도커 에이전트, YAML로 만들고 OCI로 공유한다

도커(Docker)가 AI 에이전트의 설정부터 실행, 공유까지 한 흐름으로 다루는 ‘도커 에이전트(Docker Agent)’를 공개했다. 사용자는 YAML 파일에 모델과 지시문, 사용할 도구를 적고 docker agent 명령으로 에이전트를 실행할 수 있다. 전문 에이전트끼리 작업을 나누거나 완성한 에이전트를 OCI 레지스트리에 올리는 기능도 갖췄다. 에이전트 실행 도구가 빠르게 늘어나는 지금, 도커의 익숙한 명령어와 배포 방식이 어떤 편의를 주고 어떤 운영 문제를 남기는지 살펴볼 만하다.

핵심요약

  • 도커 에이전트는 모델·지시문·도구를 YAML 설정 파일에 정의하게 해, 에이전트의 실행 구성을 버전 관리하고 공유할 수 있도록 한다.
  • 전문 에이전트 간 작업 위임과 MCP 도구 연결을 지원해, 여러 에이전트가 협업하는 작업 흐름을 구성할 수 있다.
  • 오픈AI와 앤트로픽 등 여러 모델 제공자와 도커 모델 러너를 지원하며, 검색 자료를 답변에 활용하는 RAG도 구성할 수 있다.
  • 만든 에이전트를 OCI 레지스트리에 올리고 다시 불러 실행할 수 있어, 로컬 설정 파일에서 배포까지 이어지는 경로를 제공한다.
  • 토론에서는 장기 작업의 일관성, 실행 환경의 격리, 다른 도구와의 차이, 데이터 처리 방식이 주요 쟁점으로 떠올랐다.

YAML 파일에 적는 모델과 행동 지침

도커 에이전트는 에이전트를 만들고 실행하는 도커 명령줄 도구의 플러그인이다. 도커 엔지니어링 팀은 별도의 코드를 작성하지 않아도 YAML(들여쓰기로 항목의 구조를 표현하는 설정 형식) 파일로 에이전트를 정의할 수 있다고 소개한다. 파일에는 사용할 모델과 에이전트의 설명, 응답 방식에 관한 지시문, 연결할 도구가 들어간다. 설치한 뒤에는 docker agent 명령으로 이 설정을 불러와 실행한다.

저장소에 나온 기본 예시는 root라는 에이전트에 오픈AI(OpenAI)의 gpt-5-mini 모델을 지정한다. 지시문에는 사용자의 여러 작업을 돕되 정확하고 간결하게 답하도록 적어 두고, 도구 목록에는 덕덕고(DuckDuckGo)를 연결한다. 사용자는 이 내용을 agent.yaml에 저장한 뒤 docker agent run agent.yaml을 실행하면 된다. 어떤 모델에 어떤 역할을 맡기고 무엇에 접근하게 할지가 설정 파일에 드러나는 방식이다.

여기서 ‘코드가 필요 없다’는 말은 에이전트의 동작을 프로그램으로 직접 구현하지 않아도 된다는 뜻에 가깝다. 원하는 행동을 지시문으로 설명하고, 필요한 도구와 모델을 설정에서 골라야 하는 일은 남는다. 대신 실행 구성이 파일로 남으므로 내용을 고쳐 가며 버전을 관리하거나 다른 사람에게 전달할 수 있다. 에이전트를 일회성 대화가 아니라 다시 실행할 수 있는 설정으로 다루는 출발점이다.

전문 에이전트가 일을 나누는 구조

도커가 내세운 기능은 하나의 에이전트에 질문하고 답을 받는 데서 그치지 않는다. 전문화된 에이전트들을 팀으로 묶고, 이들이 작업을 자동으로 위임하도록 구성하는 다중 에이전트 구조를 지원한다. 복잡한 문제를 한 역할에 모두 맡기기보다 서로 다른 역할에 나누어 처리하도록 설계하는 방식이다. 모델을 무엇으로 정할지와 함께, 일을 어떤 에이전트에 맡길지도 설정의 일부가 된다.

에이전트가 사용할 도구의 범위도 넓다. 도커 에이전트는 자체 내장 도구와 MCP(에이전트가 외부 도구와 연결하는 방식) 서버를 지원한다. MCP 서버는 로컬에서 실행하거나 원격에 두거나 도커 기반으로 연결할 수 있다. 예시 설정의 덕덕고 도구처럼, 에이전트가 답변을 만들 때 외부 기능을 이용하도록 지정하는 구조다.

