Skip to main content
Claude Agent SDK를 사용하면 Claude 기반 에이전트 애플리케이션을 빠르게 구축할 수 있습니다. Claude 에이전트에 Weave를 통합하여 에이전트 쿼리, 모델 응답, 도구 사용, 여러 턴에 걸친 대화를 포함한 Call을 자동으로 트레이싱할 수 있습니다. Weave는 캡처한 데이터를 프로젝트의 Agents 뷰에 표시합니다.

Weave로 Claude Agent SDK 에이전트 트레이싱하기

Weave SDK는 Python용 Claude Agent SDK를 자동 패치하여 최소한의 설정으로 Claude 에이전트의 트레이스를 캡처할 수 있게 합니다.이 가이드에서는 Weave를 초기화하고 query()를 통해 MCP 도구를 사용하는 멀티턴 Claude 에이전트를 실행하는 방법을 설명합니다. Weave는 대화, 모델 Call, 도구 Call을 처음부터 끝까지 자동으로 트레이싱합니다.

사전 요구 사항

  • CoreWeave Forge 계정과 WANDB_API_KEY 환경 변수로 설정한 API 키.
  • ANTHROPIC_API_KEY 환경 변수로 설정한 Anthropic API 키.
  • Python 3.10 이상.

패키지 설치

개발 환경에 다음 패키지를 설치하세요. weave 패키지는 트레이스를 캡처하고, claude-agent-sdk는 에이전트 런타임을 제공하며, 나머지 패키지는 예시 도구를 지원합니다.

코드에서 Weave 초기화

프로젝트에 weave.init을 추가하고, CoreWeave Forge 팀 및 프로젝트 이름을 업데이트한 다음, 평소처럼 에이전트를 구축하세요. weave.init은 Claude Agent SDK의 트레이스를 자동으로 수집하고 기록하는 자동 패치 기능을 활성화합니다.이 예제는 wikipedia_search MCP 도구를 정의하고 세 턴으로 구성된 대화를 실행합니다. 각 턴은 별도의 query() 호출이지만, 이후 턴에서는 첫 번째 턴의 세션 ID와 함께 resume을 전달하여 Weave Agents 뷰에서 모든 턴을 하나의 대화로 그룹화합니다. 처음 두 턴은 Wikipedia 검색을 트리거하고, 세 번째 턴은 이전 대화 컨텍스트를 사용하여 도구 Call 없이 요약을 생성합니다.
각 query() 호출은 invoke_agent 루트 span을 생성합니다. 후속 턴은 동일한 세션으로 재개되므로, Weave는 모든 span에 동일한 gen_ai.conversation.id를 기록하고 Agents 뷰에서 하나의 대화로 그룹화합니다. 재사용할 ID는 ResultMessage.session_id에 담겨 있으며, 첫 번째 턴에서는 resume에 None을 전달할 수 있고 이 경우 새 세션이 시작됩니다.resume을 사용하지 않으면 각 턴이 자체 세션을 시작하므로 별도의 대화로 표시됩니다. 단, ClaudeSDKClient는 예외입니다. async with 블록이 유지되는 동안 하나의 세션을 열어 두므로, 동일한 클라이언트로 보내는 턴은 자동으로 하나로 그룹화됩니다. Weave는 두 방식 모두에 패치를 적용합니다.

Agents 뷰에서 에이전트 트레이스 확인하기

스크립트가 실행되면 weave.init()이 프로젝트 링크를 출력합니다. Agents 뷰를 열어 다음을 확인하세요:
  • 대화의 턴을 포함하는 세션.
  • 중첩된 chat 및 execute_tool 하위 항목이 있는 invoke_agent span으로 표시되는 각 턴.
  • 각 단계의 전체 입력, 모델, 출력, 토큰 사용량 및 도구 결과.
Weave에서 Agents 데이터를 확인하는 방법에 대한 자세한 내용은 에이전트 활동 확인하기를 참조하세요.
마지막 수정일 2026년 9월 30일