View a markdown version of this page

Claude 에이전트 SDK - Amazon Bedrock AgentCore
에이전트 계측스팬 식별 방법평가 필드 추출 방법이벤트 레코드가 있는 스팬의 예이벤트 레코드가 없는 스팬의 예

Claude 에이전트 SDK

이 페이지에서는 Claude Agent SDK 에이전트를 계측하는 방법, 스팬을 식별하는 방법, 평가 필드를 추출하는 방법을 설명합니다.

주제

에이전트 계측

OpenInference 계측 라이브러리()를 사용하여 Claude Agent SDK 에이전트를 계측할 수 있습니다openinference-instrumentation-claude-agent-sdk. 이 라이브러리는 Amazon Bedrock AgentCore Evaluationsopeninference.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",
]
참고

계측은 관찰성을 설정하는 한 단계입니다. 평가를 위해 원격 측정을 내보내려면 관찰성 설정에서 전체 설정을 완료합니다.

스팬 식별 방법

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)은 두 경우 모두 스팬에 있습니다. 자세한 내용은 스팬, 이벤트 레코드 및 원격 측정 신호를 참조하세요.

이벤트 레코드에서

원격 측정이 분할되면 AgentCore Evaluations는 각 범위와 상관관계가 있는 이벤트 레코드에서 콘텐츠를 읽습니다.

  • 사용자 프롬프트 및 에이전트 응답: body.input 및의 에이전트 스팬 호출 이벤트 레코드에서body.output.

  • 도구 호출: tool.name 속성의 도구 이름과 실행 도구 범위의 tool.id의 도구 호출 ID입니다. 도구 인수와 결과는 body.input 및의 해당 스팬의 이벤트 레코드에서 가져옵니다body.output. AgentCore Evaluations는 도구 결과에서 Anthropic 콘텐츠 블록의 래핑을 해제합니다.

예제는 이벤트 레코드가 있는 스팬 예제를 참조하세요.

스팬 속성에서

원격 측정이 분할되지 않으면 속성과 동일한 콘텐츠가 스팬에 유지됩니다.

  • 사용자 프롬프트 및 에이전트 응답: 에이전트 간접 호출 스팬에서 input.value 및 output.value에서.

  • 도구 호출: 실행 도구 범위의의 도구 이름tool.name,의 도구 호출 IDoutput.value,의 tool.id인수 input.value및의 결과입니다. AgentCore Evaluations는 도구 결과에서 Anthropic 콘텐츠 블록의 래핑을 해제합니다.

예제는 이벤트 레코드가 없는 스팬 예제를 참조하세요.

이벤트 레코드가 있는 스팬의 예

원격 측정이 분할되면 스팬은 식별 속성을 전달하고 콘텐츠는 상관관계가 있는 이벤트 레코드에 있습니다. 다음 예제는 Amazon Bedrock AgentCore 런타임에 배포된 Claude Agent SDK 여행 계획 에이전트에서 가져온 것입니다.

참고

이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.

예
Invoke agent span

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 ..." }
      ]
    }
  }
}
Execute tool span

openinference.span.kind 속성(TOOL)은 이를 실행 도구 범위로 식별합니다.는 도구 이름과 도구 호출 IDtool.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 여행 계획 에이전트의 예입니다.

참고

이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.

예
Invoke agent span

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"
  }
}
Execute tool span

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"
  }
}