Instrumentez votre agent Comment les travées sont identifiées Comment sont extraits les champs d'évaluation Exemples de plages dans la télémétrie fractionnée Exemples de plages en télémétrie unifiée

Google ADK

Cette page explique comment instrumenter un agent Google Agent Development Kit (ADK), comment les intervalles sont identifiés et comment les champs d'évaluation sont extraits.

Rubriques

Instrumentez votre agent
Comment les travées sont identifiées
Comment sont extraits les champs d'évaluation
- À partir des enregistrements d'événements
- À partir des attributs de span
Exemples de plages dans la télémétrie fractionnée
Exemples de plages en télémétrie unifiée

Instrumentez votre agent

Vous pouvez instrumenter un agent Google ADK à l'aide de la bibliothèque OpenInference d'instrumentation (openinference-instrumentation-google-adk). Cette bibliothèque émet des données télémétriques sous le nom de scopeopeninference.instrumentation.google_adk, que lit Amazon AgentCore Bedrock Evaluations.

Lorsque votre agent fonctionne avec le AWS Distro for OpenTelemetry (ADOT), par exemple sur Amazon Bedrock AgentCore Runtime, vous n'avez pas besoin d'ajouter de code d'instrumentation explicite. Il suffit d'ajouter la bibliothèque d'instrumentation aux dépendances de votre projet. ADOT le découvre au démarrage et l'active automatiquement.

Ajoutez la bibliothèque d'instrumentation à vos dépendances.

Note

Utilisez la version 0.1.13 ou une version ultérieure. Il s'agit de la première version testée avec le service d'évaluation.

requirements.txt:


openinference-instrumentation-google-adk>=0.1.13

pyproject.toml:


[project]
dependencies = [
    "openinference-instrumentation-google-adk>=0.1.13",
]

Note

L'instrumentation constitue une étape dans la mise en place de l'observabilité. Pour exporter la télémétrie à des fins d'évaluation, effectuez la configuration complète dans Configurer l'observabilité.

Comment les travées sont identifiées

Google ADK est instrumenté selon cette OpenInference convention. AgentCore Evaluations classe donc les spans à l'aide de cet attribut. openinference.span.kind

Type d'envergure	Attribut d'identification
Invoquer un agent	`openinference.span.kind`= `CHAIN` ou `AGENT`
Outil d'exécution	`openinference.span.kind` = `TOOL`
Inférence	`openinference.span.kind` = `LLM`

Google ADK émet un arbre de span imbriqué : un invocation span externe (CHAIN) enveloppe un agent_run span (AGENT), qui à son tour enveloppe les travées () et call_llm (LLM). execute_tool TOOL Le CHAIN span externe contient l'invite de l'utilisateur ; AgentCore Evaluations l'utilise comme span d'invocation de l'agent.

Comment sont extraits les champs d'évaluation

Google ADK intègre le contenu de ses conversations au format de contenu Gemini. L'invite utilisateur est imbriquée sous un new_message objet en tant que{"new_message": {"parts": [{"text": "…"}], "role": "user"}}, et la réponse de l'agent est imbriquée sous un content objet en tant que. {"content": {"parts": [{"text": "…"}], "role": "model"}} AgentCore Evaluations dévoile ces structures et joint le parts texte par de nouvelles lignes. Les définitions d'outils arrivent sous la forme d'une requête Gemini sérialisée ; AgentCore Evaluations lit les outils disponibles à partir deconfig.tools[].function_declarations[].

L'emplacement de ce contenu dépend de la manière dont la télémétrie a été collectée. L'attribut d'identification (openinference.span.kind) se trouve sur la plage dans les deux cas. Pour plus d'informations, consultez la section Configuration et diffusion de la télémétrie.

À partir des enregistrements d'événements

Grâce à la télémétrie fractionnée, AgentCore Evaluations lit le contenu de l'enregistrement de l'événement en corrélation avec chaque intervalle :

Invite utilisateur : à partir de l'enregistrement des événements du span d'invocation de l'agent, dansbody.input. AgentCore Les évaluations dévoilent le texte. new_message.parts
Réponse de l'agent : à partir de l'enregistrement des événements de l'intervalle d'agent d'appel, dansbody.output. AgentCore Les évaluations dévoilent le texte. content.parts
Appel d'outil : nom de l'outil figurant dans l'tool.nameattribut de l'étendue de l'outil d'exécution. Les arguments et le résultat de l'outil proviennent de l'enregistrement d'événements de cette plage, dans body.input etbody.output.

Pour plus d'informations, voir Exemples de plages dans la télémétrie fractionnée.

À partir des attributs de span

Grâce à la télémétrie unifiée, le même contenu reste sur la plage en tant qu'attributs :

Invite utilisateur et réponse de l'agent : depuis input.value et vers output.value le span d'invocation de l'agent. AgentCore Les évaluations déballent le texte new_message.parts et. content.parts
Appel d'outil : nom de l'outil provenant detool.name, arguments et résultats provenant de input.value etoutput.value, sur la plage d'outils d'exécution.

Pour plus d'informations, consultez la section Exemples de plages de télémétrie unifiée.

Exemples de plages dans la télémétrie fractionnée

