에이전트 구성

에이전트 구성 (Agent Configuration)

YAML 구성에서 에이전트를 정의하기 위한 완전한 참조예요. 구성은 agents 아래에 최소 하나의 에이전트를 정의해야 해요.

출처: 문서

본문

전체 스키마 (Full Schema)

agents:
  agent_name:
    model: string # Required: model reference
    description: string # Required: what this agent does
    instruction: string # Required (unless instruction_file): system prompt
    instruction_file: string | [list] # Optional: load the system prompt from one or more files relative to this config (mutually exclusive with instruction)
    sub_agents: [list] # Optional: local or external sub-agent references
    toolsets: [list] # Optional: tool configurations (use `type: rag` for RAG sources)
    fallback: # Optional: fallback config
      models: [list]
      retries: 2
      cooldown: 1m
    add_date: boolean # Optional: add date to context
    add_environment_info: boolean # Optional: add env info to context
    add_prompt_files: [list] # Optional: include additional prompt files
    add_description_parameter: bool # Optional: add description to tool schema
    redact_secrets: boolean # Optional: scrub detected secrets out of tool args, outgoing chat messages, and tool output
    code_mode_tools: boolean # Optional: let the agent write JavaScript to orchestrate tool calls (see Code Mode)
    max_iterations: int # Optional: max tool-calling loops
    max_consecutive_tool_calls: int # Optional: max identical consecutive tool calls
    max_old_tool_call_tokens: int # Optional: token budget for old tool call content (disabled unless positive)
    max_tool_result_tokens: int # Optional: per-tool-result token cap with middle-out truncation (disabled unless positive)
    num_history_items: int # Optional: limit conversation history
    session_compaction: boolean # Optional: disable automatic session compaction (default: true)
    compaction_threshold: float # Optional: context-window fraction that triggers auto-compaction (0–1, default: 0.9)
    compaction_model: string # Optional: model used for session-compaction (summary generation)
    use_toolsets: [list] # Optional: names of top-level toolsets to merge into this agent
    readonly: boolean # Optional: restrict all toolsets to read-only tools only
    skills: boolean | [list] # Optional: enable skill discovery (true/false or list of names and/or sources)
    use_commands: [list] # Optional: names of top-level commands groups to merge into this agent
    use_skills: [list] # Optional: names of top-level skills groups to merge into this agent
    commands: # Optional: named prompts
      name: "prompt text" # or {instruction: "prompt", agent: "sub_agent_name"} or {url: "https://..."} (TUI only)
    welcome_message: string # Optional: message shown at session start
    handoffs: [list] # Optional: agent names this agent can hand off to
    force_handoff: string # Optional: agent that always receives the conversation when this agent stops
    hooks: # Optional: lifecycle hooks
      pre_tool_use: [list]
      tool_response_transform: [list]
      post_tool_use: [list]
      session_start: [list]
      session_end: [list]
      on_user_input: [list]
      stop: [list]
      notification: [list]
    structured_output: # Optional: constrain output format
      name: string
      schema: object
    cache: # Optional: response cache (skip the model on repeat questions)
      enabled: boolean
      case_sensitive: boolean
      trim_spaces: boolean
      path: string
    harness: # Optional: delegate to an external coding CLI (Claude Code, Codex, opencode, pi)
      type: string # Required: claude-code | codex | opencode | pi
      model: string # Optional: model override forwarded to the CLI (omit for the CLI's own default)
      effort: string # claude-code only: low | medium | high | xhigh | max (omit for the Claude Code default)
      agent: string # opencode only: agent profile name
      thinking: boolean # opencode only: enable extended thinking

Tip 참고 (See also) 모델 파라미터는 Model Config, 도구 상세는 Tool Config, 다중 에이전트 패턴은 Multi-Agent 참고.

속성 참조 (Properties Reference)

