View a markdown version of this page

Agents à mèches - Amazon Bedrock AgentCore
Instrumez votre agentComment les travées sont identifiéesComment les champs d'évaluation sont extraitsExemples de périodes avec des enregistrements d'événementsExemples de périodes sans enregistrement d'événements

Agents à mèches

Cette page explique comment instrumenter un agent Strands Agents, comment les intervalles sont identifiés et comment les champs d'évaluation sont extraits.

Rubriques

Instrumez votre agent

Le SDK Strands Agents inclut la télémétrie intégrée et ne nécessite aucune bibliothèque d'instrumentation supplémentaire. Il produit des intervalles et des enregistrements d'événements sous le nom strands.telemetry.tracer de scope. Lorsqu'il est déployé sur Amazon Bedrock AgentCore Runtime avec le AWS Distro for OpenTelemetry (ADOT), le Runtime injecte l'session.idattribut et exporte automatiquement les intervalles et les enregistrements d'événements.

Note

L'instrumentation est l'une des étapes de la mise en place de l'observabilité. Pour exporter la télémétrie à des fins d'évaluation, effectuez la configuration complète dans Configurer l'observabilité.

Comment les travées sont identifiées

Strands définit l'gen_ai.operation.nameattribut sur chaque intervalle. Le service d'évaluation utilise cet attribut pour classer les intervalles :

Type de travée Attribut d'identification Exemple de nom d'intervalle

Invoquer l'agent

gen_ai.operation.name = invoke_agent

invoke_agent TravelAgent

Exécuter l'outil

gen_ai.operation.name = execute_tool

execute_tool search_flights

Inférence

gen_ai.operation.name = chat

chat

Comment les champs d'évaluation sont extraits

L'emplacement du contenu de la conversation dépend de la manière dont la télémétrie a été collectée. Lorsque ADOT divise la télémétrie, le contenu se trouve dans un enregistrement d'événement distinct. Lorsque la télémétrie n'est pas divisée, le contenu reste sur la plage sous forme d'événements intégrés. Pour plus d'informations, voir Spans, enregistrements d'événements et signaux de télémétrie. L'attribut d'identification (gen_ai.operation.name) se trouve sur le span dans les deux cas.

À partir des enregistrements d'événements

Lorsque la télémétrie est divisée, le service lit le contenu de l'enregistrement d'événements corrélé à chaque intervalle :

  • Demande utilisateur : à partir des messages saisis par l'agent (input.messages), le contenu du message avec un rôle d'utilisateur.

  • Réponse de l'agent : à partir des messages de sortie de l'agent (output.messages), le contenu du message avec un rôle d'assistant.

  • Appel à l'outil : nom de l'outil indiqué dans l'gen_ai.tool.nameattribut figurant sur la plage d'outils d'exécution. Les arguments et le résultat de l'outil proviennent de l'enregistrement des événements de cette plage (inputetoutput).

Pour des exemples, voir Exemples de périodes avec enregistrements d'événements.

À partir d'événements inline span

Lorsque la télémétrie n'est pas divisée, le même contenu est diffusé dans des événements d'envergure intégrés au lieu d'un enregistrement d'événement distinct :

  • Demande utilisateur : depuis l'gen_ai.user.messageévénement, l'contentattribut.

  • Réponse de l'agent : à partir de l'gen_ai.choiceévénement, de l'messageattribut.

  • Appel à l'outil : nom de l'outil indiqué dans l'gen_ai.tool.nameattribut figurant sur le span. Les arguments de l'outil proviennent de l'gen_ai.tool.messageévénement, et le résultat provient de l'gen_ai.choiceévénement.

Pour des exemples, voir Exemples de périodes sans enregistrement d'événements.

Exemples de périodes avec des enregistrements d'événements

Lorsque la télémétrie est divisée, la plage contient les attributs d'identification et le contenu est enregistré dans un enregistrement d'événements corrélé. Les exemples suivants proviennent d'un agent de planification de voyages Strands déployé sur Amazon AgentCore Bedrock Runtime.

Note

Ces exemples ne sont pas des étendues complètes. Ils présentent des données représentatives d'une interaction réelle avec un agent, certains champs étant omis et les valeurs longues tronquées pour des raisons de lisibilité.

Exemple
Invoke agent span

L'gen_ai.operation.nameattribut (invoke_agent) l'identifie comme un span d'agent d'appel. L'gen_ai.agent.toolsattribut répertorie les outils mis à la disposition de l'agent.

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

L'enregistrement d'événements corrélé contient le contenu de la conversation. L'invite de l'utilisateur est le message du rôle de l'utilisateur dansinput.messages, et la réponse de l'agent est le message du rôle de l'assistant dans. 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.nameattribut (execute_tool) l'identifie comme une plage d'outils d'exécution. L'gen_ai.tool.nameattribut contient le nom de l'outil.

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

L'enregistrement d'événements corrélé contient l'entrée (arguments) et la sortie (résultat) de l'outil.

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

Exemples de périodes sans enregistrement d'événements

Lorsque la télémétrie n'est pas divisée, le même contenu est diffusé dans les événements d'intervalle intégrés sur le span, sans enregistrement d'événement distinct. Les exemples suivants proviennent d'un agent de planification de voyages Strands.

Note

Ces exemples ne sont pas des étendues complètes. Ils présentent des données représentatives d'une interaction réelle avec un agent, certains champs étant omis et les valeurs longues tronquées pour des raisons de lisibilité.

Exemple
Invoke agent span

L'gen_ai.user.messageévénement contient l'invite de l'utilisateur et l'gen_ai.choiceévénement contient la réponse de l'agent.

{
  "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.messageévénement contient les arguments de l'outil et le gen_ai.choice résultat de l'outil.

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