도커는 ‘생각하기’, 할 일 목록, 기억 도구도 주요 기능으로 열거한다. 작업을 단계로 나누거나 진행 상황을 다루는 기능을 에이전트 구성에 넣을 수 있다는 설명이다. 다만 도구의 종류가 늘면 각 에이전트에 무엇을 허용하고 어느 단계에서 작업을 넘길지 정하는 일도 중요해진다. 다중 에이전트라는 이름보다 실제 작업 흐름을 어떻게 설계하느냐가 사용 경험을 좌우하는 부분이다.

클라우드 모델과 로컬 모델 사이

도커 에이전트는 특정 AI 제공자의 모델만 쓰도록 묶어 두지 않았다. 지원 대상으로 오픈AI, 앤트로픽(Anthropic), 구글의 제미나이(Gemini), AWS 베드록(Bedrock), 미스트랄(Mistral), xAI 등을 열거한다. 사용자는 설정 파일에서 에이전트에 맞는 모델을 지정하고 해당 서비스의 API 키를 준비할 수 있다. 저장소는 적어도 하나의 API 키를 설정하는 방법을 시작 절차로 안내한다.

클라우드 API를 쓰지 않는 경로도 마련돼 있다. 도커 모델 러너(Docker Model Runner)를 이용하면 로컬 모델로 도커 에이전트를 실행할 수 있다. 문서는 모델 설정 안내에서 클라우드 API 키를 사용하는 방법과 로컬 모델을 사용하는 방법을 각각 다룬다. 따라서 설치 명령을 실행하는 것만으로 준비가 끝나는 것은 아니며, 어떤 모델을 어디서 돌릴지 먼저 정해야 한다.

모델 선택과 에이전트의 역할 정의는 분리된 문제다. 같은 설정 방식 안에서도 어떤 모델을 쓰는지, 어떤 지시문을 주는지, 무엇을 도구로 붙이는지에 따라 에이전트의 구성이 달라진다. 여러 제공자를 지원한다는 점은 하나의 실행 도구에서 모델 선택지를 바꿔 볼 수 있게 한다. 반면 모델을 바꾸더라도 도구 연결과 작업 위임 방식까지 자동으로 정해지는 것은 아니다.

검색 자료를 답변에 연결하는 방법

도커 에이전트는 RAG(찾아낸 자료를 답변 생성에 활용하는 방식)도 지원한다. 에이전트가 모델의 응답이나 기억 도구에만 기대지 않고, 검색한 자료를 바탕으로 답하도록 구성할 수 있는 기능이다. 도커는 검색 방식을 갈아 끼울 수 있다고 설명하며 여러 선택지를 제시한다. 필요한 자료를 어떤 방식으로 찾고 정렬할지까지 설정의 범위에 들어온다.

선택지에는 단어가 얼마나 맞아떨어지는지 활용하는 BM25와 내용을 수치로 표현해 찾는 임베딩 검색이 포함된다. 두 방식을 함께 쓰는 하이브리드 검색과, 찾은 결과의 순서를 다시 매기는 리랭킹도 지원 대상으로 적었다. 이는 RAG가 단순히 검색 도구 하나를 켜는 기능이 아니라 검색과 결과 정리 단계를 조합하는 구성임을 보여 준다. 도구 연결과 RAG를 함께 보면 도커 에이전트는 모델이 답을 생성하기 전 어떤 정보를 가져올지도 다루려 한다.

OCI 레지스트리로 옮기는 에이전트

로컬에서 만든 설정을 다른 곳으로 전달하는 경로도 제공한다. 도커는 에이전트를 OCI(컨테이너 이미지 등의 배포에 쓰이는 개방형 규격) 레지스트리에 올리고, 다시 가져와 실행할 수 있다고 설명한다. 파일을 따로 건네는 방식뿐 아니라 등록된 에이전트를 이름으로 불러오는 방식이다. 만들기와 실행하기 사이에 패키징과 공유 단계를 놓은 셈이다.

저장소의 실행 예시에는 docker agent run myorg/agent:tag가 나온다. 사용자가 로컬의 agent.yaml을 지정하는 대신 레지스트리에 있는 에이전트를 이름과 태그로 가리키는 경우다. 설정 파일은 모델과 지시문, 도구 구성을 정의하고, 레지스트리는 그 구성을 배포해 다시 실행하는 통로가 된다. 도커가 익숙하게 다뤄 온 명령줄 호출과 레지스트리 배포 개념을 에이전트에도 적용한 부분이다.

