AutoGen Tutorial (Python): deploying with Docker for beginners

This tutorial shows how to package a basic AutoGen Python agent setup into a Docker container and run it locally. You’d use this when you want the same agent code to run consistently on your laptop, in CI, or on a server without dependency drift.

What You'll Need

• •Python 3.10 or newer
• •Docker Desktop or Docker Engine installed
• •An OpenAI API key
• •autogen-agentchat installed in your Python environment
• •A working project folder with permission to create files
• •Basic familiarity with running Python scripts and Docker commands

Step-by-Step

1. •Create a small project with one agent script and one requirements file.
   Keep the first version simple: one assistant agent, one user proxy, and a single task so you can verify Docker before adding multi-agent complexity.

mkdir autogen-docker-demo
cd autogen-docker-demo
touch app.py requirements.txt Dockerfile .dockerignore

2. •Add the Python dependencies your container needs.
   For beginner-friendly deployment, pin the AutoGen package and load your OpenAI key from the environment instead of hardcoding it.

# requirements.txt
autogen-agentchat==0.4.8
openai==1.59.7
python-dotenv==1.0.1

3. •Write a minimal AutoGen app that reads the API key from the environment and runs one chat turn.
   This example uses AssistantAgent from autogen_agentchat and prints the model response to stdout, which is enough to prove the container works.

# app.py
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.messages import TextMessage
from autogen_ext.models.openai import OpenAIChatCompletionClient


def main() -> None:
    api_key = os.environ["OPENAI_API_KEY"]

    model_client = OpenAIChatCompletionClient(
        model="gpt-4o-mini",
        api_key=api_key,
    )

    agent = AssistantAgent(
        name="assistant",
        model_client=model_client,
        system_message="You are a concise assistant.",
    )

    result = agent.run(
        task=[TextMessage(content="Say hello in one sentence.", source="user")]
    )

    print(result)


if __name__ == "__main__":
    main()

4. •Add a Dockerfile that installs dependencies and runs the script inside a slim Python image.
   The important part is keeping the image small and passing secrets at runtime, not during build.

FROM python:3.11-slim

WORKDIR /app

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

COPY app.py .

CMD ["python", "app.py"]

5. •Ignore local clutter so your image stays clean.
   This prevents your virtual environment, cache files, and editor artifacts from being copied into the build context.

# .dockerignore
__pycache__/
*.pyc
*.pyo
*.pyd
.venv/
venv/
.env
.git/
.DS_Store

6. •Build and run the container with your API key injected at runtime.
   If you’re on macOS or Linux, export the variable first; on Windows PowerShell, set it for that session before running Docker.

docker build -t autogen-docker-demo .

export OPENAI_API_KEY="your_api_key_here"
docker run --rm -e OPENAI_API_KEY="$OPENAI_API_KEY" autogen-docker-demo

Testing It

When it works, the container should start, call the model once, and print an AutoGen result object to your terminal. If you get an authentication error, check that OPENAI_API_KEY is actually present inside the container and that you didn’t bake it into the image by mistake.

If Docker fails during pip install, confirm that requirements.txt matches compatible versions of autogen-agentchat and openai. If the script hangs or errors on import, rebuild after checking that every package in app.py exists in the installed dependencies.

A good sanity check is to run the same script locally outside Docker with the same environment variable set. If local works but Docker doesn’t, the problem is usually image contents, missing env vars, or version mismatch.

Next Steps

• •Add a second agent and move from a single response to multi-agent coordination using AutoGen’s group chat patterns.
• •Replace hardcoded model names with environment variables so you can switch models per deployment target.
• •Add health checks and structured logging before deploying this into Kubernetes or a cloud container service

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.