Avec la télémétrie fractionnée, la plage contient les attributs d'identification et le contenu est enregistré dans un enregistrement d'événements corrélé. Les exemples suivants proviennent d'un agent de planification de voyages Google ADK déployé sur Amazon Bedrock Runtime. AgentCore

Note

Ces exemples ne constituent pas des étendues complètes. Ils présentent des données représentatives provenant d'une interaction réelle entre agents, certains champs étant omis et les valeurs longues tronquées pour des raisons de lisibilité.

Exemple

Invoke agent span

L'openinference.span.kindattribut (CHAIN) sur la invocation travée externe l'identifie comme une étendue d'agent d'invocation. Le span ne contient aucun contenu de conversation ; il se trouve dans l'enregistrement d'événements corrélé.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "70f2e87a30c34420",
  "name": "invocation",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "user.id": "default_user",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}

L'enregistrement d'événements corrélé contient la conversation. L'invite de l'utilisateur est imbriquée en dessous new_message.parts et la réponse de l'agent est imbriquée en dessous. content.parts


{
  "spanId": "70f2e87a30c34420",
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "scope": {
    "name": "openinference.instrumentation.google_adk"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "{\"new_message\": {\"parts\": [{\"text\": \"Hey, how can you help me\"}], \"role\": \"user\"}, \"state_delta\": null, \"run_config\": null}"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"model_version\": \"gemini-2.5-flash\", \"content\": {\"parts\": [{\"text\": \"I can help you with your travel plans! I can:\\n- Search and book flights\\n- Find and book hotels\\n- Suggest and book activities\"}], \"role\": \"model\"}, \"finish_reason\": \"STOP\"}"
        }
      ]
    }
  }
}

Execute tool span

L'openinference.span.kindattribut (TOOL) l'identifie comme une étendue d'outil d'exécution ; tool.name contient le nom de l'outil. Les arguments et le résultat de l'outil sont enregistrés dans l'enregistrement d'événement corrélé.


{
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "spanId": "9028a8dd94943456",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.type": "FunctionTool",
    "gen_ai.tool.call.id": "adk-12345678-1234-1234-1234-123456789012",
    "tool.name": "search_flights",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "9028a8dd94943456",
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "scope": {
    "name": "openinference.instrumentation.google_adk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"id\": \"adk-12345678-...\", \"name\": \"search_flights\", \"response\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}}"
        }
      ]
    }
  }
}

Inference span

L'openinference.span.kindattribut (LLM) de la call_llm plage l'identifie comme une étendue d'inférence. Il contient les métadonnées du modèle et, dans l'index llm.input_messages.* et les llm.output_messages.* attributs, les messages pour l'appel du modèle.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "1c4e5f8a2b9d0e73",
  "name": "call_llm",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "gen_ai.operation.name": "generate_content",
    "gen_ai.request.model": "gemini-2.5-flash",
    "llm.model_name": "gemini-2.5-flash",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.contents.0.message_content.text": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "model",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can help you plan your trip ...",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}

Exemples de plages en télémétrie unifiée

Grâce à la télémétrie unifiée, le même contenu reste sur les attributs de la plage et aucun enregistrement d'événement distinct n'est produit. Les exemples suivants proviennent d'un agent de planification de voyages Google ADK.

Note

Exemple

Invoke agent span

L'input.valueattribut contient l'invite de l'utilisateur (imbriquée en dessousnew_message.parts) et l'output.valueattribut contient la réponse de l'agent (imbriquée en dessouscontent.parts).


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "31ea3d5882dac680",
  "name": "invocation",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.value": "{\"user_id\": \"test_user\", \"session_id\": \"sea-nyc-trip-2-turns-google-adk-unified\", \"new_message\": {\"parts\": [{\"text\": \"Hey, how can you help me\"}], \"role\": \"user\"}}",
    "input.mime_type": "application/json",
    "output.value": "{\"model_version\": \"gemini-2.5-flash\", \"content\": {\"parts\": [{\"text\": \"I can help you plan your trip! I can:\\n- Search and book flights\\n- Find and book hotels\\n- Suggest and book activities\"}], \"role\": \"model\"}, \"finish_reason\": \"STOP\"}",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

L'input.valueattribut contient les arguments de l'outil et l'output.valueattribut contient le résultat de l'outil.


{
  "traceId": "6a4de7c376913db82e6f0f336a16731d",
  "spanId": "b64c37adefae74f0",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "adk-12345678-1234-1234-1234-123456789012",
    "tool.name": "search_flights",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "output.value": "{\"id\": \"adk-12345678-...\", \"name\": \"search_flights\", \"response\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}}",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

L'openinference.span.kindattribut (LLM) de la call_llm plage l'identifie comme une étendue d'inférence. Les messages relatifs à l'appel de modèle sont intégrés aux attributs llm.input_messages.* indexésllm.output_messages.*.


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "2d5f6a9b3c0e1f84",
  "name": "call_llm",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "gen_ai.operation.name": "generate_content",
    "gen_ai.request.model": "gemini-2.5-flash",
    "llm.model_name": "gemini-2.5-flash",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.contents.0.message_content.text": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "model",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can help you plan your trip ...",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

LlamaIndex

Kit de développement logiciel Claude Agent