Programmatic Tool Calling은 왜 도구 호출이 아니라 실행 경계일까

• 카테고리: ai_dev
• 예상 읽기 시간: 10분
• 오늘의 질문: 에이전트가 도구를 하나씩 부르는 대신 코드를 실행해 여러 도구를 조합하게 만들면, 우리는 무엇을 더 엄격하게 설계해야 할까?
• 핵심 출처:
  • Programmatic Tool Calling - OpenAI API - 게시일 미표기, 2026-07-11 확인
  • Model guidance - OpenAI API - 게시일 미표기, 2026-07-11 확인
  • How Code Mode works - Cloudflare Agents docs - 2026-06-24 수정, 2026-07-11 확인
  • Cloudflare's own MCP servers - Cloudflare Agents docs - 게시일 미표기, 2026-07-11 확인
  • Code execution with MCP: building more efficient AI agents - Anthropic - 2025-11-04 게시, 2026-07-11 확인

1. 왜 지금 봐야 하나

최근 에이전트 설계에서 “tool calling”의 모양이 조금씩 바뀌고 있다. 예전에는 모델이 search_customer, get_invoice, update_ticket 같은 도구를 하나씩 호출하고, 애플리케이션이 결과를 다시 모델에게 넣어 다음 호출을 기다리는 구조가 기본이었다. 이 방식은 이해하기 쉽지만 도구가 많아지고 중간 결과가 커질수록 컨텍스트, 비용, 지연이 빠르게 늘어난다.

OpenAI의 Programmatic Tool Calling 문서는 모델이 Responses API 요청 안에서 JavaScript를 작성해 eligible tool을 조합하고, 루프·조건·병렬 호출·필터링·집계·검증을 수행할 수 있다고 설명한다. OpenAI의 최신 모델 가이드도 GPT-5.6에서 이 기능을 bounded tool-heavy workflow에 쓰라고 권한다. Cloudflare의 Code Mode 문서는 모델에게 전체 도구 카탈로그를 넣는 대신 하나의 codemode 도구와 점진적 search/describe를 제공하고, 실행·승인·replay·rollback을 durable runtime이 관리한다고 설명한다. Anthropic도 MCP 도구를 직접 나열하는 대신 코드 API로 노출하면 도구 정의와 큰 중간 결과를 컨텍스트 밖에서 처리할 수 있다고 설명한다.

핵심은 “모델이 코드를 쓸 수 있다”가 아니다. 도구 호출의 일부 판단과 데이터 처리를 모델 대화 바깥의 실행 경계로 옮긴다는 점이다. 이 경계를 잘 설계하면 토큰과 지연을 줄일 수 있지만, 잘못 설계하면 권한 우회, 재실행 부작용, 잘못 압축된 결과, 검증 불가능한 최종 답변이 생긴다.

2. 핵심 개념

Programmatic Tool Calling 또는 Code Mode를 한 문장으로 정의하면 이렇다.

모델이 매 단계 자연어로 도구를 고르는 대신, 제한된 sandbox 안에서 짧은 프로그램을 작성해 여러 도구 호출과 중간 데이터 처리를 실행하게 하는 패턴.

여기에는 세 층이 있다.

첫째, 도구 목록의 노출 방식이다. 직접 tool calling은 도구 스키마를 모델 컨텍스트에 넣는다. 도구가 10개면 괜찮지만, 수백 개 API endpoint나 여러 MCP 서버를 붙이면 도구 설명만으로 컨텍스트가 무거워진다. Cloudflare 문서는 전체 Cloudflare API의 2,594개 endpoint를 native MCP tool로 노출하면 full schema 기준 약 1,170,000 token, required parameter만 넣어도 약 244,000 token이 필요하지만, Code Mode의 search()와 execute() 패턴은 약 1,000 token 수준으로 줄인다고 설명한다.

둘째, 중간 결과의 위치다. 직접 tool calling에서는 도구 결과가 모델 컨텍스트로 들어오고, 다음 도구 입력으로 다시 모델이 써야 한다. Anthropic은 2시간 회의록을 Google Drive에서 읽어 Salesforce에 붙이는 예시에서 큰 transcript가 모델 컨텍스트를 두 번 통과할 수 있다고 지적한다. 코드 실행 패턴에서는 transcript 전체를 sandbox 내부 변수로 두고, 모델에게는 필요한 요약·검증 결과·상태만 돌려줄 수 있다.

