구성 개요

구성 개요 (Configuration Overview)

Docker Agent는 YAML 또는 HCL 구성 파일을 사용해서 에이전트, 모델, 도구와 그 관계를 정의해요.

출처: 문서

본문

Docker Agent는 YAML 또는 HCL 구성 파일로 에이전트, 모델, 도구와 그 관계를 정의해요.

파일 구조 (File Structure)

Docker Agent 구성은 YAML이나 HCL로 작성할 수 있어요. 이 페이지의 예제는 YAML을 사용하지만, 블록 기반 HCL 문법은 HCL Configuration에서 확인할 수 있어요.

Docker Agent 구성에는 다음과 같은 주요 섹션이 있어요:

# 1. Version — configuration schema version (optional but recommended)
version: 15

# 2. Metadata — optional agent metadata for distribution
metadata:
  author: my-org
  description: My helpful agent
  version: "1.0.0"

# 3. Models — define AI models with their parameters
models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-5
    max_tokens: 64000

# 4. Agents — define AI agents with their behavior (at least one is required)
agents:
  root:
    model: claude
    description: A helpful assistant
    instruction: You are helpful.
    toolsets:
    - type: think

# 5. RAG — define retrieval-augmented generation sources (optional)
rag:
  docs:
    docs: [ "./docs" ]
  strategies:
  - type: chunked-embeddings
    embedding_model: openai/text-embedding-3-small

# 6. MCPs — reusable MCP server definitions (optional)
mcps:
  github:
    remote:
      url: https://api.githubcopilot.com/mcp
      transport_type: sse

# 7. Providers — optional reusable provider definitions
providers:
  my_provider:
    provider: anthropic # or openai (default), google, amazon-bedrock, etc.
    token_key: MY_API_KEY
    max_tokens: 16384

# 8. Permissions — agent-level tool permission rules (optional)
# For user-wide global permissions, see ~/.config/cagent/config.yaml
permissions:
  allow: [ "read_*" ]
  deny: [ "shell:cmd=sudo*" ]

# 9. Commands & Skills — reusable, named groups shared across agents (optional)
commands:
  ci:
    deploy: "Deploy the application"
skills:
  base: [ local, git ]

# 10. Toolsets — reusable, named toolset definitions shared across agents (optional)
toolsets:
  fs:
    type: filesystem

최소 구성 (Minimal Config)

가장 단순한 구성이에요 — 인라인 모델을 가진 에이전트 하나만 정의하면 돼요:

agents:
  root:
    model: openai/gpt-5
    description: A helpful assistant
    instruction: You are a helpful assistant.

같은 구성을 HCL로 쓰면 이렇게 돼요:

agent "root" {
  model = "openai/gpt-5"
  description = "A helpful assistant"
  instruction = "You are a helpful assistant."
}

인라인 vs 명명된 모델 (Inline vs Named Models)

모델은 인라인으로 참조하거나 models 섹션에서 정의할 수 있어요:

• Inline — 빠르고 단순해요. provider/model 문법을 바로 쓰면 돼요: model: openai/gpt-5
• Named — 파라미터를 완전히 제어할 수 있고 여러 에이전트에서 재사용할 수 있어요: model: my_claude

구성 섹션 (Config Sections)

• HCL Configuration — 라벨 블록, heredoc, 블록 기반 도구 정의로 같은 에이전트 스키마를 HCL로 작성해요.
• Agent Config — model, instruction, tools, sub-agents, hooks 등 모든 에이전트 속성.
• Model Config — provider 설정, 파라미터, thinking budget, provider별 옵션.
• Tool Config — 내장 도구, MCP 도구, Docker MCP, LSP, API 도구, 도구 필터링.

고급 구성 (Advanced Configuration)

• Hooks — 도구 호출이나 세션 시작/종료 같은 라이프사이클 이벤트에서 셸 명령을 실행해요.
• Permissions — 어떤 도구가 자동 승인되고, 확인이 필요하며, 차단되는지 제어해요.
• Sandbox Mode — 보안을 위해 에이전트를 격리된 Docker 컨테이너에서 실행해요.
• Structured Output — 에이전트 응답이 특정 JSON 스키마를 따르도록 제약해요.
• Flavors — 하나의 에이전트 파일에 명명된 변형을 담고 실행 시점에 YAML 패치로 활성화해요.