이 흐름의 초점은 에이전트를 한 번 만든 뒤 끝내지 않는 데 있다. 설정 파일을 수정해 실행 방식을 바꾸고, 공유할 구성을 레지스트리에 올린 뒤, 필요한 곳에서 불러올 수 있다. 도커가 내세우는 ‘만들고, 실행하고, 공유한다’는 설명이 각각 YAML, CLI, OCI 레지스트리에 대응한다. 다중 에이전트와 도구 연결까지 포함한 구성을 어떻게 관리할지 고민하는 사용자에게 특히 눈에 띄는 경로다.

설치 경로와 네 가지 시작 명령

도커 데스크톱(Docker Desktop) 4.63 이상에는 도커 에이전트 CLI 플러그인이 미리 설치돼 있다. 이 환경에서는 별도 플러그인 설치 없이 docker agent 명령으로 시작할 수 있다. 다른 경로로는 홈브루(Homebrew)의 brew install docker-agent와 GitHub 바이너리 릴리스가 안내돼 있다. 바이너리는 docker-agent로 직접 실행하거나 도커 CLI 플러그인 경로에 연결해 사용할 수 있다.

설치를 마쳤다면 다음 단계는 모델 준비다. 클라우드 모델을 선택한 경우에는 해당 서비스의 API 키를 설정하고, 로컬 모델을 선택했다면 도커 모델 러너를 사용한다. 저장소는 두 경로의 설정 절차를 별도로 안내한다. 에이전트 설정 파일을 작성하기 전에도 모델을 어디서 이용할지 결정해야 실행까지 이어질 수 있다.

시작 명령은 무엇을 실행할지에 따라 갈린다. docker agent run은 기본 에이전트를 실행하고, docker agent new는 새 에이전트 설정을 대화식으로 만든다. 직접 작성한 파일에는 docker agent run agent.yaml을, 레지스트리의 에이전트에는 이름과 태그를 지정한 run 명령을 쓴다. 저장소의 examples/ 디렉터리에는 다른 구성을 살펴볼 수 있는 예시도 마련돼 있다.

문서와 자체 개발에 쓰인 에이전트

도커 에이전트 문서는 설치와 모델 설정, 빠른 시작 안내에서 출발한다. 이어 에이전트와 모델, 도구, 다중 에이전트 구성, 설정 항목을 다룬다. 터미널 사용자 인터페이스인 TUI와 CLI, MCP 모드, RAG, 모델 제공자에 관한 문서도 따로 안내한다. 하나의 예시 파일을 실행하는 방법뿐 아니라 구성을 넓혀 가는 경로를 문서로 나눠 둔 것이다.

도커 엔지니어링 팀은 도커 에이전트를 만드는 데도 이 도구를 쓴다고 밝혔다. 저장소에는 docker agent run ./golang_developer.yaml이라는 실행 예시가 실려 있다. 개발 작업에 맞춰 정의한 에이전트를 같은 명령 체계로 호출한다는 사례다. 저장소는 기여 안내와 보안 정책, 커뮤니티 채널도 연결해 두고 있다.

운영할 때 확인할 정보도 저장소에 명시돼 있다. 도커는 도구 개선을 위해 익명 사용 데이터를 수집한다고 밝히고 텔레메트리(도구 사용 정보를 수집하는 기능) 안내를 제공한다. 에이전트 설정에 모델과 외부 도구가 함께 들어가는 만큼, 사용자는 어떤 연결을 허용할지뿐 아니라 사용 데이터가 어떻게 다뤄지는지도 살펴볼 필요가 있다. 토론에서는 기능 목록보다 장기 작업의 기록과 실행 환경의 격리를 먼저 따지는 의견이 이어졌다.

커뮤니티 의견

한 사용자는 에이전트끼리 일을 주고받게 하는 것보다 긴 작업 동안 목표에서 벗어나지 않도록 유지하는 일이 더 어렵다고 했다. 자신이 만든 별도 도구에서는 에이전트가 작업을 기록하고, 개발자가 정한 원칙과 확인 가능한 명세를 따르도록 한다고 설명했다. 답글에서는 여러 에이전트를 관리하다 보면 결국 사람의 업무 관리 도구와 닮은 체계를 만들게 된다는 반응이 나왔다.

‘코드 없이’ 만들 수 있다는 표현에 의문을 제기하는 의견도 있었다. 에이전트가 이미 코드를 빠르게 생성하는데 YAML 설정이 얼마나 큰 이점이냐는 질문이다. 답글에서는 코드를 추가하면 그만큼 검토할 대상도 생긴다는 반론이 나왔다. 비개발자에게는 YAML을 작성하는 일 자체가 프로그래밍처럼 보일 것이라는 지적도 이어졌다.

