도구 사용 작동 원리 (How Tool Use Works)

도구 사용 루프가 어떻게 돌아가는지, 도구가 어디서 실행되는지, 그리고 언제 문장(prose) 대신 도구를 써야 하는지를 이해해 보아요.

이 페이지는 도구 사용의 개념을 다룹니다. 도구가 어디서 실행되는지, 에이전트 루프(agentic loop)가 어떻게 작동하는지, 어떤 상황에서 도구 사용이 맞는 접근인지를 설명할게요. 실제로 손을 움직여 보고 싶다면 도구 사용 에이전트 만들기 튜토리얼이나 도구 정의하기 가이드부터 시작하는 걸 추천해요.

도구 사용 계약 (The tool-use contract)

도구 사용은 여러분의 애플리케이션과 모델 사이의 계약이에요. 여러분은 어떤 작업이 가능한지, 그 입력과 출력이 어떤 모양인지를 정하고, Claude가 언제 어떻게 호출할지를 결정합니다. 모델은 절대 스스로 아무것도 실행하지 않아요. 모델은 구조화된 요청을 내보낼 뿐이고, 여러분의 코드(또는 Anthropic 서버)가 그 작업을 실행한 뒤 결과를 다시 대화로 흘려보내는 구조죠.

이 계약 덕분에 모델은 단순한 텍스트 생성기라기보다는 여러분이 호출하는 하나의 함수처럼 동작해요. 고전적인 API 경험이 있는 엔지니어라면 다른 타입 기반 인터페이스와 똑같은 방식으로 도구 사용을 통합할 수 있습니다. 스키마를 정의하고, 콜백을 처리하고, 결과를 반환하면 돼요. 차이가 있다면 반대편에 있는 호출자가 대화 내용을 보고 어떤 함수를 호출할지 고르는 언어 모델이라는 점이죠.

도구가 실행되는 곳 (Where tools run)

도구들이 서로 달라지는 가장 큰 기준은 코드가 어디서 실행되느냐입니다. 모든 도구는 세 가지 그룹 중 하나에 속하고, 그 그룹에 따라 여러분의 애플리케이션이 책임져야 할 일이 달라져요.

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

스키마를 쓰고, 코드를 실행하고, 결과를 반환하는 건 모두 여러분의 몫이에요. 이게 가장 흔한 경우입니다. 도구 사용 트래픽의 대부분은 애플리케이션 고유 로직을 호출하는 사용자 정의 도구죠.

Claude가 여러분의 도구 중 하나를 호출하면, API 응답에 도구 이름과 JSON 객체 형태의 인자(arguments)를 담은 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 블록을 직접 만들 일이 없습니다. 한 턴(turn)이 서버 도구만 호출하는 경우, 서버 쪽 루프가 작업을 실행하고 응답이 여러분에게 도달하기 전에 그 출력을 모델에 다시 흘려보냅니다. 단, 루프가 끝나기 전에 멈추는 경우는 예외인데, 가장 흔한 경우는 일시 정지(pause) 때문이에요.

여러분이 받는 응답에는 무엇이 실행됐고 무엇이 반환됐는지 보여주는 server_tool_use 블록이 들어 있어요. 일반적인 경우에는 여러분이 그것을 볼 즈음엔 실행이 이미 끝나 있어서, 애플리케이션의 할 일은 도구를 활성화하고 실행 루프에 참여하는 대신 최종 답을 읽는 것입니다. 주요 예외는 일시 정지된 루프(pause_turn)와 클라이언트 도구도 함께 호출하는 턴이에요.

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

클라이언트 실행 도구(사용자 정의와 Anthropic 스키마 모두)는 애플리케이션이 루프를 직접 돌려야 합니다. 모델은 여러분의 코드를 실행할 수 없으니, 모든 도구 호출은 왕복(round trip)이에요. 모델이 요청하고, 여러분이 실행하고, 다시 보고하고, 모델이 이어가는 구조죠.

전형적인 모양은 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가 최종 답을 냈거나, 애플리케이션이 처리해야 할 다른 이유로 멈췄다는 뜻이에요.

