Messages도구

도구 사용의 작동 방식

Copy page



도구 사용 루프, 도구가 실행되는 위치, 그리고 산문 대신 도구를 사용해야 하는 시점을 이해하세요.

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

도구 사용 계약

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

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

도구가 실행되는 위치

도구가 서로 다른 주요 축은 코드가 실행되는 위치입니다. 모든 도구는 세 가지 범주 중 하나에 속하며, 그 범주가 애플리케이션이 책임지는 부분을 결정합니다.

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

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

Claude가 여러분의 도구 중 하나를 호출하면, API 응답에는 도구 이름과 인수의 JSON 객체가 포함된 tool_use 블록이 들어 있습니다. 애플리케이션은 그 인수를 추출하고, 작업(데이터베이스 쿼리, HTTP 호출, 파일 쓰기 등 도구가 수행하는 모든 것)을 실행한 다음, 다음 요청에서 tool_result 블록에 출력을 다시 보냅니다. Claude는 여러분의 구현을 절대 보지 못합니다. 제공한 스키마와 반환한 결과만 볼 뿐입니다.

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

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

실행 모델은 사용자 정의 도구와 동일합니다. 응답에 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인 경우. 실행할 것이 없다면, 도구가 할 일도 없습니다.
• 도구 호출 지연 시간이 사소한 응답을 지배하게 되는 경우. 모든 도구 호출은 최소한 한 번의 추가 왕복입니다. 가벼운 작업의 경우 오버헤드가 작업 자체를 초과할 수 있습니다.

접근 방식 선택하기

다음 단계