도구 사용 방식

이 페이지는 도구 사용의 개념을 설명합니다: 도구가 실행되는 위치, 에이전트 루프가 어떻게 작동하는지, 그리고 도구 사용이 올바른 접근 방식인 경우입니다. 실습 지침을 원하시면 튜토리얼이나 구현 가이드부터 시작하세요.

도구 사용 계약

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

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

도구가 실행되는 위치

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

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

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

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

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

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

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

서버 실행 도구

web_search, web_fetch, code_execution, tool_search의 경우, Anthropic이 코드를 실행합니다. 요청에서 도구를 활성화하면 서버가 나머지를 모두 처리합니다. 서버 측 루프가 작업을 실행하고 응답이 도달하기 전에 모델로 출력을 피드백하기 때문에 이러한 도구에 대해 tool_result 블록을 구성하지 않습니다.

받는 응답에는 실행된 내용과 반환된 내용을 보여주는 server_tool_use 블록이 포함되지만, 이를 볼 때쯤이면 실행이 이미 완료되었습니다. 애플리케이션의 역할은 도구를 활성화하고 최종 답변을 읽는 것이지, 실행 루프에 참여하는 것이 아닙니다.

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

클라이언트 실행 도구(사용자 정의 및 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"으로 돌아옵니다. 일시 중지된 턴은 작업이 완료되지 않았음을 의미합니다. 대화(일시 중지된 응답 포함)를 다시 보내 모델이 중단한 위치에서 계속하도록 합니다. 계속 패턴은 서버 도구를 참조하세요.

도구 사용 시기(및 사용하지 않을 시기)

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

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

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

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

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

접근 방식 선택

다음 단계