요청 구성, 병렬 도구 호출 처리, 결과 형식 지정 방법은 도구 호출 처리하기에서 다뤄요.

서버 쪽 루프 (The server-side loop)

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

이 내부 루프에는 반복 한도(iteration limit) 가 있습니다. 한도에 도달했는데도 모델이 여전히 반복 중이면, 응답이 "end_turn" 대신 stop_reason: "pause_turn"으로 돌아와요. 일시 정지된 턴은 작업이 끝나지 않았다는 뜻입니다. 일시 정지된 응답을 포함한 대화를 다시 보내면 모델이 중단된 지점부터 이어서 작업을 계속해요. 지속 패턴은 서버 도구에서 볼 수 있습니다.

루프는 또한 Claude가 서버 도구와 클라이언트 도구를 같은 병렬 도구 호출 그룹에서 함께 호출하는 경우, 서버 도구가 실행되기 전에 제어권을 여러분에게 다시 넘깁니다. 그러면 응답이 stop_reason: "tool_use"와 함께 아직 결과 블록이 없는 server_tool_use 블록으로 돌아오고, API는 여러분이 클라이언트 도구 결과를 반환한 뒤에 그것을 실행해요. 정확한 계약은 정지 사유와 폴백에서 확인하세요.

언제 도구를 쓰고, 언제 쓰지 말아야 할까

도구 사용은 작업이 텍스트만으로는 모델이 할 수 없는 무언가를 요구할 때 어울립니다.

• 부수 효과가 있는 작업. 이메일 보내기, 파일 쓰기, 기록 업데이트 같은 것들이요. 모델은 이런 작업을 설명할 수는 있지만, 수행할 수 있는 건 도구뿐이에요.
• 최신이거나 외부의 데이터. 현재 가격, 오늘의 날씨, 데이터베이스 내용이 여기에 해당해요. 학습 데이터 밖에 있거나 여러분의 시스템에 특화된 것이라면 그것을 가져오려면 도구가 필요합니다.
• 구조화되고 형태가 보장된 출력. 특정 필드를 가진 JSON 객체가 필요할 때, 정보를 우연히 담고 있는 문장보다는 도구 스키마가 그 형태를 강제해요.
• 기존 시스템에 연결하기. 데이터베이스, 내부 API, 파일시스템이죠. 도구 사용은 자연어 요청과 그것을 수행하는 시스템 사이의 다리 역할을 합니다.

도구를 써야 한다는 분명한 신호 하나를 드릴게요. 모델 출력에서 결정을 추출하려고 정규식(regex)을 쓰고 있다면, 그 결정은 애초에 도구 호출이었어야 합니다. 자유 형식 텍스트를 파싱해서 구조화된 의도를 되찾는 일은, 그 구조가 스키마에 들어 있었어야 한다는 신호이기 때문이에요.

도구 사용이 어울리지 않는 경우도 있어요.

• 모델이 학습만으로 답할 수 있는 경우. 요약이나 번역, 일반 상식 질문은 도구 왕복이 필요 없어요.
• 부수 효과가 없는 일회성 질문·답변. 실행할 것이 없다면 도구가 할 일도 없죠.
• 도구 호출 지연이 사소한 응답을 압도하는 경우. 모든 도구 호출은 최소 왕복 한 번을 더하며, 가벼운 작업에서는 그 오버헤드가 작업 자체보다 커질 수 있어요.

접근 방식 선택하기

접근 방식	언제 쓸까	무엇을 기대할까	더 알아보기
사용자 정의 클라이언트 도구	커스텀 비즈니스 로직, 내부 API, 독점 데이터	실행과 에이전트 루프를 여러분이 처리	도구 정의하기
Anthropic 스키마 클라이언트 도구	표준 개발 작업(bash, 파일 편집, 데스크톱·브라우저 제어)	실행은 여러분이 처리하고, 스키마가 학습되어 있어 Claude가 도구를 안정적으로 호출	도구 레퍼런스
서버 실행 도구	웹 검색, 코드 샌드박스, 웹 가져오기	Anthropic이 실행을 처리하고, 여러분은 결과를 만들 대신 읽기만	서버 도구

다음 단계