환경 변수 (Environment Variables)

API 키와 시크릿은 환경 변수에서 읽어요 — 구성 파일에 저장하지 않아요. 자격 증명을 제공하는 모든 방법(env 파일, Docker Compose secrets, Docker Agent env 파일)은 Managing Secrets에서 확인할 수 있어요:

변수	Provider
OPENAI_API_KEY	OpenAI
ANTHROPIC_API_KEY	Anthropic
GOOGLE_API_KEY / GEMINI_API_KEY	Google Gemini
MISTRAL_API_KEY	Mistral
XAI_API_KEY	xAI
NEBIUS_API_KEY	Nebius
MINIMAX_API_KEY	MiniMax
REQUESTY_API_KEY	Requesty
OPENROUTER_API_KEY	OpenRouter
GITHUB_TOKEN	GitHub Copilot (copilot scope가 있는 PAT)
AZURE_API_KEY	Azure OpenAI (token_key로 재정의 가능)
AWS_BEARER_TOKEN_BEDROCK	AWS Bedrock (또는 표준 AWS 자격 증명 체인)

도구 자동 설치:

변수	설명
DOCKER_AGENT_AUTO_INSTALL	false로 설정하면 도구 자동 설치를 비활성화해요
DOCKER_AGENT_TOOLS_DIR	설치된 도구의 기본 디렉토리를 재정의해요 (기본값: ~/.cagent/tools/)

런타임 재정의:

변수	설명
DOCKER_AGENT_DEFAULT_MODEL	지정이 없을 때 사용할 기본 모델 (예: openai/gpt-5).
DOCKER_AGENT_MODELS_GATEWAY	모델 트래픽을 게이트웨이로 라우팅해요. --models-gateway 플래그와 동일해요.
DOCKER_AGENT_HIDE_TELEMETRY_BANNER	1로 설정하면 첫 실행 텔레메트리 안내를 숨겨요.
DOCKER_AGENT_AUTO_UPDATE	진실값(1, true, yes, on)으로 설정하면 독립형 릴리스 바이너리가 실행 전에 스스로 업데이트돼요. Optional Self-Updates 참조.
DOCKER_AGENT_NO_TOKEN_EXCHANGE	1로 설정하면 Docker Agent가 docker login으로 저장된 액세스 토큰을 Docker 토큰으로 교환하는 것을 멈춰요. Docker authentication 참조.
DOCKER_AGENT_HUB_LOGIN_URL	토큰 교환을 Docker 스테이징 환경으로 가리켜요. HTTPS docker.com URL이 아니면 무시돼요.

참고 — 레거시 CAGENT_* 별칭: 같은 변수를 레거시 CAGENT_ 접두사(예: CAGENT_DEFAULT_MODEL, CAGENT_MODELS_GATEWAY, CAGENT_HIDE_TELEMETRY_BANNER)로도 받아들여요(하위 호환). 새 구성에서는 DOCKER_AGENT_* 형태를 쓰는 게 좋아요.

중요 — 모델 참조는 대소문자를 구분해요: openai/gpt-5는 openai/GPT-5와 같지 않아요.

구성 필드의 변수 확장 (Variable Expansion in Config Fields)

Docker Agent는 여러 구성 필드에서 ${env.VAR} 참조를 확장해요. 이것은 어디서나 동작하는 표준 문법이라 모든 필드에 쓰는 게 좋아요. 이를 뒷받침하는 엔진은 두 개예요: 프롬프트/HTTP 필드를 위한 완전한 JavaScript 평가기(여기서는 기본값, 삼항 연산자, 도구 호출도 사용 가능)와, 파일시스템/env 필드를 위한 더 단순한 경로 확장기(레거시 $VAR / ${VAR} / ~ 셸 형태도 추가로 허용)예요. 어디서든 ${env.VAR}를 쓰면 항상 동작하는데, 한 가지 주의점은 경로 확장기가 더 풍부한 JS 표현식을 평가하지 못한다는 거예요. JS 템플릿 필드에 셸 스타일 $VAR을 쓰면 현재는 조용히 무시되어 리터럴 문자열이 그대로 전달돼요. 추적 이슈: #2615.