셋째, 실행 제어의 위치다. 필터링, join, deduplication, ranking, aggregation, validation처럼 결정적인 로직은 모델에게 매번 묻기보다 코드가 처리할 수 있다. OpenAI 문서는 이런 예측 가능한 control flow에 Programmatic Tool Calling을 쓰고, 각 결과마다 새로운 모델 판단이 필요하거나 승인·citation·native artifact 보존이 중요한 경우에는 직접 tool calling을 선호하라고 구분한다.

3. 최신 이슈와 연결

OpenAI의 Programmatic Tool Calling은 hosted V8 runtime에서 JavaScript를 실행한다. 문서상 이 runtime은 Node.js, package install, direct network access, 일반 filesystem, subprocess, console, persistent JavaScript state를 제공하지 않는다. 외부 시스템과의 상호작용은 요청에서 허용한 도구를 통해서만 가능하다. 즉 “모델에게 임의 코드를 실행시킨다”가 아니라, 도구 접근권을 제한한 짧은 실행 환경을 제공하는 것이다.

Cloudflare Code Mode는 이 패턴을 MCP와 API catalog 쪽으로 확장한다. 문서에 따르면 executor는 생성 코드를 격리 실행하고 상태를 저장하지 않는다. connector는 GitHub, Stripe, MCP server, OpenAPI 문서 같은 host-side capability를 sandbox 안의 namespace로 노출한다. durable runtime은 실행 기록, connector-call log, pending approval, snippet, replay, rollback을 관리한다. 특히 connector 호출이 sandbox boundary를 넘을 때 runtime이 가로채 승인·로깅·replay 정책을 적용한다는 점이 중요하다.

Anthropic의 글은 같은 문제를 context efficiency 관점에서 설명한다. MCP가 많은 시스템을 연결하는 표준이 되면서 tool definition과 intermediate result가 컨텍스트를 잡아먹는다. 이때 MCP 서버를 code API처럼 노출하면 모델은 필요한 도구 정의만 읽고, 큰 데이터는 실행 환경 안에서 필터링한 뒤 작은 결과만 모델로 넘길 수 있다. 다만 Anthropic도 sandboxing, resource limit, monitoring 같은 운영 복잡도가 생긴다고 경고한다.

4. 개발자 관점 해석

이 패턴의 장점은 명확하다. 첫째, 토큰 비용을 줄인다. 도구 스키마와 중간 payload를 매 턴 모델에게 읽히지 않아도 된다. 둘째, 지연을 줄일 수 있다. 모델-도구-모델 왕복을 줄이고, 일부 호출은 코드에서 병렬화할 수 있다. 셋째, 결정적 처리를 코드로 옮긴다. 정렬, 중복 제거, 집계, schema validation은 LLM보다 코드가 안정적이다.

하지만 실패 모드도 함께 온다.

첫 번째 실패는 잘못된 압축이다. 프로그램이 큰 결과를 줄여서 반환할 때 중요한 예외, citation, 원본 artifact를 버릴 수 있다. OpenAI 문서가 final citation이나 native artifact validation이 필요한 경우 직접 tool calling을 권하는 이유다. 비용을 아끼려고 근거를 없애면 신뢰성은 오히려 떨어진다.

두 번째 실패는 승인 경계 붕괴다. 읽기 작업과 쓰기 작업을 같은 program 안에 넣으면 모델이 작성한 코드가 언제 side effect를 일으키는지 사용자가 보기 어렵다. Cloudflare Code Mode가 pending approval, replay, rollback을 runtime 책임으로 둔 이유는 “코드가 실행된다”는 사실만으로는 안전하지 않기 때문이다. 승인 필요한 connector method는 실행을 pause하고, 같은 execution ID로 재개할 때 이미 적용된 호출을 replay해야 한다.

세 번째 실패는 재실행 부작용이다. 승인 때문에 코드가 다시 실행되거나 네트워크 오류 뒤 retry될 때 같은 결제, 이메일, DB update가 두 번 일어나면 안 된다. Code Mode 문서는 sequence number, applied result, replay divergence, rollback 같은 개념을 둔다. 직접 구현한다면 idempotency key와 execution log가 필수다.

