Docker Agent

Docker Agent

Docker Agent는 특화된 AI 에이전트 팀을 구축하기 위한 오픈소스 프레임워크예요. 하나의 일반 범용 모델에 프롬프트를 주는 대신, 특정 역할과 지침을 가진 에이전트를 정의해서 협력하며 문제를 해결하게 만들 수 있어요. 이런 에이전트 팀을 터미널에서 어떤 LLM 제공자를 사용해서든 실행할 수 있답니다.

출처: 문서

본문

Note Docker Agent는 커스텀 에이전트 팀을 구축하고 실행하기 위한 프레임워크예요. Docker의 내장 AI 어시스턴트는 Gordon (docker ai) 문서를 참고하세요.

에이전트 팀이 필요한 이유 (Why agent teams)

하나의 에이전트가 복잡한 작업을 처리하면 계속해서 컨텍스트를 전환해야 해요. 대신 작업을 각자 잘하는 것만 처리하는 초점화된 에이전트들로 나누면 돼요. Docker Agent가 이런 조율(coordination)을 관리해줘요.

여기 문제를 디버깅하는 두 에이전트로 구성된 팀이 있어요:

agents:
  root:
    model: openai/gpt-5-mini # Change to the model that you want to use
    description: Bug investigator
    instruction: |
      Analyze error messages, stack traces, and code to find bug root causes.
      Explain what's wrong and why it's happening.
      Delegate fix implementation to the fixer agent.
    sub_agents: [fixer]
    toolsets:
      - type: filesystem
      - type: mcp
        ref: docker:duckduckgo

  fixer:
    model: anthropic/claude-sonnet-4-5 # Change to the model that you want to use
    description: Fix implementer
    instruction: |
      Write fixes for bugs diagnosed by the investigator.
      Make minimal, targeted changes and add tests to prevent regression.
    toolsets:
      - type: filesystem
      - type: shell

루트 에이전트는 문제를 조사하고 설명해요. 문제를 이해하면 구현을 위해 fixer 에게 넘겨줘요. 각 에이전트는 자기 전문 분야에 집중하죠.

설치 (Installation)

Docker Agent는 Docker Desktop 4.63 이상에 포함되어 있어요. Docker Desktop 4.49부터 4.62까지는 이 기능을 cagent 라고 불렀어요.

Docker Engine 사용자나 커스텀 설치의 경우:

  • Homebrew: brew install docker-agent
  • Winget: winget install Docker.Agent
  • 사전 빌드 바이너리: GitHub releases
  • 소스에서: Docker Agent repository 참고

docker-agent 바이너리는 ~/.docker/cli-plugins 에 복사한 뒤 docker agent 명령으로 사용할 수 있어요. 또는 독립 실행 바이너리로 사용할 수도 있어요.

시작하기 (Get started)

버그 분석 팀을 시험해봐요:

  • 사용하려는 모델 제공자의 API 키를 설정해요:
$ export ANTHROPIC_API_KEY=<your_key> # For Claude models
$ export OPENAI_API_KEY=<your_key> # For OpenAI models
$ export GOOGLE_API_KEY=<your_key> # For Gemini models
  • 예제 구성을 debugger.yaml 로 저장해요.
  • 에이전트 팀을 실행해요:
$ docker agent run debugger.yaml

버그를 설명하거나 에러 메시지를 붙여넣을 수 있는 프롬프트가 나타나요. 조사자(investigator)가 문제를 분석한 뒤 구현을 위해 fixer 에게 넘겨줘요.

동작 원리 (How it works)

당신은 루트 에이전트(root agent)와 상호작용하고, 루트 에이전트는 당신이 정의한 하위 에이전트(sub-agents)에게 작업을 위임할 수 있어요. 각 에이전트는:

  • 자신만의 모델과 파라미터를 사용
  • 자신만의 컨텍스트를 가짐 (에이전트끼리 지식을 공유하지 않음)
  • todo 리스트, 메모리, 작업 위임 같은 내장 도구에 접근
  • MCP 서버를 통해 외부 도구를 사용

루트 에이전트는 sub_agents 아래 나열된 에이전트들에게 작업을 위임해요. 하위 에이전트는 더 깊은 계층 구조를 위해 자신의 하위 에이전트를 가질 수도 있어요.

구성 옵션 (Configuration options)

에이전트 구성은 YAML 파일이에요. 기본 구조는 다음과 같아요:

agents:
  root:
    model: claude-sonnet-4-0
    description: Brief role summary
    instruction: |
      Detailed instructions for this agent...
    sub_agents: [helper]

  helper:
    model: gpt-5-mini
    description: Specialist agent role
    instruction: |
      Instructions for the helper agent...

모델 설정(컨텍스트 제한 등), 도구(MCP 서버 포함) 등도 구성할 수 있어요. 전체 상세는 configuration reference 문서를 참고하세요.

에이전트 팀 공유하기 (Share agent teams)

에이전트 구성은 OCI 아티팩트로 패키징돼요. 컨테이너 이미지처럼 push하고 pull할 수 있어요:

$ docker agent share push ./debugger.yaml myusername/debugger
$ docker agent share pull myusername/debugger

Docker Hub나 OCI 호환 레지스트리를 사용해요. push하면 repository가 아직 없을 때 자동으로 생성돼요.

다음 단계 (What's next)

  • 퀵스타트를 따라 첫 에이전트를 만들어보기
  • 효과적인 에이전트를 만들기 위한 모범 사례 배우기
  • Docker Agent를 편집기와 통합하거나, MCP 클라이언트에서 에이전트를 도구로 사용하기
  • Docker Agent repository에서 예제 에이전트 구성 살펴보기
  • Docker MCP Gateway를 통해 에이전트를 외부 도구에 연결하기
  • 전체 구성 참조(configuration reference) 읽기

더 알아보기 (Learn more)