JavaScript 템플릿 리터럴 — ${env.VAR}

에이전트 프롬프트나 HTTP 트래픽이 템플릿 처리되는 곳에 사용해요. JS 평가기가 뒷받침하므로 || 기본값, 삼항 연산자, 도구 호출(${tool({...})})도 사용할 수 있어요.

적용 대상:

• agents.<name>.description
• agents.<name>.welcome_message
• agents.<name>.instruction
• agents.<name>.commands.* (문자열 형태와 instruction: 필드)
• toolsets[*].instruction
• toolsets[*].headers 및 toolsets[*].remote.headers (MCP, A2A, OpenAPI, fetch, API)

api toolsets의 경우 api_config.endpoint와 api_config.headers도 JS 확장기를 통해 렌더링돼요(같은 문법 적용).

agents:
  root:
    description: "Assistant for ${env.USER || 'guest'}"
    commands:
      deploy: "Deploy ${env.PROJECT_NAME || 'app'} to ${env.ENV || 'staging'}"
    toolsets:
    - type: openapi
      url: https://api.example.com
      headers:
        Authorization: "Bearer ${env.INTERNAL_TOKEN}"

정의되지 않은 변수는 빈 문자열로 확장돼요.

경로 & env 필드 — ${env.VAR} (표준), $VAR / ${VAR} / ~ (별칭)

파일시스템 경로와 프로세스 환경 값에 사용해요. os.ExpandEnv와 현재 사용자 홈 디렉토리 기준 물결(~) 확장으로 동작해요. 표준 ${env.VAR} 형태도 여기서 허용되므로 모든 필드에서 단일 문법으로 동작하고, 순수 $VAR / ${VAR} 셸 형태는 별칭으로 계속 지원돼요.

적용 대상:

• agents.<name>.toolsets[*].working_dir (MCP, LSP)
• agents.<name>.toolsets[*].path (memory, tasks)
• agents.<name>.toolsets[*].env 값 (MCP, shell, script, LSP)
• agents.<name>.toolsets[*].shell.<tool>.working_dir (script 도구)
• agents.<name>.hooks.*.working_dir
• 그런 문서화된 모든 경로형 필드에서 ~ 접두사도 허용돼요.

agents:
  root:
    toolsets:
    - type: memory
      path: "~/notes/${env.PROJECT}/memory.db"
    - type: mcp
      command: my-server
      working_dir: "${env.HOME}/work"

위의 JS 템플릿 필드와 달리 여기서는 단순 변수 참조만 받아들여요. 더 풍부한 JS 표현식(예: ${env.VAR || 'default'})은 평가되지 않고, 레거시 $VAR / ${VAR} 형태는 하위 호환을 위해 계속 동작해요.

Hook과 script 도구의 env 값은 오직 순수 ${env.VAR} 형태만 확장하며 OS 프로세스 환경 기준으로 해석돼요(dotenv/secret-provider 값은 참조하지 않아요). 순수 $VAR나 ${VAR}는 리터럴 그대로 전달되어, $를 정당하게 포함하는 값(패스워드, 템플릿)이 절대 망가지지 않아요:

agents:
  root:
    hooks:
      session_start:
      - type: command
        command: ./notify.sh
        working_dir: "~/scripts" # ~, $VAR, ${VAR}, ${env.VAR} all work
        env:
          API_TOKEN: "${env.NOTIFY_TOKEN}" # expanded
          PASSWORD: "pa$$word" # kept literal

모델 정의도 같은 규칙을 따라요. models.<name>.model과 models.<name>.base_url 필드는 provider가 구성될 때 확장되며 ${env.VAR}와 ${VAR} 둘 다 받아들여요. 모델 ID나 엔드포인트가 환경에서 주입될 때 유용해요(예: 모델 참조를 변수로 내보내는 Docker Compose / DMR 설정):

models:
  nemotron3:
    provider: dmr
    model: "${env.NEMOTRON3_MODEL}" # resolved from the environment at load time
    base_url: "${DMR_BASE_URL}" # ${VAR} is accepted as well

