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은 도구 스키마를 게시하고 애플리케이션이 실행을 처리합니다. 이 범주의 도구는 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 루프입니다:
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"으로 돌아옵니다. 일시 중지된 턴은 작업이 완료되지 않았음을 의미합니다. 대화(일시 중지된 응답 포함)를 다시 보내면 모델이 중단된 지점에서 계속할 수 있습니다. 계속 진행 패턴에 대해서는 서버 도구를 참조하세요.
또한 Claude가 동일한 병렬 도구 호출 그룹에서 서버 도구와 클라이언트 도구를 함께 호출하는 경우, 루프는 해당 서버 도구가 실행되기 전에 제어권을 여러분에게 돌려줍니다. 그러면 응답은 stop_reason: "tool_use"와 아직 결과 블록이 없는 server_tool_use 블록으로 돌아옵니다. API는 여러분이 클라이언트 도구 결과를 반환한 후에 이를 실행합니다. 정확한 계약에 대해서는 중지 이유 및 폴백을 참조하세요.
도구 사용은 텍스트만으로는 모델이 할 수 없는 것을 작업이 요구할 때 적합합니다:
도구를 사용해야 한다는 명확한 신호: 모델 출력에서 결정을 추출하기 위해 정규식을 작성하고 있다면, 그 결정은 도구 호출이었어야 합니다. 구조화된 의도를 복원하기 위해 자유 형식 텍스트를 파싱하는 것은 그 구조가 스키마에 속해야 한다는 신호입니다.
도구 사용이 적합하지 않은 경우:
| 접근 방식 | 사용 시점 | 예상되는 것 | 자세히 알아보기 |
|---|---|---|---|
| 사용자 정의 클라이언트 도구 | 커스텀 비즈니스 로직, 내부 API, 독점 데이터 | 여러분이 실행과 에이전트 루프를 처리합니다 | 도구 정의하기 |
| Anthropic 스키마 클라이언트 도구 | 표준 개발 작업 (bash, 파일 편집, 브라우저 제어) | 여러분이 실행을 처리합니다. 스키마가 학습에 포함되어 있어 Claude가 도구를 안정적으로 호출합니다 | 도구 참조 |
| 서버 실행 도구 | 웹 검색, 코드 샌드박스, 웹 가져오기 | Anthropic이 실행을 처리합니다. 여러분은 결과를 생성하는 대신 읽습니다 | 서버 도구 |
단일 도구 호출부터 프로덕션까지 단계별로 에이전트를 구축합니다.
스키마 사양, 설명, 그리고 tool_choice.
Anthropic이 제공하는 도구 디렉터리.
Was this page helpful?