Docker Agent: YAML로 정의하는 AI 에이전트 빌더·런타임

Who Should Read

에이전트를 코드 없이 선언형 설정으로 만들고 OCI 레지스트리로 공유하고 싶은 백엔드·DevOps 개발자

Core Mechanics

• YAML 한 파일로 에이전트 정의
  • agents 아래에 model, description, instruction, toolsets를 적는다.
  • docker agent run agent.yaml로 실행한다.
• docker CLI 플러그인으로 동작
  • Docker Desktop 4.63+에는 미리 설치되어 있다.
  • Homebrew(brew install docker-agent)나 GitHub Releases 바이너리로도 설치한다.
• 멀티 에이전트와 MCP 도구 지원
  • 전문 에이전트 팀이 작업을 자동으로 위임한다.
  • 내장 도구와 MCP(에이전트가 외부 도구를 쓰는 표준 규약) 서버(로컬·원격·Docker 기반)를 쓸 수 있다.
• 모델 제공자에 종속되지 않음
  • OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI, Docker Model Runner 등을 지원한다.
  • API 키 하나 또는 Docker Model Runner 로컬 모델로 시작한다.
• RAG와 추론 도구 내장
  • think, todo, memory 도구가 기본 제공된다.
  • RAG는 BM25, 임베딩, 하이브리드 검색, 리랭킹을 끼워 쓰는 구조다.

Community Reactions

• 에이전트 하네스가 너무 많다는 의견
  • 예전 JS 프레임워크처럼 다들 하나씩 만든다는 반응이 있었다.
  • 좋은 에이전트 없이 하네스부터 내놓는 건 순서가 뒤집혔다는 의견도 있었다.
• 써 봤더니 불안정했다는 경험
  • 몇 주 전 열심히 써 봤는데 써 본 하네스 중 가장 깨지기 쉬웠다는 경험이 있었다.
  • 더 성숙해지면 다시 보겠다고 했다.
• 샌드박스·보안 정보가 부족하다는 지적
  • Docker 도구인데 샌드박싱 이야기가 없다는 지적이 있었다.
  • 명령·자격증명 ACL처럼 에이전트 권한 경계를 실행 전에 정하고 싶다는 의견도 있었다.
• 운영 방식에 대한 의견
  • 에이전트가 많아지면 관리가 힘들어서 능력별로 라우팅하는 단일 오케스트레이터가 낫다는 경험이 있었다.
  • 데이터 보존 약관을 먼저 읽어야 한다는 경고도 있었다.

How to Apply

• 로컬에서 최소 에이전트 YAML 돌려보기
  • 오늘 brew install docker-agent로 설치하고 API 키를 환경변수로 설정한다.
  • 아래 YAML을 agent.yaml로 저장해 docker agent run agent.yaml을 실행한다.
• 팀 에이전트를 OCI 레지스트리로 배포하기
  • 반복 쓰는 에이전트 YAML을 사내 OCI 레지스트리에 push한다.
  • 팀원은 docker agent run으로 같은 에이전트를 받아 쓰게 한다.
• 도입 전 보안·약관 체크리스트 만들기
  • 샌드박스 문서와 Telemetry 문서를 읽고 데이터 보존 범위를 확인한다.
  • 쓰기 권한이 있는 도구는 확인 후에 연결한다.

Try It

# 터미널에 붙여넣기 (원문 README의 예제 기반, OPENAI_API_KEY 필요)

brew install docker-agent
export OPENAI_API_KEY=sk-...

cat > agent.yaml <<'EOF'
agents:
  root:
    model: openai/gpt-5-mini
    description: A helpful AI assistant
    instruction: |
      You are a knowledgeable assistant that helps users with various tasks.
      Be helpful, accurate, and concise in your responses.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
EOF

docker-agent run agent.yaml

# 이어서 해 볼 것: docker agent new로 대화형 생성, docker agent run myorg/agent:tag로 레지스트리 에이전트 실행

Terminology

관련 논문

• 같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나

  긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복

• 가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격

  가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)

• Harness Engineering 101: LLM은 뇌, harness는 몸

  에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

• Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크

  모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다

• 해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유

  경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다

• tmux와 Claude Code: 세션, send-keys, 그리고 한계선

  tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

• Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트

  잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓

Related Resources

• https://github.com/docker/docker-agent
• https://docker.github.io/docker-agent/
• https://docker.github.io/docker-agent/configuration/sandbox/
• https://github.com/pullboard-dev/pullboard
• https://github.com/oguzbilgic/kern-ai
• https://kagent.dev/
• https://github.com/kubernetes-sigs/agent-sandbox