# Agen Claude SDK
Halaman ini menjelaskan cara instrumen [agen SDK Claude Agent](https://docs.claude.com/en/api/agent-sdk/overview), bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi.
**Topik**
+ [Instrumen agen Anda](#claude-agent-sdk-instrument)
+ [Bagaimana rentang diidentifikasi](#claude-agent-sdk-span-identification)
+ [Bagaimana bidang evaluasi diekstraksi](#claude-agent-sdk-extraction)
+ [Dari catatan acara](#claude-agent-sdk-extraction-event-records)
+ [Dari atribut span](#claude-agent-sdk-extraction-attributes)
+ [Contoh membentang dengan catatan acara](#claude-agent-sdk-examples-with)
+ [Contoh membentang tanpa catatan peristiwa](#claude-agent-sdk-examples-without)
## Instrumen agen Anda
Anda dapat menginstrumentasikan agen Claude Agent SDK dengan library **OpenInference**instrumentasi (). `openinference-instrumentation-claude-agent-sdk` Pustaka ini memancarkan telemetri dengan nama lingkup, `openinference.instrumentation.claude_agent_sdk` yang dibaca Amazon Bedrock AgentCore Evaluations.
Saat agen Anda berjalan dengan AWS Distro for OpenTelemetry (ADOT), seperti di Amazon Bedrock AgentCore Runtime, Anda tidak perlu menambahkan kode instrumentasi eksplisit. Menambahkan pustaka instrumentasi ke dependensi proyek Anda sudah cukup. ADOT menemukannya saat startup dan mengaktifkannya secara otomatis.
Tambahkan pustaka instrumentasi ke dependensi Anda.
**catatan**
Gunakan versi `0.1.3` atau yang lebih baru. Ini adalah versi paling awal yang diuji dengan layanan evaluasi.
`requirements.txt`:
```
openinference-instrumentation-claude-agent-sdk>=0.1.3
```
`pyproject.toml`:
```
[project]
dependencies = [
"openinference-instrumentation-claude-agent-sdk>=0.1.3",
]
```
**catatan**
Instrumentasi adalah salah satu langkah dalam mengatur observabilitas. Untuk mengekspor telemetri untuk evaluasi, selesaikan pengaturan lengkap di [Siapkan observabilitas](supported-frameworks.md#supported-frameworks-setup).
## Bagaimana rentang diidentifikasi
Claude Agent SDK diinstrumentasi dengan OpenInference konvensi, sehingga AgentCore Evaluations mengklasifikasikan rentang menggunakan atribut. `openinference.span.kind`
| Jenis rentang | Mengidentifikasi atribut |
| --- | --- |
| Memanggil agen | `openinference.span.kind` = `AGENT` |
| Jalankan alat | `openinference.span.kind` = `TOOL` |
Claude Agent SDK hanya memancarkan `AGENT` dan `TOOL` membentang; itu tidak memancarkan rentang inferensi () terpisah. `LLM` Metadata model (nama model, penggunaan token) dan respons agen dilakukan pada `AGENT` rentang itu sendiri.
## Bagaimana bidang evaluasi diekstraksi
Claude Agent SDK menghasilkan input dan output agen teks biasa yang bersih, sehingga prompt pengguna dan respons agen tidak memerlukan penguraian khusus. Hasil alat, bagaimanapun, tiba sebagai blok konten Antropik dalam formulir`[{"type": "text", "text": "…"}]`. AgentCore Evaluasi membuka blok-blok ini dan menggabungkan teks mereka.
Lokasi konten ini tergantung pada bagaimana telemetri dikumpulkan. Atribut identifikasi (`openinference.span.kind`) berada pada rentang dalam kedua kasus. Untuk informasi selengkapnya, lihat [Rentang, catatan peristiwa, dan sinyal telemetri](supported-frameworks-telemetry.md).
### Dari catatan acara
Ketika telemetri dibagi, AgentCore Evaluasi membaca konten dari catatan peristiwa yang berkorelasi dengan setiap rentang:
+ **Prompt pengguna** dan **respons agen**: dari catatan peristiwa rentang agen pemanggilan, di `body.input` dan`body.output`.
+ **Panggilan alat**: nama alat dari `tool.name` atribut dan ID panggilan alat dari `tool.id` rentang alat eksekusi. Argumen dan hasil alat berasal dari catatan peristiwa rentang itu, di `body.input` dan`body.output`. AgentCore Evaluasi membuka blok konten Antropik dalam hasil alat.
Sebagai contoh, lihat [Contoh bentang dengan catatan peristiwa](#claude-agent-sdk-examples-with).
### Dari atribut span
Ketika telemetri tidak dibagi, konten yang sama tetap pada rentang sebagai atribut:
+ **Prompt pengguna** dan **respons agen**: dari `input.value` dan `output.value` pada rentang agen pemanggilan.
+ **Panggilan alat**: nama alat dari`tool.name`, ID panggilan alat dari`tool.id`, argumen dari`input.value`, dan hasil dari`output.value`, pada rentang alat eksekusi. AgentCore Evaluasi membuka blok konten Antropik dalam hasil alat.
Sebagai contoh, lihat [Contoh rentang tanpa catatan peristiwa](#claude-agent-sdk-examples-without).
## Contoh membentang dengan catatan acara
Ketika telemetri dibagi, rentang membawa atribut pengidentifikasi dan konten hidup dalam catatan peristiwa yang berkorelasi. Contoh berikut berasal dari agen perencanaan perjalanan Claude Agent SDK yang digunakan di Amazon Bedrock Runtime. AgentCore
**catatan**
Contoh-contoh ini bukan bentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.
**Example**
`openinference.span.kind`Atribut (`AGENT`) mengidentifikasi ini sebagai rentang agen pemanggilan. Rentang membawa metadata model; konten percakapan hidup dalam catatan peristiwa yang berkorelasi.
```
{
"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 ..." }
]
}
}
}
```
`openinference.span.kind`Atribut (`TOOL`) mengidentifikasi ini sebagai rentang alat eksekusi; `tool.name` memegang nama alat dan `tool.id` ID panggilan alat. Hasil alat hidup dalam catatan peristiwa yang berkorelasi sebagai blok konten Antropik, yang dibuka oleh AgentCore Evaluasi.
```
{
"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\\\": [ ... ]}\"}]"
}
]
}
}
}
```
## Contoh membentang tanpa catatan peristiwa
Ketika telemetri tidak dibagi, konten yang sama tetap pada atribut rentang dan tidak ada catatan peristiwa terpisah yang dihasilkan. Contoh berikut berasal dari agen perencanaan perjalanan Claude Agent SDK.
**catatan**
Contoh-contoh ini bukan bentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.
**Example**
`input.value`Atribut menahan prompt pengguna, dan `output.value` atribut menahan respons agen, keduanya sebagai teks biasa.
```
{
"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"
}
}
```
`input.value`Atribut memegang argumen alat, dan `output.value` atribut menyimpan hasil alat sebagai blok konten Antropik, yang dibuka oleh AgentCore Evaluasi.
```
{
"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"
}
}
```