Agent Framework — Docker Starter

Docker-first starter for building AI agents with Microsoft Agent Framework on .NET 8 and Azure OpenAI.

• Runs entirely inside a container — no local .NET install required.
• Dev Container / Codespaces ready — one-click reproducible dev environment.
• Multi-stage Dockerfile with Alpine runtime and a non-root user.
• Works with both API key and Azure AD (AzureCliCredential / DefaultAzureCredential).

Part of a series of Docker-first samples for Microsoft Agent Framework: agent-framework-devcontainer · mcp-docker-starter · ai-agents-compose-stack

---

Why Docker-first?

Problem running agents locally	What this starter gives you
"Works on my machine" env drift	Reproducible image, same across team
Onboarding takes hours	docker compose up — done
Hard to share with non-.NET teammates	Anyone with Docker can run it
Messy auth setup	Key-based or Azure AD, both supported
Hard to deploy to Azure / K8s later	Same image deploys anywhere

---

Requirements

• Docker Desktop or Docker Engine + Compose v2
• An Azure OpenAI resource with a chat deployment (e.g. gpt-4o-mini)

No .NET SDK needed on your host — the build runs inside the container.

---

Pull from GHCR (skip the build)

Pre-built multi-arch images (linux/amd64 + linux/arm64) with SBOM and build provenance attestations are published to GHCR on every push to main.

docker pull ghcr.io/ppiova/agent-framework-devcontainer:latest
docker run --rm --env-file .env ghcr.io/ppiova/agent-framework-devcontainer:latest "Tu prompt"

Pin to an immutable digest for production:

docker pull ghcr.io/ppiova/agent-framework-devcontainer@sha256:<digest>

Or reference it directly from compose.yaml:

services:
  agent:
    image: ghcr.io/ppiova/agent-framework-devcontainer:latest
    env_file: [.env]

---

Quickstart

1. Clone and configure

git clone https://github.com/ppiova/agent-framework-devcontainer.git
cd agent-framework-devcontainer
cp .env.example .env

Edit .env with your Azure OpenAI values:

AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini
AZURE_OPENAI_API_KEY=<your-key>    # optional — see "Auth modes" below

2. Run with Docker Compose

docker compose up --build

You should see the agent respond in streaming:

🤖 [DockerDemoAgent] ejecutándose en contenedor
📍 Endpoint: https://...
🧠 Deployment: gpt-4o-mini
🔑 Auth: API Key

> Prompt: Preséntate en una frase y explicá por qué conviene...
--- Respuesta (streaming) ---
¡Hola! Soy DockerDemoAgent, un agente corriendo en un contenedor...
------------------------------

3. Ask your own prompt

docker compose run --rm agent "Dame 3 razones para usar Docker al desplegar agentes de IA"

Or with plain Docker:

docker build -t agent-starter .
docker run --rm --env-file .env agent-starter "¿Qué es un multi-agent workflow?"

---

Dev Container / Codespaces

Open the repo in VS Code → "Reopen in Container", or click Open in Codespaces at the top of this README.

You get:

• .NET 8 SDK + C# Dev Kit
• Docker CLI (docker-outside-of-docker)
• Azure CLI + GitHub CLI
• dotnet restore runs automatically on create

Once inside the container:

az login                    # if using Azure AD auth
dotnet run --project src

---

Auth modes

The agent resolves credentials in this order:

1. AZURE_OPENAI_API_KEY — if present, use key-based auth (simplest inside Docker).
2. AzureCliCredential — works in the Dev Container after az login.
3. DefaultAzureCredential — works with environment variables (AZURE_CLIENT_ID/AZURE_TENANT_ID/AZURE_CLIENT_SECRET) or Managed Identity when deployed to Azure (App Service, Container Apps, AKS).

This means the same image runs locally, in CI, and in production — only the credential source changes.

---

Project layout

.
├── .devcontainer/
│   └── devcontainer.json     # Codespaces / VS Code Dev Container config
├── src/
│   ├── AgentStarter.csproj   # Microsoft.Agents.AI + Azure.AI.OpenAI
│   └── Program.cs            # Minimal streaming agent
├── .dockerignore
├── .env.example
├── .gitignore
├── compose.yaml              # Compose orchestration + env loading
├── Dockerfile                # Multi-stage Alpine build, non-root user
└── README.md

---

Dockerfile highlights

• Multi-stage: mcr.microsoft.com/dotnet/sdk:8.0-alpine for build, mcr.microsoft.com/dotnet/runtime:8.0-alpine for runtime — final image stays under ~100 MB.
• Layer caching: csproj is restored before copying source, so source-only changes skip the restore layer.
• Non-root user (agent) — OWASP / CIS hardening baseline.
• UseAppHost=false + dotnet EntryPoint — smaller, faster startup.
• .dockerignore excludes bin/, obj/, .git/, .env from the build context.

---

Next steps — extend this starter

This is intentionally minimal so you can build on it:

• Add function tools ([Description]-annotated methods registered in CreateAIAgent)
• Add multi-turn with AgentThread
• Wire OpenTelemetry and ship traces to an OTLP collector
• Swap Azure OpenAI for Ollama or OpenAI.com (see Microsoft.Extensions.AI)
• Deploy to Azure Container Apps or AKS using the same image

For multi-agent + observability patterns, see ai-agents-compose-stack. For containerized MCP integrations, see mcp-docker-starter.

---

License

MIT — by Pablo Piovano · Microsoft MVP in AI.