# Claude 에이전트 SDK
이 페이지에서는 [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) 에이전트를 계측하는 방법, 스팬을 식별하는 방법, 평가 필드를 추출하는 방법을 설명합니다.
**주제**
+ [에이전트 계측](#claude-agent-sdk-instrument)
+ [스팬 식별 방법](#claude-agent-sdk-span-identification)
+ [평가 필드 추출 방법](#claude-agent-sdk-extraction)
+ [이벤트 레코드에서](#claude-agent-sdk-extraction-event-records)
+ [스팬 속성에서](#claude-agent-sdk-extraction-attributes)
+ [이벤트 레코드가 있는 스팬의 예](#claude-agent-sdk-examples-with)
+ [이벤트 레코드가 없는 스팬의 예](#claude-agent-sdk-examples-without)
## 에이전트 계측
**OpenInference** 계측 라이브러리()를 사용하여 Claude Agent SDK 에이전트를 계측할 수 있습니다`openinference-instrumentation-claude-agent-sdk`. 이 라이브러리는 Amazon Bedrock AgentCore Evaluations`openinference.instrumentation.claude_agent_sdk`가 읽는 범위 이름 로 원격 측정을 내보냅니다.
Amazon Bedrock AgentCore 런타임에서와 같이 에이전트가 AWS Distro for OpenTelemetry(ADOT)를 사용하여 실행되는 경우 명시적 계측 코드를 추가할 필요가 없습니다. 프로젝트의 종속성에 계측 라이브러리를 추가하면 충분합니다. ADOT는 시작 시 이를 검색하고 자동으로 활성화합니다.
종속성에 계측 라이브러리를 추가합니다.
**참고**
버전 `0.1.3` 이상을 사용합니다. 평가 서비스로 테스트한 가장 빠른 버전입니다.
`requirements.txt`:
```
openinference-instrumentation-claude-agent-sdk>=0.1.3
```
`pyproject.toml`:
```
[project]
dependencies = [
"openinference-instrumentation-claude-agent-sdk>=0.1.3",
]
```
**참고**
계측은 관찰성을 설정하는 한 단계입니다. 평가를 위해 원격 측정을 내보내려면 [관찰성 설정](supported-frameworks.md#supported-frameworks-setup)에서 전체 설정을 완료합니다.
## 스팬 식별 방법
Claude Agent SDK는 OpenInference 규칙으로 계측되므로 AgentCore Evaluations는 `openinference.span.kind` 속성을 사용하여 스팬을 분류합니다.
| 범위 유형 | 속성 식별 |
| --- | --- |
| 에이전트 호출 | `openinference.span.kind` = `AGENT` |
| 도구 실행 | `openinference.span.kind` = `TOOL` |
Claude Agent SDK는 `AGENT` 및 스`TOOL`팬만 내보내고 별도의 추론(`LLM`) 스팬은 내보내지 않습니다. 모델 메타데이터(모델 이름, 토큰 사용)와 에이전트 응답은 `AGENT`스팬 자체에서 전달됩니다.
## 평가 필드 추출 방법
Claude 에이전트 SDK는 깨끗한 일반 텍스트 에이전트 입력 및 출력을 생성하므로 사용자 프롬프트와 에이전트 응답에는 특별한 구문 분석이 필요하지 않습니다. 그러나 도구 결과는 형식으로 Anthropic 콘텐츠 블록으로 도착합니다`[{"type": "text", "text": "…"}]`. AgentCore Evaluations는 이러한 블록을 언래핑하고 텍스트를 연결합니다.
이 콘텐츠의 위치는 원격 측정이 수집된 방식에 따라 달라집니다. 식별 속성(`openinference.span.kind`)은 두 경우 모두 스팬에 있습니다. 자세한 내용은 [스팬, 이벤트 레코드 및 원격 측정 신호를](supported-frameworks-telemetry.md) 참조하세요.
### 이벤트 레코드에서
원격 측정이 분할되면 AgentCore Evaluations는 각 범위와 상관관계가 있는 이벤트 레코드에서 콘텐츠를 읽습니다.
+ **사용자 프롬프트** 및 **에이전트 응답**: `body.input` 및의 에이전트 스팬 호출 이벤트 레코드에서`body.output`.
+ **도구 호출**: `tool.name` 속성의 도구 이름과 실행 도구 범위의 `tool.id`의 도구 호출 ID입니다. 도구 인수와 결과는 `body.input` 및의 해당 스팬의 이벤트 레코드에서 가져옵니다`body.output`. AgentCore Evaluations는 도구 결과에서 Anthropic 콘텐츠 블록의 래핑을 해제합니다.
예제는 [이벤트 레코드가 있는 스팬 예제를 참조하세요](#claude-agent-sdk-examples-with).
### 스팬 속성에서
원격 측정이 분할되지 않으면 속성과 동일한 콘텐츠가 스팬에 유지됩니다.
+ **사용자 프롬프트** 및 **에이전트 응답**: 에이전트 간접 호출 스팬에서 `input.value` 및 `output.value`에서.
+ **도구 호출**: 실행 도구 범위의의 도구 이름`tool.name`,의 도구 호출 ID`output.value`,의 `tool.id`인수 `input.value`및의 결과입니다. AgentCore Evaluations는 도구 결과에서 Anthropic 콘텐츠 블록의 래핑을 해제합니다.
예제는 [이벤트 레코드가 없는 스팬 예제를 참조하세요](#claude-agent-sdk-examples-without).
## 이벤트 레코드가 있는 스팬의 예
원격 측정이 분할되면 스팬은 식별 속성을 전달하고 콘텐츠는 상관관계가 있는 이벤트 레코드에 있습니다. 다음 예제는 Amazon Bedrock AgentCore 런타임에 배포된 Claude Agent SDK 여행 계획 에이전트에서 가져온 것입니다.
**참고**
이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.
**Example**
`openinference.span.kind` 속성(`AGENT`)은 이를 호출 에이전트 범위로 식별합니다. 스팬에는 모델 메타데이터가 포함되며, 대화 콘텐츠는 상관관계가 있는 이벤트 레코드에 있습니다.
```
{
"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` 속성(`TOOL`)은 이를 실행 도구 범위로 식별합니다.는 도구 이름과 도구 호출 ID`tool.id`를 `tool.name` 보유합니다. 도구 결과는 상관관계가 있는 이벤트 레코드에 AgentCore Evaluations가 래핑 해제하는 Anthropic 콘텐츠 블록으로 존재합니다.
```
{
"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\\\": [ ... ]}\"}]"
}
]
}
}
}
```
## 이벤트 레코드가 없는 스팬의 예
원격 측정이 분할되지 않으면 동일한 콘텐츠가 스팬 속성에 유지되고 별도의 이벤트 레코드가 생성되지 않습니다. 다음은 Claude Agent SDK 여행 계획 에이전트의 예입니다.
**참고**
이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.
**Example**
`input.value` 속성에는 사용자 프롬프트가 저장되고 `output.value` 속성에는 에이전트 응답이 모두 일반 텍스트로 저장됩니다.
```
{
"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` 속성에는 도구 인수가 저장되고 `output.value` 속성에는 도구 결과가 Anthropic 콘텐츠 블록으로 저장되며,이 블록은 AgentCore Evaluations에서 언래핑합니다.
```
{
"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"
}
}
```