# Kit de développement logiciel Claude Agent
Cette page explique comment instrumenter un agent du [SDK Claude Agent](https://docs.claude.com/en/api/agent-sdk/overview), comment les intervalles sont identifiés et comment les champs d'évaluation sont extraits.
**Rubriques**
+ [Instrumez votre agent](#claude-agent-sdk-instrument)
+ [Comment les travées sont identifiées](#claude-agent-sdk-span-identification)
+ [Comment les champs d'évaluation sont extraits](#claude-agent-sdk-extraction)
+ [À partir des enregistrements d'événements](#claude-agent-sdk-extraction-event-records)
+ [À partir des attributs span](#claude-agent-sdk-extraction-attributes)
+ [Exemples de périodes avec des enregistrements d'événements](#claude-agent-sdk-examples-with)
+ [Exemples de périodes sans enregistrement d'événements](#claude-agent-sdk-examples-without)
## Instrumez votre agent
Vous pouvez instrumenter un agent du SDK Claude Agent à l'aide de la bibliothèque **OpenInference**d'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](supported-frameworks.md#supported-frameworks-setup) 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](supported-frameworks-telemetry.md).
### À 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` et`body.output`.
+ **Appel à l'outil** : le nom de l'outil indiqué dans l'`tool.name`attribut 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` et`body.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](#claude-agent-sdk-examples-with).
### À 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 depuis`tool.name`, l'ID de l'appel d'outil depuis`tool.id`, les arguments depuis `input.value` et le résultat de`output.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](#claude-agent-sdk-examples-without).
## 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é.
**Example**
L'`openinference.span.kind`attribut (`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 ..." }
]
}
}
}
```
L'`openinference.span.kind`attribut (`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**
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é.
**Example**
L'`input.value`attribut contient l'invite de l'utilisateur et l'`output.value`attribut 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"
}
}
```
L'`input.value`attribut contient les arguments de l'outil, et l'`output.value`attribut 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"
}
}
```