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

Questa pagina spiega come strumentare un [agente Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/), come vengono identificati gli intervalli e come vengono estratti i campi di valutazione.

 **Argomenti** 
+  [Strumenta il tuo agente](#google-adk-instrument) 
+  [Come vengono identificate le campate](#google-adk-span-identification) 
+  [Come vengono estratti i campi di valutazione](#google-adk-extraction) 
  +  [Dai registri degli eventi](#google-adk-extraction-event-records) 
  +  [Dagli attributi span](#google-adk-extraction-attributes) 
+  [L'esempio include i record degli eventi](#google-adk-examples-with) 
+  [Esempio di intervalli senza record di eventi](#google-adk-examples-without) 

## Strumenta il tuo agente
<a name="google-adk-instrument"></a>

Puoi strumentare un agente Google ADK con la libreria di **OpenInference**strumentazione (). `openinference-instrumentation-google-adk` Questa libreria emette dati di telemetria con il nome dell'ambito, letto da Amazon `openinference.instrumentation.google_adk` Bedrock Evaluations. AgentCore 

Quando il tuo agente utilizza AWS Distro for OpenTelemetry (ADOT), ad esempio su Amazon Bedrock AgentCore Runtime, non è necessario aggiungere codice di strumentazione esplicito. È sufficiente aggiungere la libreria di strumentazione alle dipendenze del progetto. ADOT la rileva all'avvio e la attiva automaticamente.

Aggiungi la libreria di strumentazione alle tue dipendenze.

**Nota**  
Usa la versione `0.1.13` o successiva. Questa è la prima versione testata con il servizio di valutazione.

 `requirements.txt`:

```
openinference-instrumentation-google-adk>=0.1.13
```

 `pyproject.toml`:

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

**Nota**  
La strumentazione è un passo nella configurazione dell'osservabilità. [Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità.](supported-frameworks.md#supported-frameworks-setup)

## Come vengono identificati gli intervalli
<a name="google-adk-span-identification"></a>

Google ADK utilizza questa OpenInference convenzione, quindi Evaluations classifica gli intervalli AgentCore utilizzando l'attributo. `openinference.span.kind`


| Tipo di intervallo | Attributo identificativo | 
| --- | --- | 
| Invoca l'agente |  `openinference.span.kind`= `CHAIN` o `AGENT`  | 
| Strumento di esecuzione |  `openinference.span.kind` = `TOOL`  | 
| Inferenza |  `openinference.span.kind` = `LLM`  | 

Google ADK emette uno span tree annidato: uno span esterno (`CHAIN`) avvolge `invocation` uno span (), che a sua volta racchiude gli `agent_run` span (`AGENT`) e (). `call_llm` `LLM` `execute_tool` `TOOL` L'outer `CHAIN` span contiene il prompt dell'utente; Evaluations lo utilizza come invoke agent span. AgentCore 

## Come vengono estratti i campi di valutazione
<a name="google-adk-extraction"></a>

Google ADK inserisce i contenuti delle conversazioni nel formato di contenuti Gemini. Il prompt utente è annidato sotto un `new_message` oggetto come`{"new_message": {"parts": [{"text": "…​"}], "role": "user"}}`, e la risposta dell'agente è annidata sotto un oggetto come. `content` `{"content": {"parts": [{"text": "…​"}], "role": "model"}}` AgentCore Evaluations elimina queste strutture e unisce il testo con delle nuove righe. `parts` Le definizioni degli strumenti arrivano come richiesta Gemini serializzata; AgentCore Evaluations legge gli strumenti disponibili da. `config.tools[].function_declarations[]`

La posizione di questo contenuto dipende da come è stata raccolta la telemetria. L'attributo identificativo (`openinference.span.kind`) è compreso nell'intervallo in entrambi i casi. Per ulteriori informazioni, consulta [Spans, record di eventi e segnali di telemetria](supported-frameworks-telemetry.md).

### Dai registri degli eventi
<a name="google-adk-extraction-event-records"></a>

Quando la telemetria viene suddivisa, AgentCore Evaluations legge il contenuto del record dell'evento correlato a ciascun intervallo:
+  **Richiesta utente**: dal record degli eventi di Invoke Agent Span, in. `body.input` AgentCore Evaluations cancella il testo. `new_message.parts`
+  **Risposta dell'agente**: dal record degli eventi dell'agente invoke span, in. `body.output` AgentCore Evaluations cancella il testo. `content.parts`
+  **Richiamata dello strumento**: il nome dello strumento dall'`tool.name`attributo nell'intervallo dello strumento di esecuzione. Gli argomenti e i risultati dello strumento provengono dal record degli eventi di quell'intervallo, in `body.input` and. `body.output`

Per esempi, vedete [Example spans with event records](#google-adk-examples-with).

### Dagli attributi span
<a name="google-adk-extraction-attributes"></a>

Quando la telemetria non viene suddivisa, lo stesso contenuto rimane nell'intervallo degli attributi:
+  **Richiesta dell'utente** e **risposta dell'agente**: da `input.value` e `output.value` sull'intervallo dell'agente Invoke. AgentCore Evaluations cancella il testo and. `new_message.parts` `content.parts`
+  **Richiamata dello strumento**: il nome dello strumento da`tool.name`, gli argomenti e il risultato di `input.value` e`output.value`, nell'intervallo dello strumento di esecuzione.

Ad esempio, vedete [Example spans without event records](#google-adk-examples-without).

## L'esempio si estende ai record degli eventi
<a name="google-adk-examples-with"></a>

Quando la telemetria viene suddivisa, l'intervallo contiene gli attributi identificativi e il contenuto risiede in un record di eventi correlato. I seguenti esempi sono tratti da un agente di pianificazione dei viaggi di Google ADK distribuito su Amazon Bedrock Runtime. AgentCore 

**Nota**  
Questi esempi non sono intervalli completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

**Example**  
L'`openinference.span.kind`attributo (`CHAIN`) sullo span esterno lo identifica come `invocation` un invoke agent span. Lo span non contiene alcun contenuto della conversazione; risiede nel record dell'evento correlato.  

```
{
  "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"
  }
}
```
Il record dell'evento correlato contiene la conversazione. Il prompt dell'utente è annidato sotto `new_message.parts` e la risposta dell'agente è annidata sotto. `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`attributo (`TOOL`) lo identifica come estensione dello strumento di esecuzione; `tool.name` contiene il nome dello strumento. Gli argomenti e i risultati dello strumento risiedono nel record degli eventi correlato.  

```
{
  "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`attributo (`LLM`) sullo `call_llm` span lo identifica come un intervallo di inferenza. Contiene i metadati del modello e, negli indici e negli `llm.output_messages.` attributi, i messaggi per la `llm.input_messages. ` chiamata al modello.  

```
{
  "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"
  }
}
```

## L'esempio si estende senza record di eventi
<a name="google-adk-examples-without"></a>

Quando la telemetria non viene suddivisa, lo stesso contenuto rimane negli attributi span e non viene prodotto alcun record di eventi separato. Gli esempi seguenti sono tratti da un agente di pianificazione viaggi di Google ADK.

**Nota**  
Questi esempi non sono esempi completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

**Example**  
L'`input.value`attributo contiene il prompt dell'utente (nidificato sotto`new_message.parts`) e l'`output.value`attributo contiene la risposta dell'agente (nidificata sotto). `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`attributo contiene gli argomenti dello strumento e l'`output.value`attributo contiene il risultato dello strumento.  

```
{
  "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`attributo (`LLM`) sullo `call_llm` span lo identifica come un intervallo di inferenza. I messaggi per la chiamata al modello sono in linea negli attributi indicizzati e. `llm.input_messages. ` `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"
  }
}
```