Claude API 가이드: 멀티도구 워크플로우의 프로그래밍 방식 도구 호출

InYourLeague 리서치 · 2026-09-05

핵심 답변

Claude API의 프로그래밍 방식 도구 호출(Programmatic tool calling)을 사용하면 Claude가 샌드박스화된 코드 실행 컨테이너 내부의 Python 코드에서 도구를 직접 호출할 수 있습니다. 이 워크플로우는 불필요한 모델 왕복을 줄이고 방대한 중간 데이터를 필터링하여 컨텍스트 윈도우 유입을 방지함으로써 토큰 예산을 최적화하고 지연 시간을 단축합니다.

핵심 정보 한눈에 보기

오류 유형과 검증

자주 묻는 질문

프로그래밍 방식 도구 호출과 기존 일반 도구 호출 방식의 주요 운영상 차이점은 무엇인가요?

기존 도구 호출 방식은 도구를 호출할 때마다 모델과의 왕복 통신이 발생하여 모든 중간 데이터가 컨텍스트 윈도우에 누적됩니다. 반면 프로그래밍 방식 도구 호출은 Claude가 샌드박스 컨테이너 내 Python 스크립트에서 비동기 함수로 도구를 직접 호출하고, 중간 데이터를 자체 필터링한 후 최종 요약본만 컨텍스트에 반환합니다.

프로그래밍 방식 도구 호출을 사용하기 위해 요구되는 코드 실행 도구 버전은 무엇인가요?

프로그래밍 방식 도구 호출을 사용하려면 code_execution_20260120 이상의 코드 실행 도구 버전이 필요합니다. 공식 문서에 따르면 code_execution_20260120 및 code_execution_20260521이 allowed_callers 필드에서 상호 호환되며, API 응답 블록에는 항상 code_execution_20260120으로 표기됩니다.

도구 정의의 allowed_callers 설정이 직접 호출을 완전히 차단하는 보안 경계 역할을 수행하나요?

아닙니다. 공식 문서는 allowed_callers가 Claude에게 도구 사용 방식을 안내하고 tool_choice에 대해 검증되지만, API 수준의 절대적인 차단 장치나 보안 경계가 아니라고 명시합니다. 따라서 클라이언트는 정의된 도구에 대해 직접 호출이 발생할 수 있는 상황을 항상 처리할 수 있어야 합니다.

중간 도구 실행 결과가 Claude의 프롬프트 컨텍스트 윈도우에 유입되지 않는 원리는 무엇인가요?

Claude의 샌드박스 스크립트가 도구를 호출하면 실행이 일시 중지되고 클라이언트가 tool_result 문자열을 반환합니다. 이 결과는 대화 기록 전체에 누적되는 대신 컨테이너 내부의 대기 중인 Python 프로세스로 직접 전달되어 스크립트 내에서 필터링 및 집계 처리됩니다.

프로그래밍 방식 도구 호출에 필수적이거나 검증된 제품 고유의 모델 ID가 있나요?

이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다. 공식 문서 예제에 claude-opus-5가 언급되어 있으나, 이는 예시 구성일 뿐 고정된 기본값이나 완전한 지원 모델 목록으로 간주할 수 없습니다.

출처와 확인 날짜

• 공식 출처
• 최종 확인일: 2026-09-05

상세 가이드

Claude API의 프로그래밍 방식 도구 호출(Programmatic tool calling)은 Claude가 샌드박스화된 코드 실행 컨테이너 내부에서 Python 스크립트를 작성하여 외부 도구를 프로그래밍 방식으로 직접 호출할 수 있도록 지원하는 기능입니다. 기존의 일반 도구 사용 방식에서는 여러 도구를 순차적으로 호출할 때마다 모델과의 왕복 통신이 발생하여 중간 데이터가 대화 컨텍스트에 누적되고 전반적인 턴 지연 시간이 증가했습니다. 반면 프로그래밍 방식 도구 호출을 활용하면 단일 스크립트 내에서 반복문이나 비동기 루틴을 통해 여러 도구를 호출하고, 데이터를 컨테이너 내부에서 사전 필터링 및 집계한 뒤 필요한 최종 결과만 대화 컨텍스트에 전달할 수 있습니다.

