docker-agent-packaging

Docker Agent Packaging

When to Use Docker for Agents

Docker is the right choice when your agent has requirements that exceed what a simple package manager can handle. Use this decision framework:

Situation	Use Docker?	Why
Complex ML dependencies (PyTorch, transformers, CUDA)	Yes	Reproducible environment eliminates "works on my GPU"
Multi-service architecture (agent + vector store + DB)	Yes	Compose orchestrates the full stack in one command
Server-side agent (API endpoint, webhook handler)	Yes	Standard deployment target for every cloud platform
GPU inference required	Yes	nvidia-container-toolkit provides clean GPU passthrough
Team needs identical dev environments	Yes	Dev containers eliminate onboarding friction
Simple CLI tool with few deps	No	Use a single binary (Go/Rust) or uvx/npx
Agent is just an MCP server	No	Use npm/PyPI; MCP clients handle lifecycle
Users are non-technical without Docker installed	No	Docker itself is a prerequisite most non-devs don't have
Lightweight Python script calling APIs	No	pip install or uvx is faster with zero overhead

Rule of thumb: if your agent needs more than one process or has dependencies that fight each other across machines, Docker is the answer. If it is a single-process CLI tool, Docker adds overhead without value.

---

Dockerfile for Python AI Agents

Multi-stage builds keep your runtime image small by separating build-time tools from the final artifact.

# =============================================================================
# Stage 1: Build — install dependencies in an isolated layer
# =============================================================================
FROM python:3.12-slim AS builder

# Prevent Python from writing .pyc files and enable unbuffered output
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

WORKDIR /app

# Install system-level build dependencies (removed in runtime stage)
RUN apt-get update && \
    apt-get install -y --no-install-recommends gcc libpq-dev && \
    rm -rf /var/lib/apt/lists/*

# Copy dependency manifest first (layer caching: deps change less than code)
COPY requirements.txt .

# Install Python dependencies into a virtual environment
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install --no-cache-dir -r requirements.txt

# =============================================================================
# Stage 2: Runtime — minimal image with only what's needed to run
# =============================================================================
FROM python:3.12-slim AS runtime

# Runtime system deps only (no compiler)
RUN apt-get update && \
    apt-get install -y --no-install-recommends libpq5 curl && \
    rm -rf /var/lib/apt/lists/*

# Create non-root user (never run agents as root)
RUN groupadd --gid 1000 agent && \
    useradd --uid 1000 --gid agent --shell /bin/bash --create-home agent

WORKDIR /app

# Copy virtual environment from builder
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Copy application source
COPY --chown=agent:agent . .

# Switch to non-root user
USER agent

# Expose the agent's API port (change to match your agent)
EXPOSE 8000

# Health check — container orchestrators use this to know if agent is alive
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# API keys are NEVER baked into the image — pass at runtime via -e or .env
# ENV ANTHROPIC_API_KEY=  (do NOT set a default value)

# Start the agent
CMD ["python", "-m", "my_agent.server"]