View a markdown version of this page

Agenti Strands - Amazon Bedrock AgentCore
Strumenta il tuo agenteCome vengono identificati gli intervalliCome vengono estratti i campi di valutazioneL'esempio si estende ai record degli eventiL'esempio si estende senza record di eventi

Agenti Strands

Questa pagina spiega come strumentare un agente Strands Agents, come vengono identificati gli intervalli e come vengono estratti i campi di valutazione.

Argomenti

Strumenta il tuo agente

L'SDK Strands Agents include la telemetria integrata e non richiede alcuna libreria di strumentazione aggiuntiva. Produce intervalli e record di eventi con il nome dell'ambito. strands.telemetry.tracer Quando viene distribuito su Amazon Bedrock AgentCore Runtime with the AWS Distro for OpenTelemetry (ADOT), il Runtime inserisce l'session.idattributo ed esporta automaticamente gli intervalli e i record degli eventi.

Nota

La strumentazione è un passo nella configurazione dell'osservabilità. Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità.

Come vengono identificati gli intervalli

Strands imposta l'gen_ai.operation.nameattributo su ogni intervallo. Il servizio di valutazione utilizza questo attributo per classificare gli intervalli:

Tipo di intervallo Attributo identificativo Esempio di nome span

Invoca l'agente

gen_ai.operation.name = invoke_agent

invoke_agent TravelAgent

Strumento di esecuzione

gen_ai.operation.name = execute_tool

execute_tool search_flights

Inferenza

gen_ai.operation.name = chat

chat

Come vengono estratti i campi di valutazione

La posizione del contenuto della conversazione dipende da come è stata raccolta la telemetria. Quando ADOT divide la telemetria, il contenuto si trova in un record di eventi separato. Quando la telemetria non viene suddivisa, il contenuto rimane nell'intervallo come eventi in linea. Per ulteriori informazioni, consulta Intervalli, record di eventi e segnali di telemetria. L'attributo identificativo (gen_ai.operation.name) è sull'intervallo in entrambi i casi.

Dai registri degli eventi

Quando la telemetria viene suddivisa, il servizio legge il contenuto del record dell'evento correlato a ciascun intervallo:

  • Richiesta utente: dall'agente input messages (input.messages), il contenuto del messaggio con un ruolo utente.

  • Risposta dell'agente: dall'agente output messages (output.messages), il contenuto del messaggio con un ruolo di assistente.

  • Chiamata allo strumento: il nome dello strumento dall'gen_ai.tool.nameattributo nell'intervallo dello strumento di esecuzione. Gli argomenti e i risultati dello strumento provengono dal record degli eventi (inputandoutput) di quell'intervallo.

Per esempi, vedete Example spans with event records.

Da inline span events

Quando la telemetria non viene suddivisa, lo stesso contenuto viene inserito negli eventi inline span anziché in un record di eventi separato:

  • Richiesta utente: dall'evento, l'attributo. gen_ai.user.message content

  • Risposta dell'agente: dall'gen_ai.choiceevento, l'messageattributo.

  • Richiamata dello strumento: il nome dello strumento dall'gen_ai.tool.nameattributo sullo span. Gli argomenti dello strumento provengono dall'gen_ai.tool.messageevento e il risultato proviene dall'gen_ai.choiceevento.

Per esempi, vedete Example spans without event records.

L'esempio si estende ai record degli eventi

Quando la telemetria viene suddivisa, l'intervallo contiene gli attributi identificativi e il contenuto risiede in un record di eventi correlato. I seguenti esempi sono tratti da un agente di pianificazione dei viaggi di Strands distribuito su Amazon Bedrock Runtime. AgentCore

Nota

Questi esempi non sono intervalli completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

Esempio
Invoke agent span

L'gen_ai.operation.nameattributo (invoke_agent) lo identifica come un invoke agent span. L'gen_ai.agent.toolsattributo elenca gli strumenti disponibili per l'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"
  }
}

Il record dell'evento correlato contiene il contenuto della conversazione. Il prompt utente è il messaggio inserito nel input.messages ruolo utente e la risposta dell'agente è il messaggio relativo al ruolo di assistente. 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

L'gen_ai.operation.nameattributo (execute_tool) lo identifica come un intervallo di strumenti di esecuzione. L'gen_ai.tool.nameattributo contiene il nome dello strumento.

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

Il record dell'evento correlato contiene l'input (argomenti) e l'output (risultato) dello strumento.

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

L'esempio si estende senza record di eventi

Quando la telemetria non viene suddivisa, lo stesso contenuto viene archiviato negli eventi di estensione in linea dello span, senza alcun record di eventi separato. Gli esempi seguenti sono tratti da un agente di pianificazione dei viaggi di Strands.

Nota

Questi esempi non sono esempi completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

Esempio
Invoke agent span

L'gen_ai.user.messageevento contiene il prompt dell'utente e l'evento contiene la risposta dell'gen_ai.choiceagente.

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

L'gen_ai.tool.messageevento contiene gli argomenti dello strumento e l'gen_ai.choiceevento contiene il risultato dello strumento.

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