Skip to content
August 16, 2025

Docker Compose for AI Agents, Part 2: Operate & Evolve

· 3 min read · Containers, DevOps, Docker, GenAI

In the last post we built a tiny FastAPI agent: it answers general questions directly and calls a get_weather tool (Open-Meteo, no key) only for weather queries. We ran the whole thing with a single docker compose up.

This time we focus on reliability and portability without rewriting Python. Two small files do the heavy lifting:

  • Dockerfile — freezes the environment (exact Python + pinned libraries).
  • compose.yaml — declares how to run (ports, env vars, health, restart).

A simple mental model

  • Dockerfile = the image: your code plus a fixed Python and pinned dependencies.
  • compose.yaml = the runtime: how that image runs — ports, env vars, health checks, restart policy.

To change how it runs, edit compose.yaml; to change what’s inside, edit the Dockerfile — not your app code.

Dockerfile — same interpreter, same libs, every time

What it is: a tiny recipe for your runtime image.
Why it matters: no “works on my machine,” fast rebuilds (cached deps), clear contract for teammates and CI.

Minimal template

FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY agent.py tools.py ./

# Optional but recommended: drop root privileges
RUN useradd -u 10001 -m appuser
USER appuser

EXPOSE 8000
CMD ["uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "8000"]

Concepts to remember

  • Base image pins the interpreter and OS libs.
  • requirements.txt keeps dependency installs deterministic.
  • Dropping root is a small, high-value hardening step.

compose.yaml — one file that says how to run

What it is: a declarative runtime contract you can share and version.
Why it matters: one command runs the same stack everywhere; you get operability (health, restart) without touching code.

services:
agent:
build: .
env_file: .env
ports: ["8000:8000"]
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://localhost:8000/docs"]
interval: 10s
timeout: 3s
retries: 10

Concepts to remember

  • Ports expose your API; env_file injects config at start time.
  • Restart and healthcheck add resilience and readiness with zero code changes.
  • When you add a cache/DB/proxy later, you just add another service here.

Two tiny helpers

  • requirements.txt — pin Python dependencies to prevent version drift (e.g., matching openai and httpx).
  • .env — hold runtime settings and secrets (e.g., OPENAI_API_KEY) that Compose injects at start; don’t bake them into images.

What breaks without these — and how this setup fixes it

Everyday ops

docker compose logs -f agent
docker compose build --no-cache
docker compose down

Production-Ready Next Steps

  • Profiles & overrides: keep compose.yaml simple; add compose.prod.yaml for stricter prod settings—still no code changes.
  • Add a cache/DB/proxy: declare new services in Compose; the wiring stays in YAML.
  • Scale out later: introduce a lightweight proxy and run multiple agent replicas—again, mostly Compose edits.

This two-part series shows how Docker Compose turns a fragile prompt app into a small, dependable AI agent service you can share and scale.

Part 1 builds a FastAPI agent that answers normally and, only for weather questions, calls a get_weather tool using Open-Meteo (no API key); the Dockerfile, compose.yaml, pinned requirements.txt, and a .env make it one-command, reproducible, and tidy.

Part 2 focuses on concepts: the Dockerfile locks the environment (exact Python + deps) while compose.yaml defines the runtime (ports, env, health, restart), giving reliability and a clean path to grow—add services or scale—by editing Compose rather than rewriting code.

Tags: , , ,

Comments

Leave a Reply