View a markdown version of this page

Strands Agents - Amazon Bedrock AgentCore
Instrumente seu agenteComo os vãos são identificadosComo os campos de avaliação são extraídosExemplos de períodos com registros de eventosExemplos de períodos sem registros de eventos

Strands Agents

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

Instrumente seu agente

O SDK do Strands Agents inclui telemetria integrada e não requer biblioteca de instrumentação adicional. Ele produz intervalos e registros de eventos sob o nome strands.telemetry.tracer do escopo. Quando implantado no Amazon Bedrock AgentCore Runtime com a AWS Distro for OpenTelemetry (ADOT), o Runtime injeta o session.id atributo e exporta intervalos 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 vãos 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 os períodos:

Tipo de extensão Atributo de identificação Exemplo de nome de extensão

Invocar 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 de como a telemetria foi coletada. Quando o ADOT divide a telemetria, o conteúdo está em um registro de evento separado. Quando a telemetria não é dividida, o conteúdo permanece no intervalo como eventos embutidos. Para obter mais informações, consulte Espaços, registros de eventos e sinais de telemetria. O atributo de identificação (gen_ai.operation.name) está no intervalo em ambos os casos.

De registros de eventos

Quando 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 o resultado da ferramenta vêm do registro de eventos desse intervalo (inputeoutput).

Para ver exemplos, consulte Exemplos de períodos com registros de eventos.

De eventos de extensão em linha

Quando a telemetria não é dividida, o mesmo conteúdo é transmitido em eventos de extensão 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 a partir do gen_ai.tool.name atributo na extensão. Os argumentos da ferramenta vêm do gen_ai.tool.message evento e o resultado vem do gen_ai.choice evento.

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

Exemplos de períodos sem registros de eventos

Quando a telemetria não é dividida, o mesmo conteúdo é transmitido em eventos de intervalo em linha no intervalo, sem registro de evento separado. Os exemplos a seguir são de um agente de planejamento de viagens da 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 o prompt do usuário e o gen_ai.choice evento contém a 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"
      }
    }
  ]
}