Instrumente seu agente Como os intervalos são identificados Como os campos de avaliação são extraídos Exemplos de extensões em telemetria dividida Expansões de exemplo em telemetria unificada

Google ADK

Nesta página, explicamos como instrumentar um agente do Google Agent Development Kit (ADK), como os intervalos são identificados e como os campos de avaliação são extraídos.

Tópicos

Instrumente seu agente
Como os intervalos são identificados
Como os campos de avaliação são extraídos
- De registros de eventos
- Dos atributos de extensão
Expansões de exemplo em telemetria dividida
Expansões de exemplo em telemetria unificada

Instrumente seu agente

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 escopoopeninference.instrumentation.google_adk, que a Amazon Bedrock AgentCore Evaluations lê.

Quando seu agente executa com o 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 observabilidade.

Como os intervalos são identificados

O Google ADK é instrumentado com a OpenInference convenção, então o AgentCore Evaluations classifica os intervalos usando o atributo. openinference.span.kind

Tipo de extensão	Atributo de identificação
Invoque o 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

O Google ADK agrupa o conteúdo da conversa no formato de conteúdo Gemini. O prompt do usuário está aninhado sob um new_message objeto como{"new_message": {"parts": [{"text": "…"}], "role": "user"}}, e a resposta do agente está aninhada sob 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 Configuração e entrega de telemetria.

De registros de eventos

Com 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 invocar o agente span, embody.input. AgentCore As avaliações revelam o texto. new_message.parts
Resposta do agente: do registro de eventos do invocar o agente span, embody.output. AgentCore As avaliações revelam 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 resultados da ferramenta vêm do registro de eventos desse período, em body.input body.output e.

Para obter mais informações, consulte Exemplos de extensões em telemetria dividida.

Dos atributos de extensão

Com a telemetria unificada, o mesmo conteúdo permanece na mesma extensão dos atributos:

Solicitação do usuário e resposta do agente: de input.value e output.value para o intervalo do agente de invocação. AgentCore As avaliações revelam o texto e. new_message.parts content.parts
Chamada de ferramenta: o nome da ferramenta detool.name, os argumentos e o resultado de input.value eoutput.value, no intervalo da ferramenta de execução.

Para obter mais informações, consulte Exemplos de extensões em telemetria unificada.

Exemplos de extensões em telemetria dividida

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

exemplo

Invoke agent span

O openinference.span.kind atributo (CHAIN) na invocation extensão externa identifica isso como uma extensão do agente de invocação. O intervalo não contém conteúdo de conversa; ele está 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 acompanha a conversa. O prompt do usuário está aninhado em e new_message.parts a resposta do agente está aninhada em. 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

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 resultados 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\": [ ... ]}}"
        }
      ]
    }
  }
}

Inference span

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

Expansões de exemplo em telemetria unificada

Com a telemetria unificada, o mesmo conteúdo permanece nos atributos de extensão 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.

exemplo

Invoke agent span

O input.value atributo contém o prompt do usuário (aninhado emnew_message.parts) e o output.value atributo contém a resposta do agente (aninhado emcontent.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

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

Inference span

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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

LlamaIndex

SDK do agente Claude