Agent Patterns Lab

Agent Patterns Lab is a collection of 9 design patterns that close that gap. Each pattern solves a named architectural problem with working code you can run, study, and adapt. The progression takes you from a single POST /run REST endpoint to a cloud-deployed, authenticated, dynamically-discoverable multi-agent system.

Repository: github.com/ksopyla/agent-patterns-lab

Why This Project Exists #

I have spent years building AI-powered products in enterprise environments. The recurring lesson: knowing what an agent framework can do is the easy part. Knowing how to structure, deploy, and operate agents that work together across services, trust boundaries, and cloud environments — that is the hard part, and almost nobody writes about it.

This project is my attempt to document the architectural decisions that matter, through code that actually runs. Every pattern:

• Solves a real architectural problem that the previous pattern cannot handle
• Has clear “when to use / when to avoid” criteria
• Shows trade-offs, not just happy paths
• Builds on the previous one — you experience the limitation before learning the solution

The Design Patterns #

Foundation Tier — Single Docker network, one team, agent internals #

Distribution Tier — Multi-service, multi-team, real distributed systems #

Enterprise Tier — Production readiness, cloud deployment #

Why Each Transition Matters #

Every pattern exists because the previous one creates a real limitation:

P01 ─── Hardcoded tools can't be shared ──────────────── P02
P02 ─── Every request starts from scratch ────────────── P03
P03 ─┬─ Memory grows unbounded ──────────────────────── P04 (optional)
     └─ A second team arrives, can't import their code ─ P05
P05 ─── Third team needs both, sequential is too slow ── P06
P06 ─── Team 2 moves to external partner, no trust ──── P07
P07 ─── New agents appear, consumers need code changes ─ P08
P08 ─── Docker Compose doesn't work in production ───── P09

The Domain: A Crypto Intelligence Platform #

Abstract patterns are hard to internalize. Concrete stories stick. All nine patterns share a single, evolving domain — a crypto intelligence platform where three specialized teams emerge as complexity demands them.

 ┌─────────────────────────┐  ┌─────────────────────────┐  ┌─────────────────────────┐
 │  TEAM 1: INTELLIGENCE   │  │ TEAM 2: TECHNICAL       │  │ TEAM 3: TRADING         │
 │  (Patterns 01-04)       │  │ ANALYSIS (Pattern 05+)  │  │ SIGNALS (Pattern 06+)   │
 │                         │  │                         │  │                         │
 │  Research Planner       │  │  Price Collector        │  │  Signal Synthesizer     │
 │  News Scanner           │  │  Indicator Calculator   │  │  Risk Assessor          │
 │  Project Profiler       │  │  Level Analyst          │  │  Trade Advisor          │
 │  Community Analyst      │  │  Technical Reporter     │  │                         │
 │  Intelligence Compiler  │  │                         │  │                         │
 └────────────┬────────────┘  └────────────┬────────────┘  └────────────┬────────────┘
              │                            │                            │
              │         A2A Protocol       │         A2A Protocol       │
              └────────────────────────────┴────────────────────────────┘

The story unfolds in three acts:

Act 1 — One Team, Growing Capabilities (Patterns 01–04). You are Team 1: Intelligence. Three agents research crypto projects inside a single LangGraph pipeline. It works — until you hit hardcoded tools, stateless requests, and unbounded memory. Each limitation drives the next pattern.

Act 2 — Teams Multiply, Protocols Emerge (Patterns 05–06). Team 2: Technical Analysis arrives as a separate service with a separate codebase. You cannot import their code. You need a protocol. Then Team 3 needs data from both teams simultaneously — sequential calls take 50+ seconds. Async communication becomes the only viable path.

Act 3 — Enterprise Reality (Patterns 07–09). Team 2 moves to an external partner. Implicit trust is gone. New agents need dynamic discovery. Three teams deploy to Azure as independent Container Apps with Infrastructure as Code, Managed Identity, and per-team CI/CD pipelines.

Tech Stack #

Quick Start #

git clone https://github.com/ksopyla/agent-patterns-lab.git
cd agent-patterns-lab
cp .env.example .env
# Fill in your API keys (Azure OpenAI or Anthropic, LangSmith)

# Run Pattern 01 from inside the example folder
cd examples/01-orchestrator-pipeline
docker compose up --build

# Verify it's running
curl http://localhost:8000/health

# Submit a research request
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Research the Arbitrum crypto project"}'

Every pattern supports VERBOSE=true in .env, which logs agent reasoning steps, tool call inputs/outputs, inter-agent message payloads, and LangSmith trace IDs. Reading verbose output is how you learn what agents are actually doing.

Project Structure #

agent-patterns-lab/
├── examples/                  # One folder per pattern (self-contained)
│   ├── 01-orchestrator-pipeline/
│   │   ├── README.md          # Pattern documentation (theory + walkthrough)
│   │   ├── pyproject.toml
│   │   ├── docker-compose.yml
│   │   ├── endpoints.http     # Ready-to-run REST requests
│   │   ├── src/
│   │   └── tests/
│   └── ...
├── libs/common/               # Shared utilities (agent_common package)
├── docs/                      # Curriculum, vision, changelog
├── infra/                     # Docker base images, Azure Bicep templates
└── .github/                   # CI/CD workflows, PR templates

Each example is designed to run from inside its own folder. Examples share the repository-root .env file and the workspace libs/common package. Container images build from infra/docker/base/Dockerfile.agent with per-example build arguments.

Open Source #

The entire project is open source under the MIT license.

• Code: github.com/ksopyla/agent-patterns-lab
• Blog: ai.ksopyla.com