# Google ADK
<a name="supported-frameworks-google-adk"></a>

Cette page explique comment instrumenter un [agent Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/), comment identifier les intervalles et comment les champs d'évaluation sont extraits.

 **Rubriques** 
+  [Instrumez votre agent](#google-adk-instrument) 
+  [Comment les travées sont identifiées](#google-adk-span-identification) 
+  [Comment les champs d'évaluation sont extraits](#google-adk-extraction) 
  +  [À partir des enregistrements d'événements](#google-adk-extraction-event-records) 
  +  [À partir des attributs span](#google-adk-extraction-attributes) 
+  [Exemples de périodes avec des enregistrements d'événements](#google-adk-examples-with) 
+  [Exemples de périodes sans enregistrement d'événements](#google-adk-examples-without) 

## Instrumez votre agent
<a name="google-adk-instrument"></a>

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 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](supported-frameworks.md#supported-frameworks-setup) l'observabilité.

## Comment les travées sont identifiées
<a name="google-adk-span-identification"></a>

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
<a name="google-adk-extraction"></a>

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](supported-frameworks-telemetry.md).

### À partir des enregistrements d'événements
<a name="google-adk-extraction-event-records"></a>

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, dans`body.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, dans`body.output`. AgentCore Evaluations dévoile le texte. `content.parts`
+  **Appel à l'outil** : nom de l'outil indiqué dans l'`tool.name`attribut 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` et`body.output`.

Pour des exemples, voir [Exemples de périodes avec enregistrements d'événements](#google-adk-examples-with).

### À partir des attributs span
<a name="google-adk-extraction-attributes"></a>

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 de`tool.name`, arguments et résultats de `input.value` et`output.value`, sur la durée d'exécution de l'outil.

Pour des exemples, voir [Exemples de périodes sans enregistrement d'événements](#google-adk-examples-without).

## Exemples de périodes avec des enregistrements d'événements
<a name="google-adk-examples-with"></a>

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é.

**Example**  
L'`openinference.span.kind`attribut (`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 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\"}"
        }
      ]
    }
  }
}
```
L'`openinference.span.kind`attribut (`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\": [ ... ]}}"
        }
      ]
    }
  }
}
```
L'`openinference.span.kind`attribut (`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
<a name="google-adk-examples-without"></a>

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**  
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é.

**Example**  
L'`input.value`attribut contient l'invite de l'utilisateur (imbriquée en dessous`new_message.parts`) et l'`output.value`attribut contient la réponse de l'agent (imbriquée en dessous`content.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"
  }
}
```
L'`input.value`attribut contient les arguments de l'outil et l'`output.value`attribut 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"
  }
}
```
L'`openinference.span.kind`attribut (`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. ` et`llm.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"
  }
}
```