Instrumente seu agente Como os vãos são identificados Como os campos de avaliação são extraídos Exemplos de períodos com registros de eventos Exemplos de períodos sem registros de eventos

Google ADK

Esta página explica 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 vãos são identificados
Como os campos de avaliação são extraídos
- De registros de eventos
- De atributos de extensão
Exemplos de períodos com registros de eventos
Exemplos de períodos sem registros de eventos

Instrumente seu agente

Você pode instrumentar um agente do Google ADK com a biblioteca de OpenInferenceinstrumentaçã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 observabilidade.

Como os vãos são identificados

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

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.

De registros de eventos

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, embody.input. AgentCore As avaliações desembrulham o texto. new_message.parts
Resposta do agente: do registro de eventos do invoke agent span, embody.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.

De atributos de extensão

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 detool.name, os argumentos e o resultado de input.value eoutput.value, na extensão da ferramenta de execução.

Por exemplo, consulte Exemplos de períodos sem registros de eventos.

Exemplos de períodos com registros de eventos

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.

exemplo

Invoke agent span

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

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

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

Exemplos de períodos sem registros de eventos

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.

exemplo

Invoke agent span

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