Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
이 페이지는 도구 사용의 개념을 설명합니다: 도구가 실행되는 위치, 에이전트 루프의 작동 방식, 그리고 도구 사용이 적합한 접근 방식인 경우. 실습 안내는 튜토리얼 또는 구현 가이드를 참조하세요.
도구 사용은 애플리케이션과 모델 간의 계약입니다. 어떤 작업을 사용할 수 있는지, 입력과 출력의 형태가 어떠한지를 지정하면, Claude가 언제 어떻게 호출할지를 결정합니다. 모델은 스스로 아무것도 실행하지 않습니다. 구조화된 요청을 내보내면, 여러분의 코드(또는 Anthropic의 서버)가 작업을 실행하고, 결과가 대화로 다시 흘러들어옵니다.
이 계약은 모델이 텍스트 생성기보다는 호출하는 함수처럼 동작하게 만듭니다. 고전적인 API 경험을 가진 엔지니어는 다른 타입 인터페이스와 동일한 방식으로 도구 사용을 통합할 수 있습니다: 스키마를 정의하고, 콜백을 처리하고, 결과를 반환합니다. 차이점은 반대편의 호출자가 대화를 기반으로 어떤 함수를 호출할지 선택하는 언어 모델이라는 것입니다.
도구가 서로 다른 주요 축은 코드가 실행되는 위치입니다. 모든 도구는 세 가지 범주 중 하나에 속하며, 해당 범주가 애플리케이션이 담당해야 할 사항을 결정합니다.
스키마를 작성하고, 코드를 실행하고, 결과를 반환하는 것은 모두 여러분의 몫입니다. 이것이 핵심입니다: 도구 사용 트래픽의 대부분은 애플리케이션별 로직을 호출하는 사용자 정의 도구입니다.
Claude가 여러분의 도구 중 하나를 사용하기로 결정하면, API 응답에는 도구 이름과 인수의 JSON 객체가 포함된 tool_use 블록이 포함됩니다. 애플리케이션은 해당 인수를 추출하고, 작업(데이터베이스 쿼리, HTTP 호출, 파일 쓰기 등 도구가 수행하는 모든 작업)을 실행하고, 다음 요청의 tool_result 블록에 출력을 다시 보냅니다. Claude는 여러분의 구현을 볼 수 없으며, 제공한 스키마와 반환한 결과만 볼 수 있습니다.
일부 일반적인 작업(셸 명령 실행, 파일 편집, 브라우저 제어, 스크래치패드 메모리 관리)의 경우, Anthropic이 도구 스키마를 게시하고 애플리케이션이 실행을 처리합니다. 이 범주의 도구는 bash, text_editor, computer, memory입니다.
실행 모델은 사용자 정의 도구와 동일합니다: 응답에는 블록이 포함되고, 코드가 작업을 실행하며, 를 다시 보냅니다. 동일한 기능을 수행하는 사용자 정의 도구 대신 Anthropic 스키마 도구를 사용하는 이유는 이러한 스키마가 훈련에 내장되어 있기 때문입니다. Claude는 이 정확한 도구 서명을 사용하는 수천 개의 성공적인 궤적에 대해 최적화되어 있으므로, 동일한 작업을 수행하는 사용자 정의 도구보다 더 안정적으로 호출하고 오류에서 더 우아하게 복구합니다. 스키마는 모델이 이미 기대하는 인터페이스입니다.
Was this page helpful?
tool_usetool_resultweb_search, web_fetch, code_execution, tool_search의 경우, Anthropic이 코드를 실행합니다. 요청에서 도구를 활성화하면 서버가 나머지 모든 것을 처리합니다. 서버 측 루프가 작업을 실행하고 응답이 여러분에게 도달하기 전에 출력을 모델에 다시 공급하기 때문에, 이러한 도구에 대한 tool_result 블록을 구성할 필요가 없습니다.
수신하는 응답에는 실행된 내용과 반환된 내용을 보여주는 server_tool_use 블록이 포함되지만, 여러분이 볼 때쯤에는 실행이 이미 완료된 상태입니다. 애플리케이션의 역할은 도구를 활성화하고 최종 답변을 읽는 것이며, 실행 루프에 참여하는 것이 아닙니다.
클라이언트 실행 도구(사용자 정의 및 Anthropic 스키마 모두)는 애플리케이션이 루프를 구동해야 합니다. 모델은 코드를 실행할 수 없으므로, 모든 도구 호출은 왕복입니다: 모델이 요청하고, 여러분이 실행하고, 여러분이 보고하고, 모델이 계속합니다.
표준적인 형태는 stop_reason을 키로 하는 while 루프입니다:
tools 배열과 사용자 메시지로 요청을 보냅니다.stop_reason: "tool_use"와 하나 이상의 tool_use 블록으로 응답합니다.tool_result 블록으로 형식화합니다.tool_result 블록이 포함된 사용자 메시지를 포함하는 새 요청을 보냅니다.stop_reason이 "tool_use"인 동안 2단계부터 반복합니다.실제로 이것은 다음과 같이 읽힙니다: stop_reason == "tool_use"인 동안, 도구를 실행하고 대화를 계속합니다. 루프는 다른 중지 이유("end_turn", "max_tokens", "stop_sequence", 또는 "refusal")에서 종료되며, 이는 Claude가 최종 답변을 생성했거나 애플리케이션이 처리해야 하는 다른 이유로 중지되었음을 의미합니다.
요청 구성, 병렬 도구 호출 처리, 결과 형식화의 메커니즘에 대해서는 도구 호출 처리를 참조하세요.
서버 실행 도구는 Anthropic의 인프라 내에서 자체 루프를 실행합니다. 애플리케이션의 단일 요청이 응답이 돌아오기 전에 여러 번의 웹 검색이나 코드 실행을 트리거할 수 있습니다. 모델은 검색하고, 결과를 읽고, 다시 검색하기로 결정하고, 필요한 것을 얻을 때까지 반복합니다. 이 모든 것이 애플리케이션의 참여 없이 이루어집니다.
이 내부 루프에는 반복 제한이 있습니다. 모델이 한도에 도달할 때까지 여전히 반복 중이면, 응답이 "end_turn" 대신 stop_reason: "pause_turn"으로 돌아옵니다. 일시 중지된 턴은 작업이 완료되지 않았음을 의미합니다; 모델이 중단된 곳에서 계속할 수 있도록 대화(일시 중지된 응답 포함)를 다시 보내세요. 연속 패턴에 대해서는 서버 도구를 참조하세요.
도구 사용은 작업이 모델이 텍스트만으로는 할 수 없는 무언가를 필요로 할 때 적합합니다:
도구를 사용해야 한다는 신호: 모델 출력에서 결정을 추출하기 위해 정규식을 작성하고 있다면, 그 결정은 도구 호출이었어야 합니다. 구조화된 의도를 복구하기 위해 자유 형식 텍스트를 파싱하는 것은 구조가 스키마에 속한다는 신호입니다.
도구 사용이 적합하지 않은 경우: