도구 사용의 작동 방식

이 페이지에서는 도구 사용의 개념, 즉 도구가 실행되는 위치, 에이전트 루프의 작동 방식, 그리고 도구 사용이 적합한 접근 방식인 경우를 설명합니다. 실습 가이드를 원하시면 튜토리얼 또는 구현 가이드부터 시작하세요.



도구 사용 계약

"Tool use"(도구 사용)는 애플리케이션과 모델 간의 계약입니다. 사용자는 어떤 작업이 가능한지와 그 입력 및 출력의 형태를 지정하고, Claude는 언제 어떻게 호출할지 결정합니다. 모델은 스스로 아무것도 실행하지 않습니다. 모델은 구조화된 요청을 내보내고, 사용자의 코드(또는 Anthropic의 서버)가 작업을 실행하며, 그 결과가 대화로 다시 흘러 들어갑니다.

이 계약은 모델이 텍스트 생성기보다는 호출하는 함수처럼 동작하게 만듭니다. 전통적인 API 경험이 있는 엔지니어는 다른 타입 지정 인터페이스와 동일한 방식으로 도구 사용을 통합할 수 있습니다. 즉, 스키마를 정의하고, 콜백을 처리하고, 결과를 반환합니다. 차이점은 반대편의 호출자가 대화를 기반으로 어떤 함수를 호출할지 선택하는 언어 모델이라는 점입니다.



도구가 실행되는 위치

도구를 구분하는 주요 축은 코드가 실행되는 위치입니다. 모든 도구는 세 가지 범주 중 하나에 속하며, 이 범주에 따라 애플리케이션이 담당해야 할 부분이 결정됩니다.



사용자 정의 도구 (클라이언트 실행)

사용자가 스키마를 작성하고, 코드를 실행하고, 결과를 반환합니다. 이것이 핵심입니다. 도구 사용 트래픽의 대부분은 애플리케이션별 로직을 호출하는 사용자 정의 도구입니다.

Claude가 사용자의 도구 중 하나를 사용하기로 결정하면, API 응답에는 도구 이름과 인수의 JSON 객체가 포함된 tool_use 블록이 포함됩니다. 애플리케이션은 해당 인수를 추출하고, 작업(데이터베이스 쿼리, HTTP 호출, 파일 쓰기 등 도구가 수행하는 모든 작업)을 실행한 다음, 다음 요청에서 tool_result 블록으로 출력을 다시 보냅니다. Claude는 사용자의 구현을 볼 수 없으며, 사용자가 제공한 스키마와 반환한 결과만 볼 수 있습니다.



Anthropic 스키마 도구 (클라이언트 실행)

몇 가지 일반적인 작업(스크래치패드 메모리 관리, 셸 명령 실행, 파일 편집, 브라우저 제어)의 경우, Anthropic이 도구 스키마를 게시하고 애플리케이션이 실행을 처리합니다. 이 범주의 도구는 memory, bash, text_editor, computer입니다.

실행 모델은 사용자 정의 도구와 동일합니다. 응답에 tool_use 블록이 포함되고, 사용자의 코드가 작업을 실행하며, tool_result를 다시 보냅니다. 동등한 도구를 직접 정의하는 대신 Anthropic 스키마 도구를 사용하는 이유는 이러한 스키마가 학습에 포함되어 있기 때문입니다. Claude는 이러한 정확한 도구 시그니처를 사용하는 수천 개의 성공적인 실행 경로로 최적화되었으므로, 동일한 작업을 수행하는 사용자 정의 도구보다 더 안정적으로 호출하고 오류에서 더 원활하게 복구합니다. 스키마는 모델이 이미 기대하는 인터페이스입니다.



서버 실행 도구

web_search, web_fetch, code_execution, tool_search의 경우 Anthropic이 코드를 실행합니다. 요청에서 도구를 활성화하면 서버가 나머지를 모두 처리합니다. 이러한 도구에 대해서는 tool_result 블록을 구성하지 않습니다. 턴이 서버 도구만 호출하는 경우, 서버 측 루프가 작업을 실행하고 응답이 사용자에게 도달하기 전에 출력을 모델에 다시 전달합니다. 단, 루프가 완료되기 전에 중단되는 경우(대부분 일시 중지로 인해)는 예외입니다.

수신하는 응답에는 무엇이 실행되었고 무엇이 반환되었는지 보여주는 server_tool_use 블록이 포함됩니다. 일반적인 경우, 이를 볼 때쯤이면 실행이 이미 완료되어 있으며, 애플리케이션의 역할은 실행 루프에 참여하는 것이 아니라 도구를 활성화하고 최종 답변을 읽는 것입니다. 주요 예외는 일시 중지된 루프(pause_turn)와 클라이언트 도구도 함께 호출하는 턴입니다.



에이전트 루프 (클라이언트 도구)

