Instrumez votre agent Comment les travées sont identifiées Comment les champs d'évaluation sont extraits Exemples de périodes avec des enregistrements d'événements Exemples de périodes sans enregistrement d'événements

Kit de développement logiciel Claude Agent

Cette page explique comment instrumenter un agent du SDK Claude Agent, comment les intervalles sont identifiés et comment les champs d'évaluation sont extraits.

Rubriques

Instrumez votre agent
Comment les travées sont identifiées
Comment les champs d'évaluation sont extraits
- À partir des enregistrements d'événements
- À partir des attributs span
Exemples de périodes avec des enregistrements d'événements
Exemples de périodes sans enregistrement d'événements

Instrumez votre agent

Vous pouvez instrumenter un agent du SDK Claude Agent à l'aide de la bibliothèque OpenInferenced'instrumentation (openinference-instrumentation-claude-agent-sdk). Cette bibliothèque émet des données télémétriques sous le nom de scope, qu'Amazon openinference.instrumentation.claude_agent_sdk AgentCore Bedrock Evaluations lit.

Lorsque votre agent s'exécute avec le AWS Distro for OpenTelemetry (ADOT), par exemple sur Amazon Bedrock AgentCore Runtime, vous n'avez pas besoin d'ajouter de code d'instrumentation explicite. Il suffit d'ajouter la bibliothèque d'instrumentation aux dépendances de votre projet. ADOT le découvre au démarrage et l'active automatiquement.

Ajoutez la bibliothèque d'instrumentation à vos dépendances.

Note

Utilisez la version 0.1.3 ou une version ultérieure. Il s'agit de la première version testée avec le service d'évaluation.

requirements.txt:


openinference-instrumentation-claude-agent-sdk>=0.1.3

pyproject.toml:


[project]
dependencies = [
    "openinference-instrumentation-claude-agent-sdk>=0.1.3",
]

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

Le SDK Claude Agent est doté de cette OpenInference convention. AgentCore Evaluations classe donc les intervalles à l'aide de cet attribut. openinference.span.kind

Type de travée	Attribut d'identification
Invoquer l'agent	`openinference.span.kind` = `AGENT`
Exécuter l'outil	`openinference.span.kind` = `TOOL`

Le SDK Claude Agent émet uniquement AGENT et s'TOOLétend ; il n'émet pas de plages d'inférence () distinctes. LLM Les métadonnées du modèle (nom du modèle, utilisation du jeton) et la réponse de l'agent sont répercutées sur le AGENT span lui-même.

Comment les champs d'évaluation sont extraits

Le SDK Claude Agent produit des entrées et des sorties d'agent en texte clair et épuré, de sorte que l'invite de l'utilisateur et la réponse de l'agent ne nécessitent aucune analyse spéciale. Les résultats de l'outil arrivent toutefois sous forme de blocs de contenu anthropique dans le formulaire[{"type": "text", "text": "…"}]. AgentCore Evaluations déballe ces blocs et concatène leur texte.

L'emplacement de ce contenu dépend de la manière dont la télémétrie a été collectée. L'attribut d'identification (openinference.span.kind) se trouve sur le span dans les deux cas. Pour plus d'informations, voir Spans, enregistrements d'événements et signaux de télémétrie.

À partir des enregistrements d'événements

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

Demande de l'utilisateur et réponse de l'agent : à partir de l'enregistrement des événements de l'intervalle d'appel de l'agent, dans body.input etbody.output.
Appel à l'outil : le nom de l'outil indiqué dans l'tool.nameattribut et l'ID de l'appel à l'outil à partir de tool.id l'intervalle d'exécution de l'outil. Les arguments et le résultat de l'outil proviennent de l'enregistrement des événements de cette plage, dans body.input etbody.output. AgentCore Les évaluations dévoilent les blocs de contenu Anthropic dans le résultat de l'outil.

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

À partir des attributs span

Lorsque la télémétrie n'est pas divisée, le même contenu reste sur la plage que les attributs :

