Skip to content
August 16, 2025

Docker Compose for AI Agents, Part 1: Build & Run

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

Problem Statement

You prototype an AI demo. It runs on your laptop — mostly. Then someone else tries it and hits a different Python version, a missing OS package, a blocked port, or a slightly different setup script. You add a cache; someone else adds a vector DB. Suddenly the “quick demo” is a pile of one-off instructions and brittle shell scripts.

The issue isn’t your code — it’s the runtime. You need a way to describe the runtime once and run it the same way everywhere.

Docker Compose

Docker Compose is a single, declarative YAML file (compose.yaml) that answers three questions about your app’s runtime:

  1. What are the services?
    Your containers (e.g., agent, redis, nginx).
  2. How do they run?
    Ports, environment variables, healthchecks, restart policies, and resource hints.
  3. How do they connect?
    Networks, volumes, and service dependencies.

With one command — docker compose up—Compose builds images, wires services, injects config, and starts the stack the same way on every machine.

What Compose does for an AI agent

Even a single agent benefits immediately:

  • Reproducibility: “same inputs → same runtime” across laptops, CI, and servers.
  • Clean configuration: secrets and settings provided at start (not baked into images).
  • Operational hygiene: health checks, restart behavior, and ports — without touching app code.
  • Composability: when you add a cache, vector DB, or proxy, the code barely changes; the compose file grows.

Let’s prove it with a tiny, real agent that uses a tool to fetch live data.

Use Case

We’ll create a FastAPI service that acts as an agent. When the user asks about weather, the model decides to call a get_weather tool. The tool calls Open-Meteo (free, no API key) to geocode a place and fetch current conditions. If it’s not a weather query, the agent skips the tool call. The agent finally returns a friendly answer.

agent.py — the orchestrator

  • Role: HTTP front door + decision maker. Receives POST /chat, frames messages for the model, and defines a tool schema (get_weather) the model can opt to call.
  • Agentic loop: (1) Ask the model with the tool available. (2) If it calls the tool, execute it and feed the JSON back. (3) Return the model’s final answer.
  • Why it works: separates decision (model) from action (tool) and keeps state per-request (simple, stateless). Add new tools by extending the schema and importing a function.
from fastapi import FastAPI
from pydantic import BaseModel
from openai import OpenAI
import json

from tools import fetch_current_weather  # our local tool

app = FastAPI()
client = OpenAI()  # reads OPENAI_API_KEY from env

SYSTEM_PROMPT = (
    "You are a helpful software agent. "
    "When the user asks about weather, call the 'get_weather' tool with a city or place name. "
    "Otherwise, answer normally."
)

TOOLS = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a location using Open-Meteo (no API key).",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City or place, e.g., 'Chicago' or 'Paris, France'"}
            },
            "required": ["location"]
        }
    }
}]

class ChatIn(BaseModel):
    message: str

@app.post("/chat")
def chat(inp: ChatIn):
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": inp.message},
    ]

    first = client.chat.completions.create(
        model="gpt-4.1-mini",
        messages=messages,
        tools=TOOLS,
        tool_choice="auto",
    )
    msg = first.choices[0].message

    if msg.tool_calls:
        for call in msg.tool_calls:
            if call.function.name == "get_weather":
                args = json.loads(call.function.arguments or "{}")
                data = fetch_current_weather(args.get("location", "").strip())

                messages.append({"role": "assistant", "tool_calls": [call.model_dump()]})
                messages.append({
                    "role": "tool",
                    "tool_call_id": call.id,
                    "name": "get_weather",
                    "content": json.dumps(data)
                })

        final = client.chat.completions.create(
            model="gpt-4.1-mini",
            messages=messages
        )
        return {"reply": final.choices[0].message.content}

    return {"reply": msg.content}

tools.py — side-effects & integrations

  • Role: Do the real-world work cleanly. fetch_current_weather(location) calls Open-Meteo’s geocoder + forecast (no key), then returns compact, predictable JSON.
  • Design: explicit timeouts, small schema, friendly {"error": ...} messages so the agent can respond gracefully. Easy to extend with more tools or caching.
import requests

def fetch_current_weather(location: str):
if not location:
return {"error": "Location is required."}

