Instrumez votre agent Comment les travées sont identifiées Comment les champs d'évaluation sont extraits Exemples de périodes avec des enregistrements d'événements Exemples de périodes sans enregistrement d'événements

Google ADK

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

Rubriques

Instrumez votre agent
Comment les travées sont identifiées
Comment les champs d'évaluation sont extraits
- À partir des enregistrements d'événements
- À partir des attributs span
Exemples de périodes avec des enregistrements d'événements
Exemples de périodes sans enregistrement d'événements

Instrumez votre agent

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

Lorsque votre agent s'exécute 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 est l'une des étapes de 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 doté de cette OpenInference convention. AgentCore Evaluations classe donc les intervalles à l'aide de cet attribut. openinference.span.kind

Type de travée	Attribut d'identification
Invoquer l'agent	`openinference.span.kind`= `CHAIN` ou `AGENT`
Exécuter l'outil	`openinference.span.kind` = `TOOL`
Inférence	`openinference.span.kind` = `LLM`

Google ADK émet un arbre d'envergure 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 La CHAIN plage externe contient l'invite de l'utilisateur ; AgentCore Evaluations l'utilise comme étendue de l'agent d'appel.

Comment les champs d'évaluation sont extraits

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 forme de demande Gemini sérialisée ; AgentCore Evaluations lit les outils disponibles à partir de. config.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 le span dans les deux cas. Pour plus d'informations, voir Spans, enregistrements d'événements et signaux de télémétrie.

À partir des enregistrements d'événements

Lorsque la télémétrie est divisée, AgentCore Evaluations lit le contenu de l'enregistrement d'événements corrélé à chaque période :

Demande de l'utilisateur : depuis l'enregistrement des événements de l'agent Invoke span, dansbody.input. AgentCore Evaluations dévoile le texte. new_message.parts
Réponse de l'agent : à partir de l'enregistrement des événements de l'agent Invoke Span, dansbody.output. AgentCore Evaluations dévoile le texte. content.parts
Appel à l'outil : nom de l'outil indiqué dans l'tool.nameattribut figurant sur la plage d'outils d'exécution. Les arguments et le résultat de l'outil proviennent de l'enregistrement des événements de cette plage, dans body.input etbody.output.

Pour des exemples, voir Exemples de périodes avec enregistrements d'événements.

À partir des attributs span

Lorsque la télémétrie n'est pas divisée, le même contenu reste sur la plage que les attributs :

Demande de l'utilisateur et réponse de l'agent : depuis input.value et output.value pendant la durée d'appel de l'agent. AgentCore Evaluations dévoile le texte new_message.parts et. content.parts
Appel à l'outil : nom de l'outil à partir detool.name, arguments et résultats de input.value etoutput.value, sur la durée d'exécution de l'outil.

Pour des exemples, voir Exemples de périodes sans enregistrement d'événements.

Exemples de périodes avec des enregistrements d'événements

Lorsque la télémétrie est divisé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 sont pas des étendues complètes. Ils présentent des données représentatives d'une interaction réelle avec un agent, 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 le invocation span externe l'identifie comme un span d'agent d'appel. 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 dessousnew_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 plage d'outils d'exécution ; tool.name contient le nom de l'outil. Les arguments et le résultat de l'outil figurent dans l'enregistrement d'événements 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 plage d'inférence. Il contient les métadonnées du modèle et, dans les index llm.input_messages. et les llm.output_messages. attributs, les messages relatifs à 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 périodes sans enregistrement d'événements

Lorsque la télémétrie n'est pas divisée, le même contenu reste dans les attributs span 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 plage d'inférence. Les messages de l'appel du modèle sont intégrés dans les attributs indexés llm.input_messages. etllm.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