Demande de l'utilisateur et réponse de l'agent : depuis input.value et output.value pendant la durée d'appel de l'agent.
Appel d'outil : le nom de l'outil depuistool.name, l'ID de l'appel d'outil depuistool.id, les arguments depuis input.value et le résultat deoutput.value, sur la durée d'exécution de l'outil. AgentCore Les évaluations dévoilent les blocs de contenu Anthropic dans le résultat de l'outil.

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 voyage du SDK Claude Agent déployé sur Amazon Bedrock Runtime. AgentCore

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'openinference.span.kindattribut (AGENT) l'identifie comme un span d'agent d'appel. Le span contient les métadonnées du modèle ; le contenu de la conversation se trouve dans l'enregistrement d'événements corrélé.


{
  "traceId": "6a292d74406894815807e2751e61dd49",
  "spanId": "a63aab3320ed8718",
  "name": "ClaudeAgentSDK.ClaudeSDKClient.receive_response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.5"
  },
  "attributes": {
    "openinference.span.kind": "AGENT",
    "llm.system": "anthropic",
    "llm.model_name": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "input.mime_type": "text/plain",
    "output.mime_type": "text/plain",
    "session.id": "sea-nyc-trip-2-turns-claude-adot"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "a63aab3320ed8718",
  "traceId": "6a292d74406894815807e2751e61dd49",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "Hey, how can you help me" }
      ]
    },
    "output": {
      "messages": [
        { "role": "assistant", "content": "Hello! I'm your travel planning assistant ..." }
      ]
    }
  }
}

Execute tool span

L'openinference.span.kindattribut (TOOL) l'identifie comme une plage d'outils d'exécution ; tool.name contient le nom de l'outil et tool.id l'ID d'appel de l'outil. Le résultat de l'outil est enregistré dans l'enregistrement d'événements corrélé sous forme de blocs de contenu anthropique, que AgentCore Evaluations dévoile.


{
  "traceId": "6a292deb7450b3155895da4f38cb579a",
  "spanId": "909dcb4eb5f851ae",
  "name": "mcp__travel__search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.5"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "mcp__travel__search_flights",
    "tool.id": "toolu_bdrk_01KmJhCRuEJJo6fswHbjCgFp",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-claude-adot"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "909dcb4eb5f851ae",
  "traceId": "6a292deb7450b3155895da4f38cb579a",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "[{\"type\": \"text\", \"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]"
        }
      ]
    }
  }
}

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

Lorsque la télémétrie n'est pas divisée, le même contenu reste dans les attributs span et aucun enregistrement d'événement distinct n'est produit. Les exemples suivants proviennent d'un agent de planification de voyages du SDK Claude Agent.

Note

Exemple

Invoke agent span

L'input.valueattribut contient l'invite de l'utilisateur et l'output.valueattribut contient la réponse de l'agent, les deux sous forme de texte brut.


{
  "traceId": "561876bb17e9eaeb2f194ee515742b2f",
  "spanId": "3b6815f5b3909a51",
  "name": "ClaudeAgentSDK.ClaudeSDKClient.receive_response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.3"
  },
  "attributes": {
    "openinference.span.kind": "AGENT",
    "llm.system": "anthropic",
    "llm.model_name": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "input.value": "Hey, how can you help me",
    "input.mime_type": "text/plain",
    "output.value": "Hi there! ... How can I help you plan your next adventure?",
    "output.mime_type": "text/plain",
    "session.id": "sea-nyc-trip-2-turns-claude-unified"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

L'input.valueattribut contient les arguments de l'outil, et l'output.valueattribut contient le résultat de l'outil sous forme de blocs de contenu anthropique, que AgentCore Evaluations déballe.


{
  "traceId": "7bb7e59a30d03fc0b9da5bf009a3b429",
  "spanId": "d27b488965bbba99",
  "name": "mcp__travel__search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.3"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "mcp__travel__search_flights",
    "tool.id": "toolu_bdrk_019yE7Gne1rZKE3UnVPAWjLq",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.mime_type": "application/json",
    "output.value": "[{\"type\": \"text\", \"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-claude-unified"
  },
  "status": {
    "code": "OK"
  }
}

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Google ADK

Built-in évaluateurs