Suporte a agentes Python TypeScript suporte de agentes

Configurar a telemetria do Strands Agents para avaliações AgentCore

Esta página explica como instrumentar um agente Strands Agents, como os intervalos são identificados e como os campos de avaliação são extraídos.

Tópicos

Suporte a agentes Python
TypeScript suporte de agentes

AgentCore As avaliações oferecem suporte aos agentes Strands criados com o SDK e o SDK do Python. TypeScript Os dois produzem os mesmos tipos de extensão, atributos de identificação e layout de conteúdo, sob nomes de escopo diferentes, de modo que o serviço de avaliação os lê da mesma forma. Esta página aborda cada linguagem separadamente: para Python, consulte o suporte do agente Python; para TypeScript, consulte o suporte do TypeScript agente.

Suporte a agentes Python

Um agente Python Strands produz extensões sob o nome do escopo. strands.telemetry.tracer

Instrumente seu agente

O SDK do Strands Agents inclui telemetria integrada e não requer nenhuma biblioteca de instrumentação adicional. Ele produz períodos e registros de eventos sob o nome strands.telemetry.tracer do escopo. Quando implantado no Amazon Bedrock AgentCore Runtime com o AWS Distro for OpenTelemetry (ADOT), o Runtime injeta o session.id atributo e exporta períodos e registros de eventos automaticamente.

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

Strands define o gen_ai.operation.name atributo em cada extensão. O serviço de avaliação usa esse atributo para classificar extensões:

Tipo de extensão	Atributo de identificação	Exemplo de nome de extensão
Invoque o agente	`gen_ai.operation.name` = `invoke_agent`	`invoke_agent TravelAgent`
Ferramenta de execução	`gen_ai.operation.name` = `execute_tool`	`execute_tool search_flights`
Inferência	`gen_ai.operation.name` = `chat`	`chat`

Como os campos de avaliação são extraídos

A localização do conteúdo da conversa depende do modo de entrega da telemetria. Com a telemetria dividida, o conteúdo está em um registro de evento separado. Com a telemetria unificada, o conteúdo permanece no espaço, como eventos anexados a ele. Para obter mais informações, consulte Configuração e entrega de telemetria. O atributo de identificação (gen_ai.operation.name) está na extensão em ambos os modos.

De registros de eventos

Com a telemetria dividida, o serviço lê o conteúdo do registro do evento correlacionado a cada período:

Solicitação do usuário: a partir das mensagens de entrada do agente (input.messages), o conteúdo da mensagem com uma função de usuário.
Resposta do agente: das mensagens de saída do agente (output.messages), o conteúdo da mensagem com uma função de assistente.
Chamada de ferramenta: o nome da ferramenta a partir do gen_ai.tool.name atributo na extensão da ferramenta de execução. Os argumentos e resultados da ferramenta vêm do registro de eventos desse intervalo (inputeoutput).

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

De eventos de expansão em linha

Com a telemetria unificada, o mesmo conteúdo é transportado em eventos de abrangência em linha, em vez de um registro de evento separado:

Solicitação do usuário: do gen_ai.user.message evento, o content atributo.
Resposta do agente: do gen_ai.choice evento, o message atributo.
Chamada de ferramenta: o nome da ferramenta do gen_ai.tool.name atributo no vão. Os argumentos da ferramenta vêm do gen_ai.tool.message evento e o resultado vem do gen_ai.choice evento.

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 da Python Strands 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 gen_ai.operation.name atributo (invoke_agent) identifica isso como uma extensão do agente de invocação. O gen_ai.agent.tools atributo lista as ferramentas disponíveis para o agente.


{
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "spanId": "d24936b8989b6d42",
  "parentSpanId": "0ff3498548044e4b",
  "name": "invoke_agent TravelAgent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer",
    "version": ""
  },
  "startTimeUnixNano": 1776929864011990383,
  "endTimeUnixNano": 1776929869634304466,
  "durationNano": 5622314083,
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.system": "strands-agents",
    "gen_ai.agent.name": "TravelAgent",
    "gen_ai.request.model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
    "gen_ai.usage.input_tokens": 983,
    "gen_ai.usage.output_tokens": 232,
    "gen_ai.usage.total_tokens": 1215,
    "gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
    "session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
  },
  "status": {
    "code": "OK"
  }
}

O registro do evento correlacionado carrega o conteúdo da conversa. O prompt do usuário é a mensagem da função do usuário eminput.messages, e a resposta do agente é a mensagem da função de assistente em. output.messages


{
  "spanId": "d24936b8989b6d42",
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "Hey, how can you help me"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": {
            "message": "Hi there! I'm your travel planning assistant ...",
            "finish_reason": "end_turn"
          }
        }
      ]
    }
  }
}

Execute tool span

O gen_ai.operation.name atributo (execute_tool) identifica isso como uma extensão da ferramenta de execução. O gen_ai.tool.name atributo contém o nome da ferramenta.