token_key는 확장되지 않아요. 이미 API 토큰을 담는 환경 변수 이름을 가리키므로 값이 치환 대신 키로 사용돼요. model이나 base_url에서 설정되지 않은 변수는 빈 값으로 접속하는 대신 오류로 보고돼요.

빠른 참조 (Quick reference)

필드	${env.X}	$X / ${X}	~
description, welcome_message	✓	✗	✗
instruction (agent 및 toolset)	✓	✗	✗
commands.*	✓	✗	✗
headers, remote.headers, api_config.headers	✓	✗	✗
models.*.model, models.*.base_url	✓	✓	✗
working_dir, path (toolset, script tool, hook)	✓	✓	✓
env 값 (toolset)	✓	✓	✗
env 값 (hook, script tool)	✓	literal	✗

~ 접두사는 경로형 필드(working_dir, path)에서만 의미가 있어요. hook과 script 도구의 env 값에서 "literal"은 순수 $X / ${X}가 그대로 프로세스에 전달된다는 뜻이에요 — 거기서는 ${env.X}만 치환되므로 $를 포함한 값이 안전하게 유지돼요.

어디서든 ${env.X}를 쓰는 게 좋아요. 순수 $X / ${X}와 ~ 형태는 경로와 env 값 필드에서만 하위 호환을 위해 계속 지원돼요.

검증 (Validation)

Docker Agent는 시작 시 구성이 올바른지 검증해요:

• 로컬 sub_agents는 구성에 정의된 에이전트를 참조해야 해요(외부 OCI 참조(예: myorg/agent:tag)는 레지스트리에서 자동으로 가져오며, 매 실행 레지스트리 조회를 피하려면 @sha256:…로 다이제스트에 고정하세요).
• 명명된 모델 참조는 models 섹션에 존재해야 해요.
• Provider 이름이 유효해야 해요(openai, anthropic, google, dmr 등).
• 필수 환경 변수(API 키)가 설정되어야 해요.
• 도구 전용 필드가 검증돼요(예: path는 memory에만 유효).

JSON Schema

YAML 에디터 자동 완성과 검증을 위해 Docker Agent JSON Schema를 사용해요. YAML 파일 맨 위에 이 줄을 추가하면 돼요:

# yaml-language-server: $schema=https://raw.githubusercontent.com/docker/docker-agent/main/agent-schema.json

구성 버전 관리 (Config Versioning)

Docker Agent 구성은 버전이 관리돼요. 현재 버전은 15예요. 구성 맨 위에 버전을 추가하세요:

version: 15

agents:
  root:
    model: openai/gpt-5
    # ...

더 오래된 구성을 로드하면 Docker Agent가 최신 스키마로 자동 마이그레이션해요. 일관된 동작을 위해 버전을 포함하는 게 좋아요.

더 새로운 스키마 버전이 필요한 구성 키를 쓰면 Docker Agent가 strict-parse 오류와 함께 이런 힌트를 띄워요:

hint: this key is supported by config version 12; update the top-level 'version' field (currently 11)

지시에 따라 version 필드를 올리면 새 키가 활성화돼요.

메타데이터 섹션 (Metadata Section)

OCI 레지스트리를 통한 에이전트 배포를 위한 선택적 메타데이터예요:

metadata:
  author: my-org
  license: Apache-2.0
  description: A helpful coding assistant
  readme: |
    # Displayed in registries
    This agent helps with coding tasks.
  version: "1.0.0"
  tags: [ coding, review ]

필드	설명
author	작성자 또는 조직 이름
license	라이선스 식별자 (예: Apache-2.0, MIT)
description	에이전트 짧은 설명
readme	더 긴 마크다운 설명
version	시맨틱 버전 문자열
tags	분류와 발견을 위한 태그

에이전트를 레지스트리에 게시하는 법은 Agent Distribution 참조.

재사용 가능한 MCP 서버 (mcps:)

최상위 mcps: 섹션은 명명된 MCP 서버 구성을 정의하고, 에이전트가 toolsets: [{type: mcp, ref: <name>}]로 참조할 수 있어요. 이렇게 하면 command/URL/headers를 여러 에이전트에 반복하지 않고 자격 증명을 한 곳에 모을 수 있어요.