또 다른 사용자는 에이전트 실행 도구가 과거 자바스크립트 프레임워크처럼 계속 늘어난다고 평했다. 고(Go)로 작성된 새 오픈소스 도구는 반기지만, 누구나 독자적인 실행 틀을 만드는 듯하다는 이야기다. 답글에서는 고 기반 도구가 사용자에게 확장 기능을 제공하기는 까다롭다는 경험담이 나왔다. 타입스크립트 방식은 확장이 수월한 대신 플러그인 보안을 걱정해야 한다는 비교도 있었다.

보안 문서를 찾던 사용자는 도커 에이전트의 샌드박스 설정 페이지를 공유했다. 이어진 답글은 도커 에이전트를 실행 틀로, 선택 가능한 샌드박스 모드를 가상머신에서 실행하는 방식으로 구분했다. 다른 답글에서는 샌드박스 문서가 공격 경로까지 충분히 설명하는지 물었다. 이 대화는 에이전트를 실행할 수 있느냐뿐 아니라 어떤 환경에 격리해 실행하느냐를 쟁점으로 삼았다.

비슷한 프로젝트가 많아 각각 어떤 작업에 적합한지 구별하기 어렵다는 사용자도 있었다. 별도의 의견에서는 많은 에이전트를 직접 호출하며 관리하기보다 중앙의 조정 에이전트 하나가 기능에 따라 일을 보내는 방식을 소개했다. 동시에 움직이는 에이전트가 많아지면 진행 상황을 따라가기 피곤하다는 이유였다. 다중 에이전트 기능을 비교할 때 연결 가능한 에이전트 수만큼 작업 흐름을 관리하는 방식도 중요하다는 관점이다.

연구에 쓰일 가능성을 본 사용자는 에이전트 관련 머신러닝 논문의 실험을 다시 돌려 결과를 확인하는 데 이 도구가 도움이 될 수 있다고 했다. 다른 사람이 결과를 반복하고, LLM의 변동성이 결과에 대한 과도한 확신으로 이어지지 않는지 살피고 싶다는 것이다. 다만 자신은 현재 uv만으로도 격리되고 반복 가능한 환경을 만들 수 있다고 설명했다. 윈도나 맥 PC에서 작은 GPU 실험을 먼저 실행하기에도 기존 방식이 편하다고 덧붙였다.

실사용 경험은 엇갈렸다. 한 사용자는 몇 주 전 도커 에이전트를 써보려 했지만 자신이 사용한 실행 도구 중 가장 불안정했다고 평가했다. 다른 사용자는 과거 LLM이 제안한 도커 설정을 복사해 실행해도 잘 작동하지 않았던 경험을 들며, 도커에 특화된 에이전트와 모델의 조합을 기대했다. 답글에서는 도커 관련 전문 에이전트와 스킬 배포 작업이 언급됐다.

마지막으로 모델 성능이 비슷한 방향으로 발전할수록 여러 에이전트 실행 도구가 각각의 존재 이유를 보여 줘야 한다는 평이 나왔다. 기존 실행·격리 서비스로도 비슷한 일을 할 수 있는데 별도 추상화가 왜 필요한지 묻는 사용자도 있었다. 또 다른 사용자는 입력과 출력 등 데이터가 어떻게 처리되는지 약관을 확인하라고 권했다. 기능의 폭만이 아니라 기존 도구 대비 편의와 운영 조건을 함께 따져야 한다는 시선이다.

핵심통찰

도커 에이전트가 겨냥한 변화는 모델의 답변 능력보다 에이전트를 관리하는 방식에 있다. YAML로 역할과 도구를 정하고, 도커 CLI로 실행하며, OCI 레지스트리로 공유하는 경로는 에이전트를 다시 쓰고 배포할 수 있는 구성물로 만든다. 그러나 연결과 배포가 쉬워질수록 긴 작업이 목표를 유지하는지, 어떤 환경에서 실행되는지 확인하는 일도 중요해진다. 앞으로는 설치 편의뿐 아니라 작업 기록·검증, 격리 설정, 데이터 처리 방식을 얼마나 분명하게 다루는지가 이 도구의 가치를 가를 것이다.


원본: GitHub - docker/docker-agent: AI Agent Builder and Runtime by Docker Engineering

토론: Hacker News