Docker로 에이전틱 AI 애플리케이션 빌드 및 실행하기
Docker로 에이전틱 AI 애플리케이션 빌드 및 실행하기 (Build and run agentic AI applications with Docker)
Docker Model Runner와 MCP Toolkit을 사용해 AI 에이전트 애플리케이션을 만드는 방법을 설명하는 가이드예요.
출처: 문서
본문
팁: 이 가이드는 익숙한 Docker Compose 워크플로우를 사용해 에이전틱 AI 애플리케이션을 오케스트레이션해요. 더 매끄러운 개발 경험을 위해, AI 에이전트 실행과 관리를 단순화하는 전용 에이전트 런타임인 Docker Agent를 확인하세요.
소개 (Introduction)
에이전틱(agentic) 애플리케이션은 소프트웨어가 빌드되는 방식을 변화시키고 있어요. 이 앱들은 단순히 응답하지 않고, 결정하고, 계획하고, 행동해요. 모델이 구동하고 에이전트가 오케스트레이션하며 API, 도구, 서비스와 실시간으로 통합돼요.
이 새로운 에이전틱 애플리케이션들은 무엇을 하든 공통 아키텍처를 공유해요. 세 가지 핵심 구성 요소로 만들어진 새로운 종류의 스택이에요:
- 모델 (Models): GPT, CodeLlama, Mistral 같은 것들이에요. 추론, 작성, 계획을 수행해요. 지능 뒤의 엔진이에요.
- 에이전트 (Agent): 로직이 사는 곳이에요. 에이전트는 목표를 받아 세분화하고 완수 방법을 파악해요. 모든 것을 오케스트레이션해요. UI, 도구, 모델, 게이트웨이와 소통해요.
- MCP 게이트웨이 (MCP gateway): 에이전트를 외부 세상(API, 도구, 서비스 포함)에 연결하는 것이에요. 에이전트가 Model Context Protocol (MCP)을 통해 기능을 호출하는 표준 방식을 제공해요.
Docker는 모델과 도구 게이트웨이를 Docker Compose를 사용하는 개발자 친화적 워크플로우로 통합해 이 AI 기반 스택을 더 간단하고, 빠르고, 안전하게 만들어요.
이 가이드는 에이전틱 개발의 핵심 구성 요소를 안내하고 Docker가 다음 도구로 어떻게 모든 것을 연결하는지 보여줘요:
- Docker Model Runner — 간단한 명령과 OpenAI 호환 API로 LLM을 로컬에서 실행할 수 있게 해줘요.
- Docker MCP Catalog 및 Toolkit — Model Context Protocol (MCP)을 사용해 API, 데이터베이스 같은 외부 도구를 발견하고 안전하게 실행하게 해줘요.
- Docker MCP Gateway — MCP 서버를 오케스트레이션하고 관리하게 해줘요.
- Docker Compose — 단일 파일로 다중 컨테이너 애플리케이션을 정의하고 실행하게 해주는 모든 것을 묶는 도구예요.
이 가이드에서는 이미 익숙한 동일한 Compose 워크플로우를 사용해요. 그런 다음 Compose 파일, Dockerfile, 앱을 살펴보며 어떻게 함께 동작하는지 볼 거예요.
사전 요구사항 (Prerequisites)
이 가이드를 따르려면 다음이 필요해요:
- Docker Desktop 4.43 이상 설치
- Docker Model Runner 활성화
- 최소한 다음 하드웨어 사양:
- VRAM: 3.5 GB
- Storage: 2.31 GB
1단계: 샘플 애플리케이션 클론하기 (Step 1: Clone the sample application)
Docker의 AI 기능을 사용해 모델을 외부 도구에 연결하는 방법을 보여주는 기존 샘플 애플리케이션을 사용할 거예요.
$ git clone https://github.com/docker/compose-for-agents.git
$ cd compose-for-agents/adk/
2단계: 로컬에서 애플리케이션 실행하기 (Step 2: Run the application locally)
Docker Compose로 전체 애플리케이션 스택을 로컬에서 실행하려면 머신이 필요한 하드웨어 요구사항을 충족해야 해요. 이렇게 하면 클라우드에서 실행할 필요 없이 모델과 MCP 게이트웨이를 포함해 애플리케이션을 엔드 투 엔드로 테스트할 수 있어요. 이 특정 예시는 컨텍스트 크기 10000의 Gemma 3 4B 모델을 사용해요.
하드웨어 요구사항:
- VRAM: 3.5 GB
- Storage: 2.31 GB
머신이 그 요구사항을 초과한다면 더 큰 컨텍스트 크기나 더 큰 모델로 애플리케이션을 실행해 에이전트 성능을 개선하는 것을 고려하세요. compose.yaml 파일에서 모델과 컨텍스트 크기를 쉽게 업데이트할 수 있어요.
로컬에서 애플리케이션을 실행하려면:
- 클론한 저장소의
adk/디렉터리에서 터미널에 다음 명령을 실행해 애플리케이션을 빌드하고 실행하세요:
$ docker compose up
이 명령을 처음 실행하면 Docker가 Docker Hub에서 모델을 가져오는데 시간이 걸릴 수 있어요.
-
http://localhost:8080을 방문하세요. 프롬프트에 올바르거나 잘못된 사실을 입력하고 엔터를 누르세요. 한 에이전트가 DuckDuckGo를 검색해 이를 검증하고, 다른 에이전트가 출력을 수정해요. -
완료되면 터미널에서
ctrl-c를 눌러 애플리케이션을 중지하세요.
3단계: 애플리케이션 환경 검토하기 (Step 3: Review the application environment)
adk/ 디렉터리에서 compose.yaml 파일을 찾을 수 있어요. 텍스트 편집기에서 열어 서비스가 어떻게 정의되는지 확인하세요.
services:
adk:
build:
context: .
ports:
# expose port for web interface
- "8080:8080"
environment:
# point adk at the MCP gateway
- MCPGATEWAY_ENDPOINT=http://mcp-gateway:8811/sse
depends_on:
- mcp-gateway
models:
gemma3:
endpoint_var: MODEL_RUNNER_URL
model_var: MODEL_RUNNER_MODEL
mcp-gateway:
# mcp-gateway secures your MCP servers
image: docker/mcp-gateway:latest
use_api_socket: true
command:
- --transport=sse
# add any MCP servers you want to use
- --servers=duckduckgo
models:
gemma3:
# pre-pull the model when starting Docker Model Runner
model: ai/gemma3:4B-Q4_0
context_size: 10000 # 3.5 GB VRAM
# increase context size to handle search results
# context_size: 131000 # 7.6 GB VRAM
앱은 세 가지 주요 구성 요소로 이루어져 있어요:
adk서비스: 에이전틱 AI 애플리케이션을 실행하는 웹 애플리케이션. 이 서비스는 MCP 게이트웨이와 모델과 소통해요.mcp-gateway서비스: 앱을 외부 도구와 서비스에 연결하는 MCP 게이트웨이.models블록: 애플리케이션과 함께 사용할 모델을 정의해요.
compose.yaml 파일을 살펴보면 모델에 대한 두 가지 주목할 만한 요소를 발견할 거예요:
adk서비스의 서비스 수준models블록- 최상위(top-level)
models블록
이 두 블록이 함께 Docker Compose가 지정된 LLM에 ADK 웹 앱을 자동으로 시작하고 연결하게 해줘요.
팁: 더 많은 모델을 찾고 있나요? Docker AI Model Catalog를 확인하세요.
compose.yaml 파일을 살펴보면 게이트웨이 서비스가 Docker가 유지 관리하는 이미지 docker/mcp-gateway:latest임을 알 수 있어요.
이 이미지는 애플리케이션이 MCP 서버에 연결할 수 있게 해주는 Docker의 오픈소스 MCP Gateway예요. MCP 서버는 모델이 호출할 수 있는 도구를 노출해요. 이 예시에서는 duckduckgo MCP 서버를 사용해 웹 검색을 수행해요.
팁: 더 많은 MCP 서버를 찾고 있나요? Docker MCP Catalog를 확인하세요.
Compose 파일의 몇 줄의 지시사항만으로 에이전틱 AI 애플리케이션의 모든 필요한 서비스를 실행하고 연결할 수 있어요.
Compose 파일에 더해, Dockerfile과 그것이 만드는 entrypoint.sh 스크립트가 빌드 및 런타임 시 AI 스택을 연결하는 역할을 해요. adk/ 디렉터리에서 Dockerfile을 찾을 수 있어요. 텍스트 편집기에서 열어보세요.
# Use Python 3.11 slim image as base
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
RUN pip install uv
WORKDIR /app
# Install system dependencies
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy \
uv pip install --system .
# Copy application code
COPY agents/ ./agents/
RUN python -m compileall -q .
COPY <<EOF /entrypoint.sh
#!/bin/sh
set -e
if test -f /run/secrets/openai-api-key; then
export OPENAI_API_KEY=$(cat /run/secrets/openai-api-key)
fi
if test -n "\${OPENAI_API_KEY}"; then
echo "Using OpenAI with \${OPENAI_MODEL_NAME}"
else
echo "Using Docker Model Runner with \${MODEL_RUNNER_MODEL}"
export OPENAI_BASE_URL=\${MODEL_RUNNER_URL}
export OPENAI_MODEL_NAME=openai/\${MODEL_RUNNER_MODEL}
export OPENAI_API_KEY=cannot_be_empty
fi
exec adk web --host 0.0.0.0 --port 8080 --log_level DEBUG
EOF
RUN chmod +x /entrypoint.sh
# Create non-root user
RUN useradd --create-home --shell /bin/bash app \
&& chown -R app:app /app
USER app
ENTRYPOINT [ "/entrypoint.sh" ]
entrypoint.sh에는 다섯 가지 핵심 환경 변수가 있어요:
MODEL_RUNNER_URL: Docker Model Runner HTTP 엔드포인트를 가리키도록 Compose가(서비스 수준models:블록을 통해) 주입해요.MODEL_RUNNER_MODEL: Model Runner에서 실행할 모델을 선택하도록 Compose가 주입해요.OPENAI_API_KEY: Compose 파일에openai-api-key시크릿을 정의하면 Compose가 그것을/run/secrets/openai-api-key에 마운트해요. entrypoint 스크립트가 그 파일을 읽어OPENAI_API_KEY로 내보내면, 앱이 Model Runner 대신 호스팅된 OpenAI를 사용하게 돼요.OPENAI_BASE_URL: 실제 키가 없을 때, ADK의 OpenAI 호환 클라이언트가 Docker Model Runner에 요청을 보내도록 이 값을MODEL_RUNNER_URL로 설정해요.OPENAI_MODEL_NAME: Model Runner로 폴백할 때, 클라이언트가 올바른 모델 별칭을 선택하도록 모델에openai/접두사를 붙여요.
이 변수들이 함께 같은 ADK 웹 서버 코드가 다음 중 하나를 매끄럽게 타깃으로 할 수 있게 해줘요:
- 호스팅 OpenAI:
OPENAI_API_KEY(및 선택적으로OPENAI_MODEL_NAME)를 제공하는 경우 - Model Runner:
MODEL_RUNNER_URL과MODEL_RUNNER_MODEL을 OpenAI 클라이언트가 기대하는 변수로 재매핑하는 경우
4단계: 애플리케이션 검토하기 (Step 4: Review the application)
adk 웹 애플리케이션은 환경 변수와 API 호출을 통해 MCP 게이트웨이와 모델에 연결하는 에이전트 구현이에요. ADK(Agent Development Kit)를 사용해 모델이 생성한 답변을 검증하고 다듬기 위해 두 개의 하위 에이전트(Critic과 Reviser)를 조정하는 Auditor라는 이름의 루트 에이전트를 정의해요.
세 에이전트는 다음과 같아요:
- Critic: DuckDuckGo 같은 도구 세트를 사용해 사실적 주장을 검증해요.
- Reviser: Critic이 제공한 검증 결과에 따라 답변을 편집해요.
- Auditor: Critic과 Reviser를 순서대로 실행하는 상위 수준 에이전트. 진입점 역할을 하며 LLM 생성 답변을 평가하고, 검증하고, 최종 출력을 다듬어요.
애플리케이션의 모든 동작은 agents/ 디렉터리 아래 Python으로 정의돼 있어요. 주목할 만한 파일들의 설명은 다음과 같아요:
agents/agent.py: Critic과 Reviser 에이전트를 연결하는 SequentialAgent인 Auditor를 정의해요. 이 에이전트는 애플리케이션의 주요 진입점이며, 실제 검증 도구를 사용해 LLM 생성 콘텐츠를 감사하는 책임이 있어요.agents/sub_agents/critic/agent.py: Critic 에이전트를 정의해요. 언어 모델을 로드하고(Docker Model Runner를 통해), 에이전트의 이름과 동작을 설정하며, MCP 도구(DuckDuckGo 같은)에 연결해요.agents/sub_agents/critic/prompt.py: 외부 도구를 사용해 주장을 추출하고 검증하도록 에이전트에 지시하는 Critic 프롬프트를 포함해요.agents/sub_agents/critic/tools.py:mcp/문자열 파싱, 도구 연결 생성, MCP 게이트웨이 통신 처리를 포함한 MCP 도구 세트 구성을 정의해요.agents/sub_agents/reviser/agent.py: Critic의 결과를 받아 원래 답변을 최소한으로 다시 쓰는 Reviser 에이전트를 정의해요. LLM 출력을 정리하고 올바른 형식인지 확인하는 콜백도 포함해요.agents/sub_agents/reviser/prompt.py: 검증된 주장 결과에 따라 답변 텍스트를 수정하도록 에이전트에 지시하는 Reviser 프롬프트를 포함해요.
MCP 게이트웨이는 MCPGATEWAY_ENDPOINT 환경 변수로 구성돼요. 이 경우 http://mcp-gateway:8811/sse예요. 이를 통해 앱이 Server-Sent Events (SSE)를 사용해 MCP 게이트웨이 컨테이너와 통신할 수 있고, 게이트웨이 자체가 DuckDuckGo 같은 외부 도구 서비스에 대한 접근을 중개해요.
요약 (Summary)
에이전트 기반 AI 애플리케이션은 강력한 새로운 소프트웨어 아키텍처로 부상하고 있어요. 이 가이드에서 출력을 검증하고 다듬기 위해 Critic과 Reviser의 작업을 Auditor 에이전트가 조정하는 모듈식의 chain-of-thought 시스템을 탐구했어요. 이 아키텍처는 로컬 모델 추론을 외부 도구 통합과 구조적이고 모듈식으로 결합하는 방법을 보여줘요.
또한 Docker가 에이전틱 AI 개발을 지원하는 도구 모음을 제공해 어떻게 이 과정을 단순화하는지 보았어요:
- Docker Model Runner: OpenAI 호환 API를 통해 로컬에서 오픈소스 모델을 실행하고 서비스해요.
- Docker MCP Catalog 및 Toolkit: Model Context Protocol (MCP) 표준을 따르는 도구 통합을 시작하고 관리해요.
- Docker MCP Gateway: 에이전트를 외부 도구와 서비스에 연결하기 위해 MCP 서버를 오케스트레이션하고 관리해요.
- Docker Compose: 동일한 워크플로우를 사용해 단일 파일로 다중 컨테이너 에이전틱 AI 애플리케이션을 정의하고 실행해요.
이 도구들로 일관된 워크플로우를 통해 에이전틱 AI 애플리케이션을 효율적으로 개발하고 테스트할 수 있어요.