Agent Blueprints

An architecture-first guide to designing LLM workflow and agent systems.

---

This repository teaches you how to think about and design agent systems — before you write a single line of code. It covers both LLM workflows (where the developer controls the flow) and agent patterns (where the LLM controls the flow), with an explicit progression showing how one evolves into the other.

Every pattern is documented at three levels of depth. Read only what you need:

• Overview (Tier 1) — Architecture diagram, tradeoffs, when to use it. 1–2 pages.
• Design (Tier 2) — Component breakdown, data flow, error handling, scaling. 3–5 pages.
• Implementation (Tier 3) — Pseudocode, interfaces, testing strategy, pitfalls. 5–10 pages.

---

For AI tools

If you're an AI tool (Claude Code, Cursor, GitHub Copilot, agent-scaffold, …) reading this repo, start here:

• llms.txt — minimal AI-tool discovery file (llmstxt.org spec).
• agents.md — how to programmatically consume the catalog (entry shapes, tier file conventions, pinning to a version).
• patterns-catalog.yaml — canonical machine-readable index. Schema in PATTERNS_CATALOG_SCHEMA.md.
• meta/HOW_TO_ADD_AN_ENTRY.md — contributor walkthrough, including AI-tool prompts.

---

The three-repo ecosystem

This repo is the first stop in a three-repo pipeline that takes you from pattern to running agent:

flowchart LR
  P["Pattern<br/>agent-blueprints"] --> S["Spec<br/>agent-deployments"]
  S --> G["Generator<br/>agent-scaffold"]
  G --> R["Running agent"]

  style P fill:#e8f5e9
  style S fill:#fff3e0
  style G fill:#fce4ec
  style R fill:#e3f2fd

Loading

• agent-blueprints (this repo) — framework-agnostic cognitive patterns, tradeoffs, and design guidance. Start here if you want to design before you build.
• agent-deployments — opinionated, production-shaped markdown specs for ten concrete agents (Python + TypeScript tracks), plus the reliability/ops layer (auth, rate limiting, retries, idempotency, distributed tracing, observability) that every agent inherits.
• agent-scaffold — a CLI that consumes a deployment spec, asks Claude to emit a complete project, and writes the files atomically to disk.

Boundary: cognitive patterns (how the agent thinks) live here; operational patterns (how the agent survives production) live in agent-deployments. See System Design Heritage for the full mapping.

From pattern to running agent

• Blueprints → Deployments — which deployment recipes use which patterns, and what every recipe inherits from the operational layer.
• Blueprint → Spec → Scaffold — end-to-end walkthrough on one concrete agent (Research Assistant).
• patterns-catalog.yaml — machine-readable index aggregating every pattern + workflow + composition edge. Consumed by agent-deployments CI; regenerate via node meta/validate-metadata.js --emit patterns-catalog.yaml. See PATTERNS_CATALOG_SCHEMA.md.

---

Start Here

If You...	Read This
Are new to LLM systems	Foundations — concepts, terminology, mental models
Need to pick a pattern	Choosing a Pattern — decision flowchart
Want structured LLM pipelines	Workflows — 4 pre-agent patterns
Want autonomous LLM behavior	Agent Patterns — 11 agent architectures
Are designing a production system	Composition — how patterns combine
Want a production-shaped agent	Blueprints → Deployments — which patterns power which deployments
Want to generate a starter project	Blueprint → Spec → Scaffold — end-to-end walkthrough
Are building a reactive system on a queue or stream	Event-Driven Agents — async triggers, idempotency, DLQ
Want to avoid common mistakes	Anti-Patterns — what not to build
Need to test your agent system	Testing Strategies — mock LLMs, evaluation, regression

Workflow Patterns

Workflows are orchestrated patterns where the code controls the flow. The developer defines the structure; the LLM fills in the content.

Pattern	What It Does	Overview	Design	Implementation
Evaluator-Optimizer	Generate-evaluate feedback loop that iteratively improves output.	overview	design	impl
Orchestrator-Worker	LLM decomposes a task and delegates to specialized workers.	overview	design	impl
Parallel Calls	Concurrent LLM calls on independent inputs, aggregated at the end.	overview	design	impl
Prompt Chaining	Sequential LLM calls with validation gates between steps.	overview	design	impl

Agent Patterns

Agents are systems where the LLM controls the flow. The developer provides tools and constraints; the LLM decides what to do.

Pattern	What It Does	Evolves From	Overview	Design	Implementation
Agentic RAG	RAG where the agent plans retrievals, decomposes queries, routes across sources, reflects on sufficiency, and enforces citation-bound answers.	RAG, Plan & Execute	overview	design	impl
Event-Driven	Agents triggered by queue or stream events rather than HTTP requests.	Tool Use	overview	design	impl
Long-Horizon	Multi-session agent tasks that span hours to weeks; checkpoint-and-resume across crashes, deploys, and external waits.	Saga, Event-Driven	overview	design	impl
Multi-Agent	Supervisor-worker delegation across multiple autonomous agents.	Orchestrator-Worker, Routing	overview	design	impl
Plan & Execute	LLM creates a full plan upfront, then executes each step sequentially.	Orchestrator-Worker	overview	design	impl
RAG	Retrieval-augmented generation: retrieve relevant context before generating.	Parallel Calls	overview	design	impl
ReAct	Reason-act loop: the LLM reasons, calls a tool, observes, and repeats until done.	Prompt Chaining	overview	design	impl
Reflection	LLM critiques its own output and self-improves through structured feedback.	Evaluator-Optimizer	overview	design	impl
Routing	Intent classification dispatches inputs to specialized handlers.	Parallel Calls	overview	design	impl
Saga	Long-running, multi-step business processes that need compensation when an intermediate step fails.	Tool Use, Prompt Chaining	overview	design	impl