{
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "spanId": "fff785ce12d6fda8",
  "parentSpanId": "96915bf5ecc78743",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer",
    "version": ""
  },
  "startTimeUnixNano": 1776929872258292842,
  "endTimeUnixNano": 1776929872259611427,
  "durationNano": 1318585,
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_hiWwdtThuD67G5cK8cp5mj",
    "gen_ai.tool.status": "success",
    "gen_ai.tool.description": "Search for available flights between cities.",
    "session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
  },
  "status": {
    "code": "OK"
  }
}

O registro do evento correlacionado carrega a entrada (argumentos) e a saída (resultado) da ferramenta.


{
  "spanId": "fff785ce12d6fda8",
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "tool",
          "content": {
            "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
            "role": "tool",
            "id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
          }
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": {
            "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
            "id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
          }
        }
      ]
    }
  }
}

Expansões de exemplo em telemetria unificada

Com a telemetria unificada, o mesmo conteúdo é transportado em eventos de abrangência em linha na extensão, sem registro de eventos separado. Os exemplos a seguir são de um agente de planejamento de viagens da Python Strands.

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 gen_ai.user.message evento contém a solicitação do usuário e a gen_ai.choice resposta do agente.


{
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "spanId": "d2ee0e4765cc773e",
  "name": "invoke_agent TravelAgent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "TravelAgent",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "events": [
    {
      "name": "gen_ai.user.message",
      "attributes": {
        "content": "[{\"text\": \"Hey, how can you help me\"}]"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "Hi there! I'm your travel planning assistant ...",
        "finish_reason": "end_turn"
      }
    }
  ]
}

Execute tool span

O gen_ai.tool.message evento contém os argumentos da ferramenta e o gen_ai.choice evento contém o resultado da ferramenta.


{
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "spanId": "0a988e27758ebb53",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_JuGterOaZfQV2c55Rp3S7C",
    "gen_ai.tool.status": "success",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "events": [
    {
      "name": "gen_ai.tool.message",
      "attributes": {
        "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
        "role": "tool",
        "id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
        "id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
      }
    }
  ]
}

TypeScript suporte de agentes

Um agente TypeScript Strands produz extensões sob o nome strands-agents do escopo. Ele emite os mesmos tipos de extensão e layout de conteúdo de um agente Python, então o serviço de avaliação o lê da mesma forma.

Instrumente seu agente

O TypeScript Strands Agents SDK (@strands-agents/sdk>= 1.5.0) inclui telemetria integrada e não requer nenhuma biblioteca de instrumentação adicional. Quando implantado no Amazon Bedrock AgentCore Runtime com o AWS Distro for OpenTelemetry (ADOT), o Runtime injeta o session.id atributo e exporta períodos e registros de eventos automaticamente. O TypeScript SDK produz extensões sob o nome do escopo. strands-agents

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

A identificação do Span é a mesma de um agente Python. O gen_ai.operation.name atributo classifica cada intervalo. Para ver os valores e exemplos de nomes de extensões, consulte Como as extensões são identificadas sob o suporte do Python.

Como os campos de avaliação são extraídos

A extração de campo é igual à de um agente Python. O conteúdo da conversa é veiculado em eventos de abrangência em linha (gen_ai.user.messagegen_ai.choice, egen_ai.tool.message). Para saber de onde cada campo é lido, consulte From inline span events sob suporte a Python.

Exemplos de períodos de um agente TypeScript

Os exemplos a seguir são de um agente de planejamento de viagens da TypeScript Strands 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 gen_ai.operation.name atributo (invoke_agent) identifica isso como uma extensão do agente de invocação e gen_ai.agent.tools lista as ferramentas disponíveis para o agente. O gen_ai.user.message evento contém a solicitação do usuário e a gen_ai.choice resposta do agente.


{
  "traceId": "6a6bc695459e41aa14a172bb41d3246d",
  "spanId": "c2c44e69bdab6ef1",
  "parentSpanId": "f18d96d107e793ba",
  "name": "invoke_agent Strands Agent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands-agents",
    "version": ""
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "Strands Agent",
    "gen_ai.system": "strands-agents",
    "gen_ai.request.model": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "events": [
    {
      "name": "gen_ai.user.message",
      "attributes": {
        "content": "[{\"text\": \"Hey, how can you help me\"}]"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "Hello! I'm your travel planning assistant, and I can help you with the following: ..."
      }
    }
  ]
}

Execute tool span

O gen_ai.operation.name atributo (execute_tool) identifica isso como uma extensão da ferramenta de execução; gen_ai.tool.name contém o nome da ferramenta. O gen_ai.tool.message evento contém os argumentos da ferramenta e o gen_ai.choice evento contém o resultado da ferramenta.


{
  "traceId": "6a6bc69e6eaa1e994481bef349f4c72e",
  "spanId": "4227ac5525f22dd2",
  "parentSpanId": "8a989e0dbb9dc22f",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands-agents",
    "version": ""
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ",
    "gen_ai.tool.status": "success",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "events": [
    {
      "name": "gen_ai.tool.message",
      "attributes": {
        "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
        "role": "tool",
        "id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
        "id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ"
      }
    }
  ]
}

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

Frameworks compatíveis

LangGraph