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

Esta página explica como instrumentar um [agente do Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/), como os intervalos são identificados e como os campos de avaliação são extraídos.

 **Tópicos** 
+  [Instrumente seu agente](#google-adk-instrument) 
+  [Como os vãos são identificados](#google-adk-span-identification) 
+  [Como os campos de avaliação são extraídos](#google-adk-extraction) 
  +  [De registros de eventos](#google-adk-extraction-event-records) 
  +  [De atributos de extensão](#google-adk-extraction-attributes) 
+  [Exemplos de períodos com registros de eventos](#google-adk-examples-with) 
+  [Exemplos de períodos sem registros de eventos](#google-adk-examples-without) 

## Instrumente seu agente
<a name="google-adk-instrument"></a>

Você pode instrumentar um agente do Google ADK com a biblioteca de **OpenInference**instrumentação (). `openinference-instrumentation-google-adk` Essa biblioteca emite telemetria sob o nome do escopo, `openinference.instrumentation.google_adk` que o Amazon Bedrock AgentCore Evaluations lê.

Quando seu agente é executado com a AWS Distro for OpenTelemetry (ADOT), como no Amazon Bedrock AgentCore Runtime, você não precisa adicionar código de instrumentação explícito. Adicionar a biblioteca de instrumentação às dependências do seu projeto é suficiente. O ADOT o descobre na inicialização e o ativa automaticamente.

Adicione a biblioteca de instrumentação às suas dependências.

**nota**  
Use a versão `0.1.13` ou posterior. Essa é a versão mais antiga testada com o serviço de avaliação.

 `requirements.txt`:

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

 `pyproject.toml`:

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

**nota**  
A instrumentação é uma etapa na configuração da observabilidade. Para exportar a telemetria para avaliação, conclua a configuração completa em [Configurar](supported-frameworks.md#supported-frameworks-setup) observabilidade.

## Como os vãos são identificados
<a name="google-adk-span-identification"></a>

O Google ADK é equipado com a OpenInference convenção, então as AgentCore avaliações classificam os períodos usando o atributo. `openinference.span.kind`


| Tipo de extensão | Atributo de identificação | 
| --- | --- | 
| Invocar agente |  `openinference.span.kind`= `CHAIN` ou `AGENT`  | 
| Ferramenta de execução |  `openinference.span.kind` = `TOOL`  | 
| Inferência |  `openinference.span.kind` = `LLM`  | 

O Google ADK emite uma árvore de extensão aninhada: uma `invocation` extensão externa (`CHAIN`) envolve uma `agent_run` extensão (`AGENT`), que, por sua vez, envolve as extensões () e `call_llm` (`LLM`). `execute_tool` `TOOL` O `CHAIN` intervalo externo carrega o prompt do usuário; o AgentCore Evaluations o usa como o intervalo do agente de invocação.

## Como os campos de avaliação são extraídos
<a name="google-adk-extraction"></a>

O Google ADK agrupa o conteúdo da conversa no formato de conteúdo Gemini. O prompt do usuário está aninhado em um `new_message` objeto como`{"new_message": {"parts": [{"text": "…​"}], "role": "user"}}`, e a resposta do agente está aninhada em um `content` objeto como. `{"content": {"parts": [{"text": "…​"}], "role": "model"}}` AgentCore As avaliações desembrulham essas estruturas e unem o `parts` texto com novas linhas. As definições de ferramentas chegam como uma solicitação serializada do Gemini; o AgentCore Evaluations lê as ferramentas disponíveis em. `config.tools[].function_declarations[]`

A localização desse conteúdo depende de como a telemetria foi coletada. O atributo de identificação (`openinference.span.kind`) está no intervalo em ambos os casos. Para obter mais informações, consulte [Espaços, registros de eventos e sinais de telemetria](supported-frameworks-telemetry.md).

### De registros de eventos
<a name="google-adk-extraction-event-records"></a>

Quando a telemetria é dividida, o AgentCore Evaluations lê o conteúdo do registro do evento correlacionado a cada período:
+  **Solicitação do usuário**: do registro de eventos do invoke agent span, em`body.input`. AgentCore As avaliações desembrulham o texto. `new_message.parts`
+  **Resposta do agente**: do registro de eventos do invoke agent span, em`body.output`. AgentCore As avaliações desembrulham o texto. `content.parts`
+  **Chamada de ferramenta**: o nome da ferramenta a partir do `tool.name` atributo na extensão da ferramenta de execução. Os argumentos e o resultado da ferramenta vêm do registro de eventos desse intervalo, em `body.input` `body.output` e.

Para ver exemplos, consulte [Exemplos de períodos com registros de eventos](#google-adk-examples-with).

### De atributos de extensão
<a name="google-adk-extraction-attributes"></a>

Quando a telemetria não é dividida, o mesmo conteúdo permanece na extensão como atributos:
+  **Solicitação do usuário** e **resposta do agente**: de `input.value` e `output.value` sobre o período de invocação do agente. AgentCore As avaliações desembrulham o texto e. `new_message.parts` `content.parts`
+  **Chamada** de ferramenta: o nome da ferramenta de`tool.name`, os argumentos e o resultado de `input.value` e`output.value`, na extensão da ferramenta de execução.

Por [exemplo, consulte Exemplos de períodos sem registros de eventos](#google-adk-examples-without).

## Exemplos de períodos com registros de eventos
<a name="google-adk-examples-with"></a>

Quando a telemetria é dividida, o intervalo carrega os atributos de identificação e o conteúdo fica em um registro de evento correlacionado. Os exemplos a seguir são de um agente de planejamento de viagens do Google ADK implantado no Amazon Bedrock Runtime. AgentCore 

**nota**  
Esses exemplos não são extensões completas. Eles mostram dados representativos de uma interação real do agente, com alguns campos omitidos e valores longos truncados para facilitar a leitura.

**Example**  
O `openinference.span.kind` atributo (`CHAIN`) no `invocation` intervalo externo identifica isso como um intervalo do agente de invocação. O intervalo não contém conteúdo de conversação; ele reside no registro do evento correlacionado.  

```
{
  "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"
  }
}
```
O registro do evento correlacionado carrega a conversa. O prompt do usuário está aninhado abaixo e `new_message.parts` a resposta do agente está aninhada abaixo. `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\"}"
        }
      ]
    }
  }
}
```
O `openinference.span.kind` atributo (`TOOL`) identifica isso como uma extensão da ferramenta de execução; `tool.name` contém o nome da ferramenta. Os argumentos e o resultado da ferramenta estão no registro do evento correlacionado.  

```
{
  "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\": [ ... ]}}"
        }
      ]
    }
  }
}
```
O `openinference.span.kind` atributo (`LLM`) no `call_llm` intervalo identifica isso como um intervalo de inferência. Ele carrega os metadados do modelo e, nos `llm.output_messages.` atributos `llm.input_messages. ` e indexados, as mensagens para a chamada do modelo.  

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

## Exemplos de períodos sem registros de eventos
<a name="google-adk-examples-without"></a>

Quando a telemetria não é dividida, o mesmo conteúdo permanece nos atributos de span e nenhum registro de evento separado é produzido. Os exemplos a seguir são de um agente de planejamento de viagens do Google ADK.

**nota**  
Esses exemplos não são extensões completas. Eles mostram dados representativos de uma interação real do agente, com alguns campos omitidos e valores longos truncados para facilitar a leitura.

**Example**  
O `input.value` atributo contém o prompt do usuário (aninhado abaixo`new_message.parts`) e o `output.value` atributo contém a resposta do agente (aninhado abaixo`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"
  }
}
```
O `input.value` atributo contém os argumentos da ferramenta e o `output.value` atributo contém o resultado da ferramenta.  

```
{
  "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"
  }
}
```
O `openinference.span.kind` atributo (`LLM`) no `call_llm` intervalo identifica isso como um intervalo de inferência. As mensagens para a chamada do modelo estão embutidas no índice `llm.input_messages. ` e `llm.output_messages.` nos atributos.  

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