Primitives

Primitives are building blocks the agent uses orthogonally to any pattern. Picking primitives is the second of three decisions (pattern → primitives → modifiers) when designing an agent.

Pattern	What It Does	Evolves From	Overview	Design	Implementation
Memory	Persistent state across sessions: short-term, long-term, and semantic memory.	Prompt Chaining	overview	design	impl
Skills	File-based, agent-discovered procedural modules. Cheap to ship many; loaded on demand at runtime.	Tool Use	overview	design	impl
Sub-agents	Named, role-scoped agent instances spawned by a parent for delimited tasks; each has its own context window, tool grants, and (optionally) model.	Tool Use	overview	design	impl
Tool Use	Structured function calling with schema-validated tool dispatch.	Prompt Chaining	overview	design	impl

Modifiers

Modifiers wrap a chosen pattern with a transformation (gates, overlays). Picking modifiers is the third decision.

Pattern	What It Does	Evolves From	Overview	Design	Implementation
Guardrails	Layered input / tool / output policy checks plus a dual-LLM split that breaks the indirect-prompt-injection path.	Tool Use	overview	design	impl
Human in the Loop	Agent proposes an action; a human approves, denies, or modifies before the action commits.	Tool Use	overview	design	impl

How Workflows Become Agents

Each agent pattern evolves from a workflow. When a workflow's conditional logic becomes too complex, it's time to let the LLM make those decisions.

graph LR
    PC[Prompt Chaining] -->|"+ dynamic tools"| ReAct[ReAct]
    PC -->|"+ function schemas"| TU[Tool Use]
    PC -->|"+ persistence"| Mem[Memory]
    PAR[Parallel Calls] -->|"+ retrieval"| RAG[RAG]
    PAR -->|"+ classification"| Route[Routing]
    OW[Orchestrator-Worker] -->|"+ planning"| PE["Plan & Execute"]
    OW -->|"+ agent workers"| MA[Multi-Agent]
    Route -->|"+ agent workers"| MA
    EO[Evaluator-Optimizer] -->|"+ self-critique"| Ref[Reflection]
    TU -->|"+ event source"| ED[Event-Driven]
    TU -->|"+ compensation"| Saga[Saga]
    TU -->|"+ approval gate"| HITL[Human in the Loop]

    style PC fill:#e8f5e9
    style PAR fill:#e8f5e9
    style OW fill:#e8f5e9
    style EO fill:#e8f5e9
    style ReAct fill:#fff3e0
    style TU fill:#fff3e0
    style Mem fill:#fff3e0
    style RAG fill:#fff3e0
    style Route fill:#fff3e0
    style PE fill:#fff3e0
    style MA fill:#fff3e0
    style Ref fill:#fff3e0
    style ED fill:#fff3e0
    style Saga fill:#fff3e0
    style HITL fill:#fff3e0

Loading

Each agent pattern includes an evolution.md document that traces this bridge in detail.

Repository Structure

agent-blueprints/
├── foundations/          # Core concepts, terminology, pattern selection
├── patterns/             # 12 flow shapes (8 agent + 4 workflow, distinguished
│                           by the `category` field on each metadata.json)
├── primitives/           # 3 building blocks the agent uses
│                           (tool_use, memory, skills)
├── modifiers/            # 1 transformation layered on a pattern
│                           (human_in_the_loop)
├── composition/          # How patterns + primitives + modifiers combine
├── meta/                 # Contributing, style guide, roadmap
└── code/                 # Reference implementations under
                            patterns/*/code/, primitives/*/code/, modifiers/*/code/

Three-tier taxonomy. Picking an agent shape is three orthogonal decisions: one pattern + N primitives + N modifiers. See foundations/choosing-a-pattern.md for the picker. The machine-readable index is patterns-catalog.yaml (schema v2).

Design Principles

1. Architecture-first — Teach readers to design before they build
2. 3-tier depth — Overview → Design → Implementation. Read only what you need.
3. Pattern + primitives + modifiers — Three orthogonal decisions, not one. Patterns describe flow shape; primitives are building blocks; modifiers are transforms layered on top.
4. Workflows → Agents — Workflows (code-controlled flow) are the foundation; agent patterns (LLM-controlled flow) build on them. Both live in patterns/ distinguished by category.
5. Generalized, not use-case-bound — Patterns are abstract and composable.
6. Framework-agnostic — No provider lock-in. The LLM is a swappable layer.

Contributing

See the Contributing Guide and Style Guide.

Roadmap

This is Phase 1 (documentation). Code implementations, advanced patterns, and tooling are planned for future phases. See the full roadmap.

License

Released under the MIT License. Copyright (c) 2026 Jagadesh Varma Nadimpalli.