GPT-5, Claude Sonnet, Gemini. 모델은 계속 발전하지만, 복잡한 작업은 단일 모델로 해결되지 않습니다. 정보를 수집하는 리서처, 내용을 요약하는 작가, 전체를 조율하는 기획자처럼 각자 역할을 가진 에이전트들이 협업해야 진짜 일이 됩니다. 문제는 이런 멀티 에이전트 시스템을 만드는 게 지금까지는 너무 복잡했다는 점입니다. Docker가 오픈소스로 공개한 cagent는 이 문제를 YAML 파일 하나로 해결합니다.
핵심 포인트:
- YAML로 에이전트 팀 정의: 복잡한 코드 없이 각 에이전트의 역할, 사용 모델, 도구, 하위 에이전트까지 선언적으로 설정. 5분이면 3개 에이전트로 구성된 팀 완성
- Docker Hub로 에이전트 공유: 컨테이너처럼 에이전트를 패키징하고 버전 관리.
cagent push로 올리고cagent run으로 실행하면 팀원 모두 동일한 설정 사용 - MCP로 도구 통합과 다중 AI 제공자 지원: DuckDuckGo 검색부터 GitHub, 파일시스템까지 MCP 프로토콜로 즉시 연결. OpenAI, Anthropic, Gemini, 로컬 모델을 자유롭게 조합 가능
왜 멀티 에이전트 시스템인가
단일 모델은 범용적이지만 복잡한 작업에서는 한계가 있습니다. PR 분석부터 이슈 분류, 코멘트 작성까지 하나의 모델에 맡기면 맥락을 잃기 쉽습니다. 각자 역할을 가진 에이전트 팀이 협업하면 훨씬 효과적이죠. 문제는 지금까지 이런 시스템을 만드는 게 너무 복잡했다는 점입니다.
Docker의 cagent는 이 문제를 해결합니다. docker-compose가 컨테이너 오케스트레이션을 YAML로 단순화한 것처럼, cagent는 에이전트 오케스트레이션을 같은 방식으로 접근합니다. 각 에이전트의 역할과 도구, 위임 관계를 YAML에 정의하면 cagent가 실행을 관리합니다. 에이전트를 컨테이너처럼 패키징하고, Docker Hub로 공유하고, 어디서나 동일하게 실행할 수 있습니다.
docker-compose에 익숙하다면 cagent를 이해하기 쉽습니다. 핵심 개념이 거의 일대일로 대응됩니다.
| docker-compose | cagent | 설명 |
|---|---|---|
services | agents | 실행할 개별 단위 정의 |
image | model | 사용할 기반 (컨테이너 이미지 vs AI 모델) |
depends_on | sub_agents | 의존성과 실행 순서 관리 |
volumes | toolsets | 외부 리소스 접근 권한 |
networks | context flow | 구성 요소 간 통신 방식 |
docker-compose up | cagent run | 전체 시스템 실행 |
docker push | cagent push | Hub에 배포 |
docker-compose로 마이크로서비스를 오케스트레이션하듯, cagent로 AI 에이전트를 오케스트레이션합니다.
5분 만에 멀티 에이전트 시스템 만들기
실제로 얼마나 간단한지 직접 확인해보겠습니다.
1단계: 에이전트 팀 정의하기
team.yaml 파일에 세 개의 에이전트를 정의합니다.
version: "2"
agents:
root:
model: anthropic/claude-sonnet-4-0
instruction: |
사용자 요청을 분석하고 작업을 나눕니다.
리서처에게 정보 수집을 요청하고, 결과를 작가에게 전달합니다.
sub_agents: ["researcher", "writer"]
researcher:
model: openai/gpt-5-mini
description: 정보를 조사하고 수집하는 에이전트
instruction: 출처를 찾아 링크와 함께 핵심 내용을 정리합니다.
toolsets:
- type: mcp
ref: docker:duckduckgo
writer:
model: dmr/ai/qwen3
description: 내용을 요약하는 에이전트
instruction: 리서처가 수집한 내용을 명확하고 간결하게 요약합니다.이 YAML 파일은 세 에이전트의 역할을 명확히 정의합니다. root는 조정자로 Claude Sonnet 4.0을 사용하고, researcher는 GPT-5 mini로 DuckDuckGo 검색 도구를 활용하며, writer는 로컬 Qwen3 모델로 요약을 작성합니다.
2단계: API 키 설정 후 실행하기
사용할 모델에 맞춰 API 키를 설정합니다.
export OPENAI_API_KEY=your_api_key_here
export ANTHROPIC_API_KEY=your_api_key_here이제 에이전트 팀을 실행합니다.
cagent run team.yaml조정자가 작업을 위임하고, 리서처가 정보를 모으고, 작가가 초안을 작성합니다. 5분도 안 걸려 작동하는 에이전트 팀이 완성됩니다.
3단계: Docker Hub에 공유하기
만든 에이전트 팀을 Docker Hub에 올립니다.
cagent push ./team.yaml org/research-writer이제 팀원 누구나 동일한 설정으로 실행할 수 있습니다.
cagent run docker.io/org/research-writercagent의 핵심 기능
cagent는 멀티 에이전트 시스템 구축에 필요한 요소들을 갖추고 있습니다.
멀티 에이전트 아키텍처를 지원합니다. 각 도메인에 특화된 에이전트를 만들고, 상위 에이전트가 하위 에이전트에게 작업을 위임하는 구조를 선언적으로 정의할 수 있습니다.
풍부한 도구 생태계를 제공합니다. MCP 프로토콜을 통해 외부 도구와 API를 연결할 수 있습니다. Docker MCP Gateway를 사용하면 컨테이너화된 MCP 서버를 바로 활용할 수 있고, 표준 MCP 서버도 지원합니다.
스마트 위임이 가능합니다. 에이전트가 작업을 자동으로 가장 적합한 전문가에게 라우팅합니다. 복잡한 라우팅 로직을 직접 작성할 필요가 없습니다.
고급 추론을 지원합니다. think, todo, memory 같은 내장 도구로 복잡한 문제를 단계적으로 해결할 수 있습니다.
다양한 AI 제공자와 호환됩니다. OpenAI, Anthropic, Gemini, Docker Model Runner를 모두 지원하므로 상황에 맞는 모델을 선택하거나 조합할 수 있습니다.
실전 활용 사례
개발자들은 이미 다양한 용도로 cagent를 활용하고 있습니다.
GitHub PR과 이슈 자동 처리: 오픈소스 프로젝트에서 매일 수십 개의 PR과 이슈가 쌓입니다. 수집 에이전트는 GitHub API로 새 PR을 읽고 테스트 실패 여부를 확인합니다. 작가 에이전트는 “이 PR은 breaking change를 포함하므로 major 버전 업데이트가 필요합니다”처럼 구체적인 코멘트를 작성하고, 조정자는 보안 관련 이슈는 즉시 팀에 알림을 보내는 규칙을 적용합니다.
기술 리서치 자동화: “Kubernetes 보안 모범 사례”를 조사한다고 가정해봅시다. 리서처 에이전트는 공식 문서, 최신 CVE 보고서, Stack Overflow 토론을 검색해 5개 핵심 출처를 찾습니다. 작가 에이전트는 이를 “취약점 스캔 자동화”, “RBAC 설정”, “네트워크 정책” 같은 카테고리로 정리한 2페이지 요약을 만들고, 리뷰어 에이전트는 사실 확인과 함께 너무 기술적인 용어를 쉬운 표현으로 다듬습니다.
고객 문의 지능형 라우팅: 고객 지원팀에 “결제가 안 돼요”부터 “API 인증 에러”까지 다양한 문의가 들어옵니다. 라우터 에이전트는 문의 유형을 분류하고, 기술 문의는 지식베이스 에이전트가 내부 API 문서와 장애 이력을 검색해 답변 초안을 만듭니다. 편집 에이전트는 고객 이메일이나 계정 ID 같은 민감 정보를 제거한 후 담당자에게 전달합니다.
각 사례는 같은 방식으로 시작됩니다. YAML 파일 하나와 아이디어만 있으면 됩니다.
시작하기
cagent는 Homebrew로 간단히 설치할 수 있습니다.
brew install cagentcagent new 명령으로 프롬프트만 입력하면 자동으로 에이전트나 에이전트 팀을 생성할 수도 있습니다.
cagent new첫 번째 에이전트를 직접 만들어보고 싶다면 간단한 예제부터 시작하세요. basic_agent.yaml 파일을 만듭니다.
agents:
root:
model: openai/gpt-5-mini
description: 유용한 AI 어시스턴트
instruction: |
다양한 작업을 돕는 지식이 풍부한 어시스턴트입니다.
도움이 되고, 정확하며, 간결하게 답변합니다.실행은 한 줄이면 됩니다.
cagent run basic_agent.yamlMCP로 도구 연결하기
에이전트에 외부 도구를 연결하면 능력이 크게 향상됩니다. Docker MCP Gateway를 사용하면 컨테이너화된 MCP 서버를 바로 사용할 수 있습니다.
앞의 기본 에이전트에 DuckDuckGo 검색 기능을 추가해보겠습니다.
version: "2"
agents:
root:
model: openai/gpt-5-mini
description: 유용한 AI 어시스턴트
instruction: |
다양한 작업을 돕는 지식이 풍부한 어시스턴트입니다.
검색 결과를 디스크에 저장합니다.
toolsets:
- type: mcp
ref: docker:duckduckgo파일 읽기와 쓰기 기능도 추가할 수 있습니다.
version: "2"
agents:
root:
model: openai/gpt-5-mini
description: 유용한 AI 어시스턴트
instruction: |
다양한 작업을 돕는 지식이 풍부한 어시스턴트입니다.
검색 결과를 디스크에 저장합니다.
toolsets:
- type: mcp
ref: docker:duckduckgo
- type: mcp
command: rust-mcp-filesystem
args: ["--allow-write", "."]
tools: ["read_file", "write_file"]
env:
- "RUST_LOG=debug"이제 에이전트는 웹을 검색하고, 파일을 읽고 쓸 수 있습니다.
멀티 에이전트 시스템 구축이 더 이상 복잡한 코드 작성의 영역이 아닙니다. cagent는 YAML로 정의하고, 로컬에서 실행하고, 팀과 공유하는 간단한 흐름으로 이 작업을 바꿔놓습니다. 오픈소스로 공개되어 있어 누구나 시작할 수 있고, Docker 생태계와 자연스럽게 통합됩니다. 에이전트를 만들고 공유하는 일이 컨테이너를 다루는 것만큼 쉬워진 지금, 여러분의 팀에 어떤 에이전트가 필요한지 생각해보세요.
참고자료:
답글 남기기