코드 모드

코드 모드 (Code Mode)

에이전트가 도구를 하나씩 호출하는 대신, 한 턴에서 여러 도구 호출을 오케스트레이션하는 JavaScript를 작성하게 해요.

출처: 문서

본문

코드 모드란 무엇인가? (What Code Mode Is)

기본적으로 모델은 도구를 한 번에 하나씩 호출해요: 도구 호출을 만들고, 결과를 기다린 뒤, 다음에 무엇을 호출할지 결정해요. 많은 도구 호출을 체인으로 연결하는 작업 — "모든 열린 이슈를 나열하고, 각각의 댓글을 가져온 다음, 요약해줘" — 은 단계마다 모델 왕복이 한 번씩 필요하다는 뜻이에요.

Code Mode는 에이전트의 개별 도구들을 JavaScript 스크립트를 실행하는 단일 도구 run_tools_with_javascript 로 대체해요. 에이전트가 직접 호출할 모든 도구는 그 스크립트에 평범한 JavaScript 함수로 노출돼요(동기식 — await / async 불필요). 모델은 필요한 만큼 호출하는 스크립트를 작성하고, 결과를 결합·필터링하며, 단일 문자열을 반환해요 — 전부 한 번의 도구 호출로요.

코드 모드 활성화 (Enabling Code Mode)

에이전트에 code_mode_tools: true 를 설정해요:

# examples/code_mode.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Demonstrates the use of Code Mode with tools
    instruction: Use your tool to help the user with their github requests.
    code_mode_tools: true
    commands:
      demo: How many issues in docker/docker-agent have a number that is prime?
    toolsets:
      - type: mcp
        ref: docker:github-official

에이전트에 구성된 모든 toolset(여기서는 GitHub MCP 서버)이 래핑돼요: 모델은 더 이상 개별 GitHub 도구를 보지 않고 run_tools_with_javascript 만 보며, 각 래핑된 도구는 설명 안에 TypeScript 인터페이스, 타입 별칭, 함수 선언으로 문서화돼요.

개별 구성과 무관하게 실행의 모든 에이전트에 Code Mode를 강제하려면 --code-mode-tools CLI 플래그(또는 동등한 --code-mode-tools 런타임 구성 플래그, run, run --exec, serve api, serve mcp, 에이전트를 로드하는 다른 명령들에서 허용)를 사용해요:

$ docker agent run agent.yaml --code-mode-tools

도움이 될 때 (When It Helps)

Code Mode는 에이전트의 작업이 일반적으로 많은 도구 호출을 체인으로 연결해야 할 때 활성화할 가치가 있어요, 특히 그 사이에 조건부 로직이나 필터링이 있을 때 — 예를 들어 큰 결과 집합을 페이지네이션하거나, 여러 API 호출을 교차 참조하거나, 큰 페이로드를 모델이 실제로 보기 전에 필요한 몇 개 필드로 줄이는 것. 각각이 여러 번 대신 한 번의 모델 턴이 되므로, 도구 호출/응답 왕복에서 대기 시간과 토큰 지출을 모두 줄여요.

그것은 직접 도구 호출의 일반 목적 대체품은 아니에요: 턴당 한두 개의 독립 도구 호출만 주로 하는 에이전트라면, Code Mode는 실제 이점 없이 스크립트 작성과 추론의 오버헤드를 더해요.

한계와 보안 참고 (Limits & Security Notes)

  • 문자열 결과 하나. 스크립트는 문자열을 반환해야 해요; 예상대로 동작하지 않으면 console.* 를 사용해 디버그 정보를 출력하세요 — 결과와 함께 stdout/stderr로 돌아와요.
  • 실패는 진단 가능. 스크립트가 예외를 던지거나 예상치 못하게 반환하면, 응답에는 실패 전에 만든 도구 호출(이름, 인자, 결과 또는 에러)이 포함되어 모델이 무슨 일이 있었는지 보고 다음 시도에서 조정할 수 있어요.
  • 모든 도구가 래핑되는 건 아님. todo 카테고리의 도구는 스크립트 환경에서 제외되고 일반 도구로 직접 호출 가능한 채로 남아요 — Code Mode는 그것들을 대체하지 않아요.
  • 스크립트는 임베디드 샌드박스 JS 엔진(goja)에서 실행되지, Node.js나 브라우저가 아니에요: 주입된 도구 함수 너머의 파일시스템, 네트워크, 프로세스 접근은 없어요.

권한 및 도구 승인과의 상호작용 (Interaction With Permissions and Tool Approval)

권한과 대화형 도구 호출 승인은 런타임이 모델이 요청한 도구 호출을 디스패치할 때 시행돼요 — Code Mode가 활성화된 상태에서는 그것이 오직 run_tools_with_javascript 자체예요. 스크립트가 그 JavaScript 안에서 만드는 개별 도구 호출은 직접 호출되며 두 번째 권한 검사나 승인 프롬프트를 거치지 않아요.

실무적으로 이는 code_mode_tools 를 활성화하면 승인 세분성이 "도구 호출당 프롬프트 하나"에서 "전체 스크립트당 프롬프트 하나"로 줄어든다는 뜻이에요. 그 단일 승인을 스크립트의 toolset이 할 수 있는 모든 것을 승인하는 것으로 취급하세요:

Warning 더 거친 승인 세분성 (Coarser approval granularity) run_tools_with_javascript 호출을 승인하면 내부적으로 호출할 수 있는 모든 도구를 승인하는 것이며, 별도의 물음이 필요하거나 Permissions의 deny 패턴으로 막혔을 것을 포함해요. 에이전트의 toolset에 파괴적인 것이 있으면, 활성화 전에 Code Mode의 더 거친 세분성이 그 에이전트에 허용 가능한지 고려하세요. 별도의 비-Code-Mode 에이전트로 위임하는 것도 탈출구가 아니에요: handoff 와 transfer_task 는 code_mode_tools 가 켜지면 다른 도구처럼 래핑되지만 code-mode 호환 핸들러가 없어서, 모델의 스크립트가 그것들을 호출하려 하면 tool "handoff" is not available in code mode 를 받아요. 이것은 모델이 스크립트 안에서 위임을 선택하는 것만 배제할 뿐이에요: 에이전트에 구성된 force_handoff 대상은 Code Mode와 무관하게 에이전트의 턴이 자연히 멈춘 뒤에도 결정적으로 실행돼요, 런타임이 Code Mode가 대체하는 도구 호출 디스패치 경로 밖에서 적용하기 때문이에요. 파괴적인 toolset을 가진 다른 곳으로 핸드오프하거나 전송해야 하는 모델이 있는 에이전트에서는 code_mode_tools 를 꺼두세요.

더 알아보기 (Learn more)