Property Type Required Description
model string ✓ 모델 참조. 인라인(openai/gpt-5) 또는 models 섹션의 이름 있는 모델.
description string ✓ 에이전트 목적에 대한 간략한 설명. 조정자가 위임을 결정할 때 사용.
instruction string ✓ 에이전트의 행동, 성격, 제약을 정의하는 시스템 프롬프트. instruction_file 이 설정되지 않으면 필수.
instruction_file string | array ✗ (구성 파일의 디렉터리에 상대적인) 파일 경로들. 그 내용이 에이전트의 지침이 되며 시작 시 로드돼요. 단일 경로 또는 목록을 받고, 여러 파일은 순서대로 빈 줄로 구분되어 연결돼요. instruction 과는 상호 배타적이에요. 각 경로는 구성 디렉터리 안의 로컬 상대 경로여야 해요 (절대 경로와 .. 탐색은 거부됨). 로컬 파일 기반 구성에서만 지원되며 OCI/URL 소스에서는 안 돼요. 아래 External Instruction Files 참고.
sub_agents array ✗ 이 에이전트가 위임할 수 있는 에이전트 이름 또는 외부 OCI 참조 목록. 로컬 에이전트, 레지스트리 참조(예: myorg/agent:tag), 이름 있는 참조(name:reference)를 지원해요. transfer_task 도구를 자동으로 활성화해요. 외부 OCI 참조는 실행당 레지스트리 조회를 피하려면 다이제스트(name@sha256:…)로 고정하세요. External Sub-Agents 참고.
toolsets array ✗ 도구 구성 목록. Tool Config 참고.
fallback object ✗ 자동 모델 페일오버 구성.
add_date boolean ✗ true 일 때 현재 날짜를 에이전트 컨텍스트에 주입.
add_environment_info boolean ✗ true 일 때 작업 디렉터리, OS, CPU 아키텍처, git 정보를 컨텍스트에 주입.
add_prompt_files array ✗ 내용이 시스템 프롬프트에 추가되는 파일 경로 목록. 코딩 표준, 가이드라인, 추가 컨텍스트 포함에 유용.
add_description_parameter boolean ✗ true 일 때 도구 스키마에 에이전트 설명을 파라미터로 추가. 다중 에이전트 시나리오에서 도구 선택에 도움.
redact_secrets boolean ✗ true 일 때 감지된 시크릿(API 키, 토큰, 개인 키 등)을 도구가 보기 전에 도구 호출 인자, 전송 중인 채팅 메시지, 도구 출력에서 지워요. 아래 Redacting Secrets 참고.
code_mode_tools boolean ✗ true 일 때 에이전트의 개별 도구들을, 한 턴에 필요한 만큼 호출하는 JavaScript 스크립트를 실행하는 단일 도구로 대체. Code Mode 참고.
max_iterations int ✗ 최대 도구 호출 루프 수. 기본값: 무제한(0). 무한 루프를 막도록 설정하세요.
max_consecutive_tool_calls int ✗ 에이전트가 종료되기 전까지의 연속 동일 도구 호출 최대 수. 퇴화 루프를 방지. 기본값: 5.
max_old_tool_call_tokens int ✗ 이전 도구 호출 인자와 결과에서 유지할 최대 토큰 수. 이 버짓을 넘는 오래된 도구 호출은 내용이 플레이스홀더로 대체되어 컨텍스트 공간을 절약해요. 토큰은 len/4 로 근사돼요. 잘림은 기본적으로 비활성화되어 있고, 양수 값을 설정하면 활성화돼요. -1 로 설정하면 잘림을 비활성화(무제한)해요.
max_tool_result_tokens int ✗ 각 도구 결과에서 세션에 추가될 때 유지할 최대 토큰 수. 과대 결과는 중간부터 잘려요: 앞과 뒤는 유지되고 제거된 중간은 잘림 마커로 대체돼요. 결과에 첨부된 텍스트 문서도 같은 버짓을 공유해요. 토큰은 len/4 로 근사돼요. 상한은 기본적으로 비활성화되어 있고, 양수 값을 설정하면 활성화돼요. 0 과 -1 은 도구 결과를 무제한으로 둬요.
num_history_items int ✗ 모델로 보내는 대화 기록 메시지 수 제한. 긴 대화에서 컨텍스트 창 크기 관리에 유용. 기본값: 무제한(모든 메시지 전송).
session_compaction boolean ✗ false 일 때 이 에이전트의 자동 세션 압축을 비활성화: 사전 예방적 임계값 트리거와 오버플로 후 자동 복구 모두 실행되지 않아요. 수동 /compact 명령은 계속 사용 가능. 기본값: true. Context & Compaction 가이드 참고.
compaction_threshold float ✗ 사전 예방적 자동 압축이 트리거되는 모델 컨텍스트 창의 비율. 0 보다 크고 최대 1 이어야 해요. 에이전트의 모델에 설정된 compaction_threshold 가 우선해요. 기본값: 0.9. Context & Compaction 가이드 참고.
compaction_model string ✗ 세션 압축(요약 생성)에 사용되는 모델. 이름 있는 모델 또는 인라인 provider/model 문자열일 수 있어요. 이 에이전트 레벨 값이 모델이나 제공자에 설정된 compaction_model 보다 우선해요; 아무것도 설정되지 않으면 에이전트 자신의 모델이 압축해요. Context & Compaction 가이드 참고.
skills bool/array ✗ 자동 스킬 발견 활성화. true 는 발견된 모든 로컬 스킬을 로드하고, false 는 비활성화. 목록은 스킬 소스(local 또는 https://… URL)와 포함할 스킬 이름을 섞을 수 있어요 — Skills 참고.
commands object ✗ docker agent run config.yaml /command_name 으로 실행할 수 있는 이름 있는 프롬프트. 단순 문자열이거나, 에이전트 전환을 위한 instruction 및/또는 agent 필드가 있는 객체, 또는 브라우저에서 링크를 여는 url 필드일 수 있어요(TUI 전용). 아래 Named Commands 참고.
use_commands list of string ✗ 이 에이전트에 병합할 최상위 commands 그룹 이름. 이름 충돌 시 인라인 commands 항목이 우선해요. 기본값: [].
use_skills list of string ✗ 이 에이전트에 병합할 최상위 skills 그룹 이름. 인라인 스킬은 병합된 항목과 이름으로 중복 제거돼요. 기본값: [].
use_toolsets list of string ✗ 이 에이전트에 병합할 최상위 toolsets 그룹 이름. Reusable Toolsets 참고. 기본값: [].
readonly boolean ✗ true 일 때 이 에이전트의 모든 toolset이 읽기 전용 도구(읽기 전용 힌트로 주석 처리된 것)만 노출하도록 필터링돼요. 변경 도구는 로드 시 제거되며 모델이 시도해도 호출할 수 없어요. 아래 Read-Only Agents 참고.
welcome_message string ✗ 세션이 시작될 때 사용자에게 표시되는 메시지. TUI에서 Markdown으로 렌더링돼요. 모델에는 보내지 않아요 — 순전히 사용자의 이익을 위한 것. 에이전트가 무엇을 할 수 있고 어떤 명령이 있는지 알려주는 데 유용.
handoffs array ✗ 이 에이전트가 대화를 핸드오프할 수 있는 에이전트 이름 목록. handoff 도구를 활성화해요. Handoffs Routing 참고.
force_handoff string ✗ 이 에이전트가 최종 응답을 만들 때마다 무조건 대화를 받는 에이전트 이름. 런타임이 LLM의 도구 호출을 우회해 스위치 자체를 수행하여 결정적 파이프라인을 보장해요. 자기 자신을 참조하면 안 되고, 체인은 순환을 형성하면 안 돼요. Forced Handoffs 참고.
hooks object ✗ 다양한 시점에 명령을 실행하기 위한 수명 주기 훅. Hooks 참고.
structured_output object ✗ 에이전트 출력을 JSON 스키마와 일치하도록 제약. Structured Output 참고.
cache object ✗ 응답 캐시. 같은 사용자 질문이 다시 물어지면 이전 답변이 그대로 재생되고 모델은 호출되지 않아요. 아래 Response Cache 참고.
harness object ✗ 모델 대신 외부 코딩 CLI를 통해 이 에이전트를 실행. 참고: 같은 에이전트에 정의된 toolsets: 는 harness: 가 설정되면 조용히 무시돼요 — 외부 CLI가 자체 도구를 가져와요. Coding Harnesses 참고.

Warning max_iterations 기본값은 0(무제한)이에요. shell 같은 강력한 도구를 가진 에이전트에는 무한 루프를 막기 위해 항상 max_iterations 를 설정하세요. 개발 에이전트에는 20~50 값이 일반적이에요.

Tip 긴 세션 관리 (Managing long sessions) max_old_tool_call_tokens, max_tool_result_tokens, num_history_items, session_compaction, compaction_threshold 는 모두 오래 실행되는 세션을 모델 컨텍스트 창 안에 유지하는 데 도움돼요. 그것들을 결합하는 방법은 Context & Compaction 가이드 참고.

외부 지침 파일 (External Instruction Files)

긴 시스템 프롬프트는 YAML에 인라인하는 대신 instruction_file 로 자체 파일에 보관할 수 있어요. 이렇게 하면 인프라 구성(모델, 제공자, 도구)과 행동 콘텐츠(프롬프트)를 분리해서, 버전 관리 diff를 초점화하고 공유 구성의 병합 충돌을 줄이며, YAML 구문 오류를 위험에 빠뜨리지 않고 지침 콘텐츠를 편집할 수 있어요.

agents:
  coordinator:
    model: openai/gpt-5-mini
    description: Routes work between specialist agents
    instruction_file: instructions/coordinator.md
    sub_agents:
      - writer
  writer:
    model: openai/gpt-5-mini
    description: Drafts and edits written content
    instruction_file: instructions/writer.md

경로는 구성 파일의 디렉터리에 상대적으로 해석되고, 파일 내용은 구성이 로드될 때 에이전트의 지침으로 로드돼요. 참고:

  • instruction 과 상호 배타적이에요. 둘 다 설정하면 에러예요.
  • 각 경로는 구성 디렉터리 안의 로컬 상대 경로여야 해요. 절대 경로와 .. 탐색은 거부돼요.
  • 파일 목록도 허용돼요; 내용은 순서대로 빈 줄로 구분되어 연결돼요. 이렇게 하면 공유 서문(preamble)을 여러 에이전트에서 재사용하면서 각 에이전트가 자신만의 세부 사항을 덧붙일 수 있어요:
agents:
  writer:
    model: openai/gpt-5-mini
    description: Drafts and edits written content
    instruction_file:
      - instructions/shared-preamble.md
      - instructions/writer.md
  • 로컬 파일 기반 구성에서만 지원돼요, OCI 레지스트리나 URL에서 로드된 에이전트는 아니에요. 에이전트를 docker agent share push 로 푸시하면 파일 내용이 푸시된 아티팩트에 인라인되므로, 게시된 에이전트는 자체 포함성을 유지해요.

실행 가능한 예제는 examples/instruction_file.yaml 에 있어요.

프롬프트 파일 (Prompt Files)

add_prompt_files 는 매 턴 시작마다 하나 이상의 파일 내용을 에이전트 컨텍스트에 주입해요 — instruction 에 붙여넣지 않고도 사용할 수 있어야 하는 AGENTS.md 나 CLAUDE.md 같은 저장소 전체 규칙에 편리해요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A helpful coding assistant
    instruction: You are an expert software developer.
    add_prompt_files:
      - AGENTS.md

각 이름에 대해 에이전트는 현재 작업 디렉터리에서 위로 올라가며 가장 가까운 일치 항목을 로드하고, (다른 파일이라면) 사용자 홈 디렉터리 바로 아래에 같은 이름의 복사본도 로드해요 — 그래서 개인 ~/AGENTS.md 가 저장소 로컬 것 위에 레이어될 수 있어요. 없는 파일은 에러 대신 건너뛰어요. 해석과 읽기가 매 턴마다 일어나므로, 파일 편집은 에이전트를 재시작하지 않고도 반영돼요.

구성을 편집하지 않고 단일 실행에 파일을 추가하려면 --prompt-file 을 사용하세요. 이미 에이전트에 설정된 add_prompt_files 와 병합되고 중복은 제거돼요:

$ docker agent run agent.yaml --prompt-file CONTRIBUTING.md

해석된 프롬프트 파일은 /context 대화상자에 각자 항목으로 나타나요 — Terminal UI 가이드의 File Attachments 참고.

프롬프트 파일이 @ / /attach 첨부, rag toolset, API/챗 서버를 통한 콘텐츠 전송과 어떻게 비교되는지는 Choosing a Large-Input Strategy 참고.

응답 캐시 (Response Cache)

응답 캐시는 같은 사용자 질문이 다시 물어질 때 모델을 단락(short-circuit)시켜요. 질문이 처음 물어지면 에이전트가 정상적으로 모델을 호출하고 어시스턴트 답변을 저장해요. 이후 동일한 질문은 모델을 완전히 건너뛰고 저장된 답변을 그대로 재생해요.

agents:
  root:
    model: openai/gpt-5
    description: Cached assistant
    instruction: You are a helpful assistant.
    cache:
      enabled: true # required to turn the cache on
      case_sensitive: false # default: false ("Hello" == "hello")
      trim_spaces: true # default: false (" hello " == "hello")
      path: ./cache.json # optional: persist to disk; omit for in-memory
Property Type Default Description
enabled boolean false 마스터 스위치. false 일 때(또는 cache 섹션이 생략될 때) 캐싱은 수행되지 않아요.
case_sensitive boolean false true 일 때 질문이 (대소문자 포함) 정확히 일치해야 캐시에 적중해요.
trim_spaces boolean false true 일 때 비교 전에 질문의 앞뒤 공백이 제거돼요.
path string empty 설정되면 캐시 항목이 해당 경로의 JSON 파일에 유지되고 시작 시 다시 로드되어 캐시가 재시작 후에도 유지돼요. 상대 경로는 에이전트 구성 디렉터리에 대해 해석돼요. 비어 있으면 캐시는 메모리에만 존재해요.

동작 원리 (How it works)

  • 캐시 키는 세션의 최신 사용자 메시지이며, case_sensitive 와 trim_spaces 에 따라 정규화돼요.
  • 적중 시 캐시된 답변이 어시스턴트 메시지로 세션에 추가되고 stop 훅이 정상적으로 발동돼요 — 에이전트의 나머지(도구, 하위 에이전트, 모델)는 우회돼요.
  • 미스 시 에이전트가 정상적으로 실행되고, 실행의 첫 번째 stop이 만든 최종 어시스턴트 메시지가 질문의 키로 저장돼요.
  • 실행의 원래 사용자 질문에 대한 응답만 캐시돼요; 같은 RunStream 안의 후속 턴은 캐시되지 않아요.

파일 기반 저장소 (File-backed storage)

path 가 설정되면 매 Store가 전체 캐시 파일을 다시 써요. 쓰기는 원자적이에요: 새 콘텐츠를 형제 임시 파일에 쓰고, fsync 한 뒤 대상 위로 이름을 바꿔요. 그래서 동시 읽는 사람(또는 쓰기 중에 크래시하는 프로세스)은 항상 이전 콘텐츠나 새 콘텐츠 중 하나를 완전히 보게 돼요 — 절대 부분적으로 쓰인 파일을 보지 않아요. 이름 변경 후 부모 디렉터리도 fsync 되어 이름 변경 자체가 영속적이게 해요.

프로세스 간 공유 (Cross-process sharing)

여러 프로세스가 같은 path 캐시 파일을 안전하게 공유할 수 있어요. 매 Store가 형제 <path>.lock 파일(Unix에서는 POSIX flock(2), Windows에서는 LockFileEx)에 독점 조언 잠금을 걸고, 잠금 아래에서 현재 온디스크 상태를 다시 로드하고, 새 항목을 병합하고, 원자적으로 다시 써요. 서로 다른 키를 동시에 저장하는 두 프로세스는 둘 다 자신의 쓰기가 디스크에 보존되는 것을 봐요; 잠금 창은 짧아요(읽기 하나 + fsync된 쓰기 하나).

조회는 파일의 수정 시간을 보고, 파일이 마지막 로드 이후 진행되었으면 인메모리 맵을 다시 로드하므로 형제 프로세스의 쓰기가 재시작 없이 보여요. <path>.lock 센티널 파일은 첫 쓰기 시 생성되고 절대 삭제되지 않아요: 삭제하면 두 프로세스가 다른 inode를 잠그고 상호 배제를 잃을 수 있기 때문이에요.

시크릿 지우기 (Redacting Secrets)

redact_secrets 플래그는 실수로 노출된 자격 증명, 토큰, 개인 키를 에이전트의 I/O에서 지우는 단일 에이전트 레벨 스위치예요. 세 가지 보완 방어를 연결해요:

  • 도구가 보기 전에 모든 도구 호출의 인자에서 감지된 시크릿을 지우는 pre_tool_use 내장 훅.
  • 모델 제공자에 도달하기 전에 전송 중인 채팅 메시지 — 메시지 콘텐츠, 다중 부품 텍스트 콘텐츠, 이전 추론 콘텐츠, 대화에 남아 있는 도구 호출의 JSON 인코딩 인자 — 에서 같은 패턴을 지우는 before_llm_call 내장 훅.
  • 원천에서 도구 출력을 지우는 tool_response_transform 내장 훅. 그래서 시크릿이 이벤트 소비자, 영속 세션 파일, post_tool_use 훅 입력, 다음 LLM 호출에 닿지 않아요.
agents:
  root:
    model: openai/gpt-5
    description: A helpful assistant that scrubs secrets before they leak
    instruction: |
      You are a helpful assistant. If the user accidentally pastes a token,
      do your best work without echoing the secret back.
    redact_secrets: true
    toolsets:
      - type: shell

감지는 portcullis 규칙셋을 사용하며, 다음을 포함한 일반적인 시크릿 패턴을 인식해요:

  • GitHub Personal Access Tokens (ghp_*, gho_*, ghu_*, ghs_*, ghr_*, fine-grained github_pat_*)
  • AWS access keys (AKIA*, ASIA*, …) 및 secret access keys
  • GitLab PATs (glpat-*), Hugging Face tokens (hf_*)
  • Stripe (sk_live_*, pk_test_*, …), Slack (xoxb-*, …), Shopify, Twilio, Discord, Atlassian, Mailchimp, SendGrid 등 다수
  • JWTs, GCP service-account JSON, Heroku keys, Docker Hub PATs (dckr_pat_*)
  • PEM 인코딩 개인 키 (-----BEGIN … PRIVATE KEY----- 블록)

감지된 각 span은 리터럴 문자열 [REDACTED] 로 대체되고, 주변 텍스트는 보존되어 지워진 인자가 여전히 합법적인 플래그처럼 보여요(예: --token=[REDACTED]). 지우기는 멱등적이에요 — 두 번 적용해도 같은 결과예요.

Note 오탐 vs. 누탐 (False positives vs. false negatives) 오탐은 극히 드물어요: 모든 규칙이 정규식과 식별 키워드를 짝지으므로 평범한 영어는 탐지를 유발하지 않아요. 누탐은 가능해요 — 규칙셋이 인식하는 패턴만 지워지므로, 이것은 심층 방어(defense-in-depth) 기능이지 처음부터 대화에 시크릿을 두지 않게 하는 것의 대체는 아니에요. 에이전트가 실제로 필요로 하는 자격 증명에는 적절한 시크릿 관리자를 함께 사용하세요.

Note 동등한 훅 항목 (Equivalent hook entry) 에이전트에 redact_secrets: true 를 설정하는 것은 이 기능의 세 가지 다리를 훅 항목으로 자동 등록하는 약칭이에요. 그것들은 pre_tool_use, before_llm_call, tool_response_transform 에 각각 같은 내장 이름(type: builtin, command: redact_secrets)을 공유해요 — 구현은 훅 이벤트에 따라 분기해요. 수동으로 풀어서 다리를 도구 하위 집합으로 범위를 한정하거나(matcher: 를 정규식으로 설정), 특정 순서로 다른 rewriter와 쌓거나, 하나 또는 두 개의 다리만 활성화할 수 있어요. 완전한 수동 배선은 examples/redact_secrets_hooks.yaml 을, 내장의 이벤트 범위는 Hooks 참조를 참고하세요.

환영 메시지 (Welcome Message)

사용자가 세션을 시작할 때 메시지를 표시해요:

agents:
  assistant:
    model: openai/gpt-5
    description: Development assistant
    instruction: You are a helpful coding assistant.
    welcome_message: |
      👋 Welcome! I'm your development assistant.

      I can help you with:
      - Writing and reviewing code
      - Running tests and debugging
      - Explaining concepts

      What would you like to work on?

지연 도구 로딩 (Deferred Tool Loading)

Toolsets는 defer 를 지원해 도구를 온디맨드로 로드하고 에이전트 시작을 빠르게 해요. 자세한 내용은 Deferred Tool Loading 참고.

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Multi-purpose assistant
    instruction: You have access to many tools.
    toolsets:
      - type: mcp
        ref: docker:github-official
        defer: true
      - type: filesystem

폴백 구성 (Fallback Configuration)

기본 모델이 실패하면 백업 모델로 자동 전환해요:

Property Type Default Description
models array [] 순서대로 시도할 폴백 모델
retries int 2 5xx 에러에 대한 모델당 재시도. -1 로 비활성화.
cooldown string 1m 요청 제한(429) 후 폴백을 유지할 시간

에러 처리:

  • 재시도 가능 (같은 모델, 백오프 포함): HTTP 5xx, 408, 네트워크 타임아웃
  • 비재시도 (다음 모델로 건너뜀): HTTP 429, 4xx 클라이언트 에러
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    fallback:
      models:
        - openai/gpt-5
        - google/gemini-3.5-flash
      retries: 2
      cooldown: 1m

이름 있는 명령 (Named Commands)

Tip 전체 참조 이 섹션은 기본을 다뤄요. URL 명령, 에이전트 전환 명령, 재사용 가능한 최상위 commands 그룹, --disable-commands 로 명령 숨기기는 Custom Commands 참고.

현재 에이전트에 프롬프트를 보내거나, 다른 하위 에이전트로 전환하거나, 브라우저에서 URL을 열 수 있는 재사용 가능한 프롬프트 단축키를 정의해요:

참고: 이름 있는 슬래시 명령은 에이전트가 다른 메시지를 처리하는 동안에도 즉시 실행돼요. 일반 채팅 메시지(큐에 쌓임)와 달리 슬래시 명령은 에이전트가 응답 중이어도 방해하거나 방향을 조정해요.

agents:
  root:
    model: openai/gpt-5
    instruction: You are a system administrator.
    commands:
      df: "Check how much free space I have on my disk"
      logs: "Show me the last 50 lines of system logs"
      greet: "Say hello to ${env.USER}"
      deploy: "Deploy ${env.PROJECT_NAME || 'app'} to ${env.ENV || 'staging'}"

  # Advanced format with agent switching
      plan:
        agent: planner # Switch to the 'planner' agent
        instruction: "Create a detailed plan for: ${args.join(\" \")}" # Optional: send this prompt after switching

  # Agent switching without instruction - forwards remaining text as prompt
      review:
        agent: reviewer # Any text after /review is sent to the reviewer agent

  # URL command - opens a link in the browser instead of messaging the agent
      docs:
        description: "Open the documentation"
        url: https://docs.docker.com/

명령 형식 (Command Formats)

명령은 세 가지 형식을 지원해요:

  • 단순 문자열 형식: 문자열이 현재 에이전트로 보내지는 지침이 돼요
df: "Check disk space"
  • 고급 객체 형식: 에이전트 전환과 선택적 지침을 지원
plan:
  agent: planner # Required: name of any agent defined in the team
  instruction: "Plan: ${args.join(\" \")}" # Optional: prompt to send after switching
  description: "Switch to planning mode" # Optional: shown in help text
  • URL 형식: 에이전트에 메시지를 보내는 대신 브라우저에서 링크를 열어요
docs:
  url: https://docs.docker.com/ # Required: URL to open
  description: "Open the documentation" # Optional: shown in help text

instruction 없이 agent 가 설정되면, 슬래시 명령 뒤에 타이핑된 텍스트(예: /plan build a web app)는 대상 에이전트에게 프롬프트로 전달돼요. 대상 에이전트는 팀 구성에 정의된 어떤 에이전트든 될 수 있어요 — 현재 에이전트의 sub_agents 배열에 있을 필요는 없어요.

인자 및 확장 구문 (Argument and expansion syntax)

지침 문자열은 명령의 인자를 참조하고 도구 호출을 확장할 수 있어요:

  • ${args[0]}, ${args[1]}, … — 사용자가 명령 뒤에 타이핑한 순서대로 개별 위치 인자
  • ${args.join(" ")} — 모든 인자를 단일 문자열로 결합
  • ${tool_name({...})} — 도구를 호출하고 그 반환 값을 인라인 (에이전트가 사용 가능한 어떤 도구든)
  • !tool_name(key=value) — 레거시 도구 호출 형식: 평문 key=value 인자로 도구를 호출하고 그 출력을 인라인

에이전트 전환 명령 (Agent-Switching Commands)

agent 필드가 있는 명령은 해당 명령의 범위에 대해 활성 에이전트를 전환해요. /plan, /review, /deploy 가 각각 사용자를 적절한 전문가에게 라우팅하는 워크플로 단축키를 만드는 데 유용해요.

agents:
  root:
    model: openai/gpt-5
    description: Main assistant
    instruction: You are a project coordinator.
    sub_agents: [planner, reviewer]
    commands:
      # Switch to planner with a pre-filled prompt
      plan:
        agent: planner
        instruction: "Create a detailed plan for: ${args.join(\" \")}"
      # Switch to reviewer; any text after /review is forwarded
      review:
        agent: reviewer
      # Simple prompt command (no switching)
      status: "Summarize what we have accomplished so far"

  planner:
    model: openai/gpt-5
    description: Planning specialist
    instruction: You create detailed project plans.

  reviewer:
    model: anthropic/claude-sonnet-4-5
    description: Code review specialist
    instruction: You review code and suggest improvements.

에이전트 전환 vs. 핸드오프 (Agent-switching vs. handoff)

Agent-switching command handoff tool
트리거 사용자가 /command 실행 모델이 handoff() 호출
세션 같은 세션에 유지 같은 세션에 유지
기록 대상 에이전트가 전체 대화 기록을 봄 대상 에이전트가 전체 대화 기록을 봄
복귀 사용자가 명시적으로 다시 전환해야 함 대상 에이전트가 다른 에이전트로 체인 가능

에이전트 전환 vs. transfer_task

transfer_task 는 하위 세션을 시작해요: 루트 에이전트가 작업을 보내고, 자식이 격리되어 실행되며, 결과가 루트로 반환돼요. 루트 에이전트는 통제권을 유지하고 자식의 작업은 메인 대화에 절대 들어오지 않아요. 깨끗한 결과와 함께 위임을 원하면 transfer_task(sub_agents 를 통해)를 사용하고, 대화의 나머지 동안 다른 에이전트가 되기를 원하면 에이전트 전환 명령을 사용하세요.

완전한 예제는 examples/agent_switching_commands.yaml 참고.

# Run commands from the CLI
$ docker agent run agent.yaml /df
$ docker agent run agent.yaml /greet
$ PROJECT_NAME=myapp ENV=production docker agent run agent.yaml /deploy

명령은 환경 변수 보간에 JavaScript 템플릿 리터럴 구문(${env.VAR})을 사용해요. 정의되지 않은 변수는 빈 문자열로 확장돼요.

같은 구문이 에이전트와 toolset 지침에서도 확장돼요: agents.<name>.instruction 과 toolsets[*].instruction 은 ${env.X} 플레이스홀더(선택적 || 기본값과 삼항 표현식)를 지원해요. agents.<name>.description 과 agents.<name>.welcome_message 도 지원해요.

working_dir, path 같은 경로 형 필드는 주로 셸 스타일 구문($VAR, ${VAR}, ~)을 사용하고, ${env.X} 를 별칭으로도 받아요(더 풍부한 JS 표현식은 제외). 전체 표는 Variable Expansion in Config Fields 참고.

URL 명령 (URL Commands)

url 필드가 있는 명령은 에이전트에 프롬프트를 보내는 대신 사용자의 기본 브라우저에서 그 URL을 열어요. OS가 디스패치하는 법을 아는 어떤 URI 스킴이든 동작해요 — 표준 웹 URL과, 딥 링크용 docker-desktop:// 같은 커스텀 스킴 모두요. URL 명령은 TUI 전용이에요 — CLI에서 실행하면 효과가 없어요.

agents:
  root:
    model: openai/gpt-5
    description: An agent with handy URL shortcuts.
    instruction: You are a helpful assistant.
    commands:
      feedback:
        description: "Open the feedback site for this session"
        url: https://example.com/feedback?session={{session_id}}
      docs:
        description: "Open the documentation"
        url: https://docs.docker.com/
      desktop:
        description: "Open this session in Docker Desktop"
        url: docker-desktop://dashboard/session/{{session_id}}

{{session_id}} 토큰은 호출 시점에 현재 세션 ID로 대체돼요(URL을 깨뜨리거나 추가 쿼리 파라미터를 주입할 수 없도록 URL-쿼리 이스케이프됨). 그래서 명령이 대화에 범위가 한정된 무언가로 딥링크할 수 있게 해요. 이 토큰은 의도적으로 ${...} JS-확장 구문이 아닌 {{...}} 를 사용해요, 세션 ID가 디스패치 시점에만 알려지기 때문이에요.

URL은 OS 오프너에 넘기기 전에 검증돼요: 비어 있지 않은 스킴이 있는 파싱 가능한 URL이 요구되고, 플래그 같은 입력(- 로 시작하는 것)은 인자 주입을 막기 위해 거부돼요.

완전한 예제는 examples/url_commands.yaml 참고.

읽기 전용 에이전트 (Read-Only Agents)

에이전트에 readonly: true 를 설정하면 모든 toolset이 읽기 전용으로 주석 처리된 도구로만 제한돼요. 변경 도구는 로드 시 필터링되어 에이전트가 그것들을 나열하거나 호출할 수 없어요 — 모델이 호출을 환각하더라도요.

개별 toolset에 readonly: true 를 설정해 그 toolset만 제한하고 나머지는 제한 없이 둘 수도 있어요.

agents:
  # Agent-level readonly: every toolset is restricted to read-only tools.
  inspector:
    model: anthropic/claude-sonnet-4-5
    description: Read-only inspector that can explore but never modify.
    instruction: Explore the project. Do not make changes.
    readonly: true
    toolsets:
      - type: filesystem
      - type: shell

  # Toolset-level readonly: only the filesystem toolset is restricted;
  # the shell toolset keeps all of its tools.
  mixed:
    model: anthropic/claude-sonnet-4-5
    description: Read-only file access, full shell access.
    instruction: You can read files and run any shell command.
    toolsets:
      - type: filesystem
        readonly: true
      - type: shell

완전한 예제는 examples/readonly.yaml 참고.

Note 어떤 도구가 읽기 전용인가? 도구가 읽기 전용인지 여부는 ReadOnlyHint 주석으로 결정돼요. 내장 도구의 경우 읽기 전용 작업(list/read/search)은 힌트를 갖고, 변경 작업(write/delete/execute)은 갖지 않아요. 커스텀 및 MCP 도구는 자체 주석을 통해 힌트를 노출해요.

완전한 예제 (Complete Example)

models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-5
    max_tokens: 64000

agents:
  root:
    model: claude
    description: Technical lead coordinating development
    instruction: |
      You are a technical lead. Analyze requests and delegate
      to the right specialist. Always review work before responding.
    welcome_message: "👋 I'm your tech lead. How can I help today?"
    sub_agents: [developer, researcher]
    add_date: true
    add_environment_info: true
    fallback:
      models: [openai/gpt-5]
    toolsets:
      - type: think
    commands:
      review: "Review all recent code changes for issues"
    hooks:
      session_start:
        - type: command
          command: "./scripts/setup.sh"

  developer:
    model: claude
    description: Expert software developer
    instruction: Write clean, tested, production-ready code.
    max_iterations: 30
    toolsets:
      - type: filesystem
      - type: shell
      - type: think
      - type: todo

  researcher:
    model: openai/gpt-5
    description: Web researcher with memory
    instruction: Search for information and remember findings.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
      - type: memory
        path: ./research.db

더 알아보기 (Learn more)