도구 사용이 어떻게 작동하는지

도구 사용이 어떻게 작동하는지 (How tool use works)

이 페이지에서는 도구 사용 뒤에 있는 개념을 설명해요. 도구가 어디서 실행되는지, 에이전트 루프가 어떻게 작동하는지, 언제 도구 사용이 올바른 접근인지를 다뤄요. 직접 해보며 배우고 싶다면 도구 사용 에이전트 만들기 튜토리얼이나 도구 정의하기 가이드부터 시작해보세요.

출처: 문서

본문

이 페이지에서는 도구 사용 뒤에 있는 개념을 설명해요. 도구가 어디서 실행되는지, 에이전트 루프가 어떻게 작동하는지, 언제 도구 사용이 올바른 접근인지를 다뤄요. 직접 해보며 시작하려면 도구 사용 에이전트 만들기 튜토리얼이나 도구 정의하기 가이드를 참고해요.

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

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

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

도구가 어디서 실행되는지 (Where tools run)

도구가 서로 다른 주된 기준은 코드가 어디서 실행되느냐예요. 모든 도구는 세 가지 범주 중 하나에 속하며, 그 범주가 여러분의 애플리케이션이 무엇을 책임지는지를 결정해요.

사용자 정의 도구 (클라이언트 실행) (User-defined tools (client-executed))

스키마를 작성하고, 코드를 실행하고, 결과를 반환해요. 이것이 가장 흔한 경우예요. 대부분의 도구 사용 트래픽은 사용자 정의 도구가 애플리케이션 고유 로직을 호출하는 형태예요.

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

Anthropic 스키마 도구 (클라이언트 실행) (Anthropic-schema tools (client-executed))

소수의 공통 작업(스크래치패드 메모리 관리, 셸 명령 실행, 파일 편집, 데스크톱이나 브라우저 제어)에 대해서는 Anthropic이 도구 스키마를 게시하고 여러분의 애플리케이션이 실행을 처리해요. 이 범주의 도구는 memory, bash, text_editor, computer, browser예요.

실행 모델은 사용자 정의 도구와 동일해요. 응답에 tool_use 블록이 포함되고, 여러분의 코드가 작업을 실행하며, tool_result를 다시 보내요. Anthropic 스키마 도구를 직접 정의하는 대신 쓰는 이유는 이 스키마들이 학습(train)되어 있기 때문이에요. Claude는 이런 정확한 도구 시그니처를 사용하는 수천 개의 성공적인 궤적에 최적화되어 있어서, 같은 일을 하는 커스텀 도구보다 더 안정적으로 호출하고 오류에서 더 우아하게 회복해요. 스키마는 모델이 이미 기대하는 인터페이스예요.

서버 실행 도구 (Server-executed tools)

web_search, web_fetch, code_execution, tool_search의 경우 Anthropic이 코드를 실행해요. 요청에서 도구를 활성화하면 서버가 나머지를 처리해요. 이 도구들에 대해서는 tool_result 블록을 직접 만들지 않아요. 한 턴이 서버 도구만 호출하면, 서버 측 루프가 작업을 실행하고 응답이 여러분에게 도달하기 전에 출력을 모델에 다시 공급해요. 다만 루프가 끝나기 전에 멈추는 경우(대부분 일시 중지 때문에) 예외가 있어요.

받는 응답에는 무엇이 실행됐고 무엇이 돌아왔는지 보여주는 server_tool_use 블록이 포함돼요. 일반적인 경우 실행은 여러분이 그 블록을 볼 때쯤 이미 완료되어 있고, 여러분의 애플리케이션의 일은 실행 루프에 참여하는 대신 도구를 활성화하고 최종 답을 읽는 것이에요. 주요 예외는 일시 중지된 루프(pause_turn)와 클라이언트 도구도 함께 호출하는 턴이에요.

에이전트 루프 (클라이언트 도구) (The agentic loop (client tools))

클라이언트 실행 도구(사용자 정의와 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의 인프라 안에서 자체 루프를 실행해요. 여러분의 애플리케이션에서 단일 요청을 보내면 응답이 돌아오기 전에 여러 번의 웹 검색이나 코드 실행이 일어날 수 있어요. 모델은 검색하고, 결과를 읽고, 다시 검색할지 결정하고, 필요한 것을 얻을 때까지 반복해요. 이 모든 과정에서 여러분의 애플리케이션은 참여하지 않아요.

이 내부 루프에는 반복 한도가 있어요. 모델이 한도에 도달할 때까지 여전히 반복 중이면 응답은 "end_turn" 대신 stop_reason: "pause_turn"으로 돌아와요. 일시 중지된 턴은 작업이 끝나지 않았다는 뜻이에요. 대화를(일시 중지된 응답을 포함해) 다시 보내면 모델이 멈춘 지점에서 계속할 수 있어요. 계속하기 패턴은 서버 도구에서 볼 수 있어요.

또한 같은 병렬 도구 호출 그룹에서 Claude가 서버 도구와 클라이언트 도구를 함께 호출하면 서버 도구가 실행되기 전에 제어권이 여러분에게 돌아와요. 이때 응답은 stop_reason: "tool_use"와 아직 결과 블록이 없는 server_tool_use 블록으로 돌아와요. API는 여러분이 클라이언트 도구 결과를 돌려준 후에 그것을 실행해요. 정확한 계약은 중지 이유와 폴백을 참고해요.

언제 도구를 쓸까 (그리고 쓰지 말까) (When to use tools (and when not to))

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

  • 부작용이 있는 행동. 이메일 보내기, 파일 쓰기, 레코드 갱신. 모델은 이런 행동을 설명할 수 있지만, 수행하는 것은 도구뿐이에요.
  • 신선하거나 외부의 데이터. 현재 가격, 오늘의 날씨, 데이터베이스 내용. 학습 데이터 밖의 것 또는 여러분의 시스템에 특화된 것은 가져오려면 도구가 필요해요.
  • 구조화되고 형태가 보장된 출력. 정보를 우연히 담고 있는 산문 대신 특정 필드를 가진 JSON 객체가 필요할 때, 도구 스키마가 그 형태를 강제해요.
  • 기존 시스템 호출. 데이터베이스, 내부 API, 파일 시스템. 도구 사용은 자연어 요청과 그것을 충족시키는 시스템 사이의 다리예요.

도구를 써야 한다는 명확한 신호가 있어요. 모델 출력에서 결정을 추출하려고 regex를 쓰고 있다면, 그 결정은 도구 호출이어야 했어요. 자유 형식 텍스트를 파싱해서 구조화된 의도를 되찾는 것은 그 구조가 스키마에 속한다는 신호예요.

도구 사용은 다음과 같은 경우 어울리지 않아요:

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

접근 방식 선택하기 (Choosing between approaches)

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

더 알아보기 (Learn more)