클라이언트 실행 도구(사용자 정의 및 Anthropic 스키마 모두)는 애플리케이션이 루프를 구동해야 합니다. 모델은 사용자의 코드를 실행할 수 없으므로, 모든 도구 호출은 왕복입니다. 모델이 요청하고, 사용자가 실행하고, 결과를 보고하면, 모델이 계속 진행합니다.

표준 형태는 stop_reason을 기준으로 하는 while 루프입니다.

1. tools 배열과 사용자 메시지를 포함한 요청을 보냅니다.
2. Claude가 stop_reason: "tool_use"와 하나 이상의 tool_use 블록으로 응답합니다.
3. 각 도구를 실행합니다. 출력을 tool_result 블록으로 포맷합니다.
4. 원본 메시지, 어시스턴트의 응답, 그리고 tool_result 블록이 포함된 사용자 메시지를 담은 새 요청을 보냅니다.
5. stop_reason이 "tool_use"인 동안 2단계부터 반복합니다.

실제로는 다음과 같이 읽힙니다. stop_reason == "tool_use"인 동안 도구를 실행하고 대화를 계속합니다. 루프는 다른 중지 이유("end_turn", "max_tokens", "stop_sequence", 또는 "refusal")에서 종료되며, 이는 Claude가 최종 답변을 생성했거나 애플리케이션이 처리해야 하는 다른 이유로 중지했음을 의미합니다.

요청 구성, 병렬 도구 호출 처리, 결과 포맷팅의 메커니즘에 대해서는 도구 호출 처리를 참조하세요.



서버 측 루프

서버 실행 도구는 Anthropic의 인프라 내에서 자체 루프를 실행합니다. 애플리케이션의 단일 요청이 응답이 돌아오기 전에 여러 번의 웹 검색이나 코드 실행을 트리거할 수 있습니다. 모델은 검색하고, 결과를 읽고, 다시 검색하기로 결정하고, 필요한 것을 얻을 때까지 반복하며, 이 모든 과정에서 애플리케이션은 참여하지 않습니다.

이 내부 루프에는 반복 제한이 있습니다. 모델이 제한에 도달했을 때 여전히 반복 중이면, 응답은 "end_turn" 대신 stop_reason: "pause_turn"으로 돌아옵니다. 일시 중지된 턴은 작업이 완료되지 않았음을 의미합니다. 모델이 중단된 지점부터 계속할 수 있도록 대화(일시 중지된 응답 포함)를 다시 보내세요. 계속 패턴에 대해서는 서버 도구를 참조하세요.

또한 Claude가 동일한 병렬 도구 호출 그룹에서 서버 도구와 클라이언트 도구를 함께 호출하는 경우, 루프는 서버 도구가 실행되기 전에 제어권을 사용자에게 넘깁니다. 이때 응답은 stop_reason: "tool_use"와 아직 결과 블록이 없는 server_tool_use 블록과 함께 돌아옵니다. API는 사용자가 클라이언트 도구 결과를 반환한 후에 이를 실행합니다. 정확한 계약에 대해서는 중지 이유 및 폴백을 참조하세요.



도구를 사용해야 할 때 (그리고 사용하지 말아야 할 때)

도구 사용은 작업이 모델이 텍스트만으로는 할 수 없는 것을 요구할 때 적합합니다.

• 부작용이 있는 작업. 이메일 전송, 파일 쓰기, 레코드 업데이트. 모델은 이러한 작업을 설명할 수 있지만, 도구만이 이를 수행할 수 있습니다.
• 최신 또는 외부 데이터. 현재 가격, 오늘의 날씨, 데이터베이스의 내용. 학습 데이터 외부에 있거나 시스템에 특정한 모든 것은 도구를 통해 가져와야 합니다.
• 구조화되고 형태가 보장된 출력. 정보를 우연히 포함하는 산문이 아니라 특정 필드가 있는 JSON 객체가 필요한 경우, 도구 스키마가 형태를 강제합니다.
• 기존 시스템 호출. 데이터베이스, 내부 API, 파일 시스템. 도구 사용은 자연어 요청과 이를 수행하는 시스템 간의 다리입니다.

도구를 사용해야 한다는 신호: 모델 출력에서 결정을 추출하기 위해 정규식을 작성하고 있다면, 그 결정은 도구 호출이었어야 합니다. 구조화된 의도를 복구하기 위해 자유 형식 텍스트를 파싱하는 것은 그 구조가 스키마에 속해야 한다는 신호입니다.

도구 사용이 적합하지 않은 경우:

• 모델이 학습만으로 답변할 수 있는 경우. 요약, 번역, 일반 지식 질문은 도구 왕복이 필요하지 않습니다.
• 상호작용이 부작용 없는 일회성 Q&A인 경우. 실행할 것이 없다면 도구가 할 일도 없습니다.
• 도구 호출 "latency"(지연 시간)가 사소한 응답을 압도하는 경우. 모든 도구 호출은 최소 한 번의 추가 왕복입니다. 가벼운 작업의 경우 오버헤드가 작업 자체를 초과할 수 있습니다.



접근 방식 선택



다음 단계