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:
- What are the services?
Your containers (e.g.,agent,redis,nginx). - How do they run?
Ports, environment variables, healthchecks, restart policies, and resource hints. - 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.pyandtools.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
agentcontainer), - 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.



Comments