도구 호출 처리

이 페이지는 도구 호출 생명주기를 다룹니다: Claude의 응답에서 tool_use 블록 읽기, 응답에서 tool_result 블록 포맷하기, 오류 신호 보내기. 이를 자동으로 처리하는 SDK 추상화는 Tool Runner를 참조하세요.

Claude의 응답은 클라이언트 도구를 사용하는지 서버 도구를 사용하는지에 따라 다릅니다.

클라이언트 도구의 결과 처리

응답은 tool_use의 stop_reason과 다음을 포함하는 하나 이상의 tool_use 콘텐츠 블록을 가집니다:

• id: 이 특정 도구 사용 블록의 고유 식별자입니다. 나중에 도구 결과를 일치시키는 데 사용됩니다.
• name: 사용 중인 도구의 이름입니다.
• input: 도구에 전달되는 입력을 포함하는 객체로, 도구의 input_schema를 준수합니다.

클라이언트 도구에 대한 도구 사용 응답을 받으면 다음을 수행해야 합니다:

1. tool_use 블록에서 name, id, input을 추출합니다.
2. 해당 도구 이름에 해당하는 코드베이스에서 실제 도구를 실행하고, 도구 input을 전달합니다.
3. role이 user이고 tool_result 유형을 포함하는 content 블록이 있는 새 메시지를 보내 대화를 계속합니다:
   • tool_use_id: 이것이 결과인 도구 사용 요청의 id입니다.
   • content: 도구의 결과로, 문자열(예: "content": "15 degrees"), 중첩된 콘텐츠 블록의 목록(예: "content": [{"type": "text", "text": "15 degrees"}]), 또는 문서 블록의 목록(예: "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}])입니다. 이러한 콘텐츠 블록은 text, image, 또는 document 유형을 사용할 수 있습니다.
   • is_error (선택사항): 도구 실행으로 인해 오류가 발생한 경우 true로 설정합니다.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ tool_result 전의 텍스트
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ tool_result 후의 텍스트
  ]
}

도구 결과를 받은 후 Claude는 해당 정보를 사용하여 원래 사용자 프롬프트에 대한 응답 생성을 계속합니다.

서버 도구의 결과 처리

Claude는 도구를 내부적으로 실행하고 추가 사용자 상호작용 없이 결과를 응답에 직접 통합합니다.

is_error로 오류 처리

Claude와 함께 도구를 사용할 때 발생할 수 있는 몇 가지 다른 유형의 오류가 있습니다:

다음 단계

• 한 번에 여러 도구를 실행하려면 Parallel tool use를 참조하세요.
• 이 루프를 자동화하는 SDK 추상화는 Tool Runner를 참조하세요.
• 전체 도구 사용 워크플로우는 Define tools를 참조하세요.