네 번째 실패는 모델 판단이 필요한 단계를 코드로 숨기는 것이다. 검색 결과 하나하나를 읽고 다음 쿼리를 바꿔야 하는 adaptive search, 모호한 사용자 의도를 확인해야 하는 단계, 정책 판단이 필요한 단계는 코드 루프에 묻어두면 안 된다. 그런 단계는 모델 또는 사람 승인으로 되돌려야 한다.

5. 내 프로젝트에 적용할 체크포인트

에이전트에 code-based tool orchestration을 넣기 전, 아래 질문을 먼저 확인하자.

1. 이 단계는 bounded workflow인가?
   입력, 사용할 도구, 종료 조건, 실패 처리가 비교적 명확한가? 아니라면 직접 tool calling이나 일반 agent loop가 낫다.

2. 중간 결과를 줄여도 되는가?
   최종 답변에 citation, 원본 파일, 감사 로그, 법적 증빙이 필요하다면 프로그램이 무엇을 버렸는지 검증해야 한다.

3. 도구별 allowed caller를 나눴는가?
   읽기·검색·집계 도구는 programmatic 호출을 허용할 수 있지만, 결제·삭제·권한 변경·외부 발송은 직접 호출과 사람 승인을 기본값으로 두는 편이 안전하다.

4. sandbox가 정말 제한되어 있는가?
   direct network, filesystem, package install, subprocess, secret 접근을 기본 차단하고, 외부 효과는 connector/tool boundary로만 나가게 해야 한다.

5. replay와 idempotency가 있는가?
   execution ID, call ID, sequence number, idempotency key, applied result log를 남겨야 retry와 approval resume이 안전해진다.

6. eval 기준이 resource 절감만은 아닌가?
   호출 수, token, latency가 줄어도 최종 답변의 정확성·완전성·필수 근거·정책 준수가 나빠지면 개선이 아니다.

6. 오늘 10분 액션

오늘은 실제 코드를 만들기 전에 “어떤 도구를 programmatic으로 옮길지”만 표로 정해보자.

1. 현재 에이전트가 쓰는 도구 5~10개를 적는다.
2. 각 도구를 read / transform / write / approval-sensitive로 분류한다.
3. programmatic 후보는 read + transform 중심으로만 고른다.
4. write 도구에는 idempotency key, approval 필요 여부, rollback 가능 여부를 적는다.
5. 최종 답변에서 반드시 보존해야 하는 evidence 필드를 정한다.

작은 예시는 이렇다.

10분 동안 이 표만 만들어도 “도구 호출을 줄이자”가 아니라 “어디까지 실행 환경에 맡길 수 있는가”라는 설계 질문으로 바뀐다.

7. 더 볼 자료

• OpenAI Programmatic Tool Calling 문서: hosted runtime, allowed_callers, programmatic/direct 호출 선택 기준을 확인하기 좋다.
• OpenAI Model guidance: GPT-5.6의 Programmatic Tool Calling, multi-agent beta, reasoning/pro mode를 migration 관점에서 정리한다.
• Cloudflare Code Mode 문서: executor, connector, durable runtime, approval, replay, rollback을 분리해 설명한다.
• Cloudflare MCP server 문서: 큰 API catalog를 search()와 execute() 두 도구로 줄이는 실제 사례를 보여준다.
• Anthropic Code execution with MCP: MCP tool catalog와 intermediate result가 컨텍스트를 어떻게 압박하는지 원리 중심으로 설명한다.

중복 회피 메모

로컬 content/generated와 Supabase의 최근 ai_dev 글을 확인했다. 최근 글은 도구 호출 왕복 프로토콜, Tool Search, 서브에이전트 컨텍스트 격리, 에이전트 trace, RAG citation, token counting, guardrail checkpoint를 다뤘다. 이번 글은 도구를 어떻게 선택하거나 call_id를 어떻게 매핑하는지가 아니라, 여러 도구 호출과 중간 데이터 처리를 sandboxed code execution boundary로 옮길 때 생기는 allowed caller, 승인, replay, rollback, evidence 보존 판단에 집중한다.