Instrumen agen Anda Bagaimana rentang diidentifikasi Bagaimana bidang evaluasi diekstraksi Contoh membentang dengan catatan acara Contoh membentang tanpa catatan peristiwa

Agen Claude SDK

Halaman ini menjelaskan cara instrumen agen SDK Claude Agent, bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi.

Topik

Instrumen agen Anda
Bagaimana rentang diidentifikasi
Bagaimana bidang evaluasi diekstraksi
- Dari catatan acara
- Dari atribut span
Contoh membentang dengan catatan acara
Contoh membentang tanpa catatan peristiwa

Instrumen agen Anda

Anda dapat menginstrumentasikan agen Claude Agent SDK dengan library OpenInferenceinstrumentasi (). 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.

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.

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 danbody.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 danbody.output. AgentCore Evaluasi membuka blok konten Antropik dalam hasil alat.

Sebagai contoh, lihat Contoh bentang dengan catatan peristiwa.

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 daritool.name, ID panggilan alat daritool.id, argumen dariinput.value, dan hasil darioutput.value, pada rentang alat eksekusi. AgentCore Evaluasi membuka blok konten Antropik dalam hasil alat.

Sebagai contoh, lihat Contoh rentang tanpa catatan peristiwa.

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.

contoh

Invoke agent span

openinference.span.kindAtribut (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 ..." }
      ]
    }
  }
}

Execute tool span

openinference.span.kindAtribut (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.

contoh

Invoke agent span

input.valueAtribut 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"
  }
}

Execute tool span

input.valueAtribut 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"
  }
}

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Google ADK

Built-in evaluator