What is an agent blueprint?

An agent blueprint is a declarative document — YAML or JSON — that fully describes a multi-agent system: which agents exist, how they're wired into named orchestration patterns, which LLM providers back them, what contracts (input/output shape, SLAs) they must satisfy, and what governance (budgets, memory tiers, guardrails, recovery, human-in-the-loop checkpoints) applies. It's a manifest, not a script — the system's shape is data, not control flow buried in Python.

The anatomy of a blueprint

api_version: pyagent/v1
metadata:
  name: customer-support
  version: 1.0.0
  owner: platform-team

providers:                 # LLM bindings — model, tokens, timeout
  primary:
    model: gpt-4.1-mini
  fallback:
    model: gpt-4.1-nano

agents:                    # Agent definitions — prompt, provider, guardrails
  classifier:
    prompt: "Classify into: billing, tech, general"
    provider: primary
  billing:
    prompt: "Handle billing inquiries"
    provider: primary
    guardrails: [pii_redact]

workflows:                  # Named-pattern wiring + recovery policy
  support:
    pattern: supervisor
    agents:
      classifier: classifier
      routes: {billing: billing}
    recovery:
      max_retries: 2
      fallback_provider: fallback

contracts:                  # Input/output schema + SLA
  support:
    input: {type: string, max_tokens: 2000}
    output: {type: string}
    sla: {latency_p95_ms: 5000, cost_max_usd: 0.05}

observability:              # Tracing + cost budgets
  tracing: {enabled: true}
  cost_budget: {daily_usd: 100.0}

Every top-level block maps onto a real, compilable capability, not just documentation: providers feeds pyagent-router's routing; agents/workflows compile to a RuntimeAdapter's CompiledArtifact; contracts become validated I/O + SLA checks; observability wires pyagent-trace.

Why a manifest instead of code

A hand-written orchestration script conflates design (which agents, wired how) with implementation (which SDK, which execution loop). A blueprint separates them:

• Version and diff it like infrastructure. pyagent-blueprint diff v1.yaml v2.yaml shows exactly which agent, route, or SLA changed — a real code review artifact, not a prose changelog.
• Validate before running anything. Static analysis catches dangling agent references or schema violations before an LLM call happens.
• Compile it onto any registered runtime. The same manifest runs on the bundled pyagent pattern registry, a zero-dependency stdlib adapter, or a third-party adapter for LangGraph, CrewAI, Semantic Kernel, or the OpenAI Agents SDK — see Why Blueprint? for the full proof.
• Simulate without spending tokens. pyagent-blueprint simulate runs the compiled graph against a MockLLM, so CI can validate a system's shape and contract conformance for free.
• Never silently drop governance. Every declared budget, memory tier, guardrail, recovery policy, or HITL checkpoint is either honored by the target adapter or surfaced as a stable diagnostic code (e.g. BUDGET_UNSUPPORTED) — you always know what a runtime actually supports.

Where a blueprint fits in the stack

A blueprint is Pillar 1 of PyAgent's four-pillar production stack — Manifest, Execution & Routing, Context & Memory, and Observability. See the Blueprint guide for the full spec format, or What is multi-agent orchestration? for the coordination patterns a blueprint's workflows: block declares.