퀵스타트

퀵스타트 (Quick Start)

5분 안에 Docker Agent로 시작해보세요. 자신에게 가장 잘 맞는 경로를 고르면 돼요.

출처: 문서

본문

옵션 A: 기본 에이전트 실행 (Option A: Run the Default Agent)

Docker Agent를 시도하는 가장 빠른 방법 — 구성 파일이 필요 없어요:

# Launch the default agent with the interactive TUI
$ docker agent run

이것은 합리적인 기본값을 가진 일반 목적 어시스턴트를 시작해요. 그냥 대화를 시작하면 돼요.

Note 모델이 필요해요: 클라우드 제공자 API 키, 또는 Docker Model Runner를 통해 풀한 로컬 모델. Set Up a Model이 두 경로를 모두 안내해요.

옵션 B: 레지스트리에서 에이전트 실행 (Option B: Run an Agent from a Registry)

어떤 OCI 호환 레지스트리를 통해 공유된 에이전트를 실행해요 — 로컬 YAML이 필요 없어요:

$ docker agent run myorg/agent:tag

옵션 C: 구성을 대화형으로 생성 (Option C: Generate a Config Interactively)

docker agent new 명령으로 프롬프트를 통해 구성 파일을 스캐폴딩해요:

# Interactive wizard
$ docker agent new

# Or specify options directly
$ docker agent new --model openai/gpt-5

# Override iteration limits
$ docker agent new --model dmr/ai/gemma3-qat:12B --max-iterations 15

이것은 현재 디렉터리에 agent.yaml 을 생성해요. 그런 다음 실행해요:

$ docker agent run agent.yaml

옵션 D: 자신만의 구성 작성 (Option D: Write Your Own Config)

완전한 제어를 위해 agent.yaml 을 손으로 만들어요. 여기 최소한의 예제가 있어요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A helpful coding assistant
    instruction: |
      You are an expert software developer. Help users write
      clean, efficient code. Explain your reasoning.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think

이것은 에이전트에 다음을 줘요:

기본 모델로 Claude Sonnet 4.5
파일을 읽고 쓸 수 있는 파일시스템 접근
명령을 실행할 셸 접근
단계별 추론을 위한 think 도구

이 구성은 ANTHROPIC_API_KEY 설정이 필요해요. 어디에 둘지는 Set Up a Model 참고, 또는 키가 필요 없는 로컬 dmr/... 모델을 사용하세요.

# Launch the interactive terminal UI
$ docker agent run agent.yaml

Tip HCL을 선호하나요? 라벨 블록과 heredoc을 사용해 같은 구성을 agent.hcl 로 쓸 수 있어요. HCL Configuration 참고.

시험해 보기 (Try It Out)

에이전트가 실행되면 다음을 시도해 보도록 요청해보세요:

"List the files in the current directory"
"Create a Python script that fetches weather data"
"Explain what the code in main.go does"

Tip 모든 도구 호출을 자동 승인하려면 --yolo 를 추가하세요: docker agent run agent.yaml --yolo

대화형 투어 (Take the Interactive Tour)

행동으로 배우는 걸 선호하나요? 실행해보세요:

$ docker agent getting-started

이것은 채팅 UI 안에서 짧고 스크립트된 투어를 시작해요: 메시지 보내기, 도구 호출 승인, 명령 팔레트, 슬래시 명령. Esc 로 언제든 건너뛸 수 있고, 나중에 같은 명령이나 /getting-started 슬래시 명령으로 다시 재생할 수 있어요.

비대화형 모드 (Non-Interactive Mode)

일회성 작업에는 docker agent run --exec 을 사용해요:

# Ask a single question
$ docker agent run --exec agent.yaml "Create a Dockerfile for a Node.js app"

# Pipe input
$ cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?"

더 많은 힘 더하기 (Add More Power)

에이전트에 영구 메모리와 웹 검색을 줘요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Research assistant with memory
    instruction: |
      You are a research assistant. Search the web for information,
      remember important findings, and provide thorough analysis.
    toolsets:
      - type: think
      - type: memory
        path: ./research.db
      - type: mcp
        ref: docker:duckduckgo

Note Docker MCP 도구 (Docker MCP Tools) ref: docker:duckduckgo 구문은 DuckDuckGo MCP 서버를 Docker 컨테이너에서 실행해요. 이것이 MCP 도구를 쓰는 권장 방법이에요 — 안전하고, 격리되고, 구성하기 쉬워요. Docker Desktop이 필요해요.

다음은 무엇인가? (What's Next?)

Understand Agents — 에이전트가 어떻게 동작하고 무엇을 구성할 수 있는지 배우기.
Multi-Agent Systems — 협력하는 에이전트 팀 구축.
Configuration Reference — 모든 YAML 및 HCL 옵션의 전체 참조.
Troubleshooting — 뭔가 안 되나요? 디버그 팁과 일반적인 해결책.