mcps:
  github:
    remote:
      url: https://api.githubcopilot.com/mcp
      transport_type: sse
  playwright:
    command: npx
    args: [ "-y", "@modelcontextprotocol/server-playwright" ]

agents:
  root:
    model: openai/gpt-5
    toolsets:
    - type: mcp
      ref: github # reuse the definition above
    - type: mcp
      ref: playwright

mcps 항목은 일반 type: mcp toolset이 받는 모든 필드(command/args/env, url/transport_type/headers/oauth가 있는 remote, tools 필터, instruction, defer, …)를 받아들여요 — type: mcp는 암시적이에요. 모든 옵션은 Tool Config 페이지, 원격 설정은 Remote MCP Servers 가이드를 참조하세요.

재사용 가능한 툴셋 (toolsets:)

최상위 toolsets: 맵은 명명된 툴셋 구성을 정의하고 에이전트가 use_toolsets:로 이름 참조할 수 있어요. 여러 에이전트에서 같은 툴셋 정의를 반복하지 않게 해줘요 — MCP 서버의 mcps:, 재사용 프롬프트 그룹의 commands: / skills:과 같은 패턴이에요.

모든 툴셋 유형이 지원되며 MCP나 RAG 정의를 참조하는 툴셋도 포함돼요. 공유 툴셋은 MCP/RAG 패스보다 먼저 해석되므로 {type: mcp, ref: <name>} 참조를 담을 수 있어요.

toolsets:
  fs: # a named shared toolset
    type: filesystem
  docs:
    type: fetch
    allowed_domains:
    - docker.com

agents:
  root:
    model: openai/gpt-5
    # Pull in shared toolsets by name; inline toolsets come first.
    use_toolsets: [ fs, docs ]
    toolsets:
    - type: think

  reviewer:
    model: openai/gpt-5
    # Reuse the same filesystem toolset without copying its definition.
    use_toolsets: [ fs ]

인라인 툴셋: 에이전트에 직접 나열된 항목은 순서상 우선권이 있고(먼저 오고) 참조된 항목과 함께 항상 포함돼요.

전체 예제는 examples/shared-toolsets.yaml을 참조하세요.

재사용 가능한 명령 & 스킬 (commands: / skills:)

최상위 commands:와 skills: 섹션은 명명된 재사용 그룹을 정의하고 에이전트가 use_commands: / use_skills:로 이름 참조해요. 같은 명령 세트나 스킬 구성을 여러 에이전트에 반복하지 않게 해줘요. 각 그룹 값은 에이전트 자체의 commands / skills 필드와 정확히 같은 형식을 사용해요.

참조된 그룹은 구성 로드 중 에이전트에 병합돼요. 이름 충돌 시 에이전트 자신의 인라인 commands / skills 항목이 우선해요.

commands:
  ci: # a named command group
    deploy: "Deploy the application"
    test: "Run the test suite"
skills:
  base: [ local, git ] # a named skill group

agents:
  root:
    model: openai/gpt-5
    use_commands: [ ci ] # reuse the "ci" command group
    use_skills: [ base ] # reuse the "base" skill group
    commands:
      lint: "Run the linter" # inline command, merged in (wins on conflict)
  reviewer:
    model: openai/gpt-5
    use_commands: [ ci ] # same group, reused without duplication

전체 예제는 examples/shared-commands-skills.yaml을 참조하세요.

사용자 지정 Providers 섹션 (Custom Providers Section)

공유 기본값을 가진 재사용 가능한 provider 구성을 정의해요. Provider는 어떤 provider 유형이든 감싸줄 수 있어요 — OpenAI 호환 엔드포인트뿐만이 아니에요:

providers:
  # OpenAI-compatible custom endpoint
  azure:
    api_type: openai_chatcompletions
    base_url: https://my-resource.openai.azure.com/openai/deployments/gpt-4o
    token_key: AZURE_OPENAI_API_KEY

  # Anthropic with shared model defaults
  team_anthropic:
    provider: anthropic
    token_key: TEAM_ANTHROPIC_KEY
    max_tokens: 32768
    thinking_budget: 16384