# 1) Geocode the location name
try:
geo = requests.get(
"https://geocoding-api.open-meteo.com/v1/search",
params={"name": location, "count": 1, "language": "en", "format": "json"},
timeout=8
).json()
except Exception as e:
return {"error": f"Geocoding failed: {e}"}

if not geo.get("results"):
return {"error": f"Could not find coordinates for '{location}'."}

place = geo["results"][0]
lat, lon = place["latitude"], place["longitude"]
resolved_name = f"{place['name']}, {place.get('admin1','')}, {place.get('country','')}".replace(" ,", "").strip(", ")

# 2) Fetch current weather
try:
wx = requests.get(
"https://api.open-meteo.com/v1/forecast",
params={
"latitude": lat,
"longitude": lon,
"current": "temperature_2m,wind_speed_10m,weather_code",
"temperature_unit": "fahrenheit", # change to celsius if you prefer
"wind_speed_unit": "mph",
},
timeout=8
).json()
except Exception as e:
return {"error": f"Weather request failed: {e}"}

curr = wx.get("current", {})
return {
"location_resolved": resolved_name,
"latitude": lat,
"longitude": lon,
"temperature": curr.get("temperature_2m"),
"wind_speed": curr.get("wind_speed_10m"),
"weather_code": curr.get("weather_code"),
"source": "Open-Meteo",
}

requirements.txt

  • Pinned Python dependencies for deterministic installs and to avoid version drift
fastapi==0.115.0
uvicorn==0.30.6
openai==1.50.2
httpx==0.27.2
requests==2.32.3

.env

  • Runtime configuration/secrets (e.g., OPENAI_API_KEY) injected by Compose—kept out of the image and out of Git.
OPENAI_API_KEY=sk-REPLACE_ME

Dockerfile

  • Purpose: Builds a reproducible Python image so the agent runs the same everywhere.
  • What it does:
  • Sets a slim Python base, installs pinned deps from requirements.txt (cached layer).
  • Copies agent.py and tools.py, exposes port 8000, and starts Uvicorn (agent:app).
  • Why it matters: No “works on my machine.” The exact interpreter and OS libs are baked into the image.
FROM python:3.12-slim

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

COPY agent.py tools.py ./
EXPOSE 8000
CMD ["uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "8000"]

compose.yaml

  • Purpose: Declares how the service runs — the runtime contract — for one-command startup.
  • What it does:
  • Builds the image from the Dockerfile, maps 8000:8000, injects env vars via .env.
  • Adds restart policy and health check so the service is resilient and detectable as “ready.”
  • Why it matters: You evolve runtime (limits, replicas, proxy, profiles) without changing Python code
services:
agent:
build: .
env_file: .env
ports:
- "8000:8000"
restart: unless-stopped

Run it

docker compose up --build

Quick test

# Weather → tool path
curl -s -X POST http://localhost:8000/chat \
-H "content-type: application/json" \
-d '{"message":"Weather in New Orleans right now?"}' | jq

# General knowledge → no tool
curl -s -X POST http://localhost:8000/chat \
-H "content-type: application/json" \
-d '{"message":"Explain blue-green deployments in two bullets"}' | jq

Summary

We built a small AI agent: a FastAPI service that answers normal questions directly, and — only when it detects a weather query — calls a get_weather tool that uses Open-Meteo to geocode the place and return current conditions. The agent feeds that JSON back to the model to craft a friendly, live answer.

The hero is Docker Compose. In one compose.yaml, you declared:

  • What runs (the agent container),
  • How it runs (ports, env from .env, healthcheck, restart), and
  • How it connects (ready to add more services later).
    With a single command — docker compose up—you got a reproducible runtime, clean config flow (no secrets baked into images), and operational hygiene by default.

In Part 2, we’ll keep the Python almost untouched and focus on the runtime — because reliability and portability come from two small files:

  • Dockerfile: freezes the environment (Python + libs) so it runs the same on every machine.
  • compose.yaml: declares how to run (ports, env, health, restart) and evolves as you add components—without code changes.

We’ll cover the concepts : what a good Dockerfile buys you, what belongs in Compose, a simple mental model for “image vs. runtime,” and a few “upgrade moves” (profiles, overrides, a tiny proxy, basic limits) you can add later.

We’ll also contrast this with the pain you’d face without Docker/Compose — runtime drift, brittle scripts, leaked secrets, and slow onboarding — so the benefits are crystal clear.

Tags: , , ,

Comments

Leave a Reply