BrowseComp 및 DeepSearchQA와 같이 다단계 웹 조사 및 복합 정보 검색을 검증하는 에이전틱 검색 벤치마크 평가 결과에 따르면, 기본 검색 도구 위에 프로그래밍 방식 도구 호출을 결합했을 때 Anthropic 공식 문서에 기록된 연구 워크로드에서 입력 토큰을 24% 적게 소비하면서도 성능이 평균 11% 향상되었습니다. 이 기능은 무데이터 보존(Zero Data Retention, ZDR) 대상에 해당하지 않습니다. 또한 이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다. 공식 문서 예제에 등장하는 claude-opus-5는 예시 선택값일 뿐 고정된 기본값이나 완전한 지원 모델 목록을 의미하지 않습니다.

핵심 실행 워크플로우

1. 호출자 허용 도구 정의: code_execution_20260120 이상의 코드 실행 도구와 함께 사용자 정의 도구를 정의하고, allowed_callers: ["code_execution_20260120"] 속성을 지정하여 Python 코드 내에서 호출할 수 있도록 설정합니다.
2. 스크립트 생성 및 컨테이너 실행: Claude가 프로그래밍 방식 도구 호출이 필요하다고 판단하면 도구를 비동기 함수(await tool_name({...}))로 호출하는 Python 코드를 작성하고 샌드박스 컨테이너에서 실행합니다.
3. 도구 호출 일시 중지: 컨테이너 내 코드 실행 중 도구 함수가 호출되면 실행이 일시 중지되고 API는 stop_reason: "tool_use"와 함께 tool_use 블록을 반환합니다. 이때 caller 필드에는 { "type": "code_execution_20260120", "tool_id": "srvtoolu_..." }가 포함됩니다.
4. 도구 결과 전달: 클라이언트 애플리케이션이 실제 도구 동작(예: 데이터베이스 질의 실행)을 수행하고 표준 tool_result 블록을 API로 다시 전달합니다.
5. 컨테이너 재개 및 최종 집계: 컨테이너 내의 코드 실행이 재개되어 반환된 문자열 결과를 파싱(json.loads(...))하고 필터링합니다. 대량의 중간 결과는 컨텍스트 윈도우에 적재되지 않고 최종 스크립트 출력만 대화 컨텍스트로 전달됩니다.

도구 설정 및 호출자 필드 명세

allowed_callers 필드에서는 code_execution_20260120과 code_execution_20260521이 모두 허용되며 상호 호환됩니다. 두 버전 중 어느 것을 요청에 선언하더라도 두 호출자 목록을 만족하며, API 응답 블록의 caller 필드에는 요청에서 선언한 버전과 관계없이 항상 code_execution_20260120으로 표시됩니다.

구현 점검 체크리스트

• 도구 버전 확인: 코드 실행 도구 유형이 code_execution_20260120 또는 code_execution_20260521로 선언되었는지 확인합니다.
• 비동기 인터페이스 처리: Claude가 컨테이너 내에서 asyncio.gather 등을 이용해 도구를 병렬로 실행할 수 있도록 비동기 함수 호출 패턴을 처리합니다.
• 토큰 예산 최적화: 중간 원시 데이터가 컨텍스트 윈도우에 직접 적재되지 않도록 Python 스크립트 내부에서 필터링 및 집계(json.loads(...))가 수행되는지 검증합니다.
• 보안 경계 오해 방지: allowed_callers는 도구 사용 안내를 제공하고 tool_choice에 대해 검증되지만, API 수준의 엄격한 차단 장치나 보안 경계가 아님을 인지합니다.
• 호출자 추적 처리: 응답의 caller 객체를 검사하여 tool_id를 활성 실행 컨테이너와 연결하고 직접 호출 가능성에도 대비하도록 클라이언트를 구성합니다.