models:
  azure_gpt:
    provider: azure
    model: gpt-4o

  claude:
    provider: team_anthropic
    model: claude-sonnet-4-5
    # Inherits max_tokens, thinking_budget from provider

agents:
  root:
    model: claude

필드	설명
provider	기본 provider 유형: openai (기본값), anthropic, google, amazon-bedrock 등
api_type	API 스키마: openai_chatcompletions (기본값) 또는 openai_responses. OpenAI 전용.
base_url	API 엔드포인트의 기본 URL. OpenAI 호환 provider에 필수.
token_key	API 토큰을 담는 환경 변수 이름.
temperature	기본 샘플링 온도.
max_tokens	기본 최대 응답 토큰 수.
thinking_budget	기본 추론 노력/예산.
task_budget	에이전트 작업의 기본 총 토큰 예산 (Anthropic; 현재 Claude Opus 4.7에서 적용).
top_p	기본 top-p 샘플링 파라미터.
frequency_penalty	기본 frequency penalty.
presence_penalty	기본 presence penalty.
parallel_tool_calls	기본적으로 병렬 도구 호출 활성화.
track_usage	기본적으로 토큰 사용 추적.
provider_opts	Provider별 옵션.

자세한 내용은 Provider Definitions를 참조하세요.

재사용 가능한 YAML (Reusable YAML — anchors & aliases)

YAML 앵커(&name), 별칭(*name)과 병합 키(<<)는 YAML 스펙의 일부이고 Docker Agent의 구성 파서가 지원해요. 같은 블록을 여러 에이전트에 복붙하는 대신 값을 한 번 선언하고 파일 안 어디서든 재사용할 수 있어요.

이것은 위의 명명된 재사용 섹션(mcps:, commands: / skills:, providers:)을 보완해요. 그 섹션들이 다루지 않는 것을 공유할 때 앵커를 쓰세요 — 예를 들어 instruction 문자열이나 에이전트 설정 블록.

앵커와 별칭으로 값을 그대로 재사용해요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Coordinator.
    instruction: &house_rules |
      You are part of the Acme engineering team.
      Cite the files you looked at and keep changes minimal.
  reviewer:
    model: anthropic/claude-sonnet-4-5
    description: Reviews code changes.
    instruction: *house_rules # the same instruction, declared once

병합 키(<<)로 블록을 조합하고 개별 필드를 덮어써요:

agents:
  reviewer: &specialist
    model: anthropic/claude-sonnet-4-5
    description: Reviews code changes.
    instruction: |
      You are a meticulous software professional.
    toolsets:
    - type: filesystem
  documenter:
    <<: *specialist # inherit model, instruction, toolsets
    description: Writes documentation. # then override one field

경고 — 앵커가 있을 수 있는 곳: 앵커는 알려진 섹션 안의 실제 값에 위치해야 해요(위처럼 실제 에이전트, 모델, MCP 항목). defaults:나 prompts: 같은 별도 최상위 블록에 앵커를 두면 파서가 알 수 없는 최상위 키를 거부하므로 실패해요.

경고 — 병합 키 덮어쓰기: << 병합이 이미 설정한 키를 덮어쓰는 것은 위처럼 agents: 섹션에서만 동작해요. 다른 모든 섹션(models:, mcps:, providers:, rag:)은 엄격하게 파싱되어 중복 키로 보고해요. 거기서는 새 필드 추가에만 <<를 쓰거나, 항목별 덮어쓰기가 필요하면 위의 명명된 재사용 섹션을 쓰세요.

앵커는 단일 파일 안에서의 정적 재사용을 위한 것이지 동적 값이나 파일 간 조합용이 아니에요. 환경별 설정은 로드 시점에 ${env.VAR}를 치환하는 Variable Expansion in Config Fields를 참조하세요. !include 같은 템플릿 태그는 처리되지 않아요. 태그는 무시되고 인자는 평문 문자열로 유지되어 다른 파일은 로드되지 않아요. 순환 별칭은 감지되지 않으므로 참조를 비순환으로 유지하세요.

전체 예제는 examples/yaml-anchors.yaml을 참조하세요.

더 알아보기 (Learn more)

• HCL Configuration
• Agent Config
• Managing Secrets