Skip to content

Why Blueprint?

Most multi-agent frameworks make you choose your runtime before you design your system: a LangGraph StateGraph, a CrewAI Crew, an AutoGen conversation. The orchestration logic and the execution engine are the same lines of Python — which means every migration, every framework evaluation, and every "let's also support X" request means rewriting the system from scratch.

pyagent-blueprint separates the two. You declare what your system does — agents, workflows, providers, contracts, governance — in a single YAML manifest. A RuntimeAdapter decides how it runs. The same manifest compiles against five structurally different adapters today, unmodified.

How this relates to the homepage comparison

The homepage compares PyAgent's overall feature set against LangChain, CrewAI, and AutoGen (pattern count, routing, memory, and more). This page and the pages under it go one layer deeper on a single, specific claim from that table — the YAML-vs-code tradeoff and cross-runtime portability — with real adapter code, not just a feature checklist.

The same manifest, five runtimes

pyagent-blueprint's RuntimeAdapter layer compiles one YAML manifest against five structurally different execution engines unmodified — a real blueprint example, the adapter-selection API, and the full conformance table (native, LangGraph, CrewAI, OpenAI Agents, Semantic Kernel) now live on their own page: Adapters.

What you get that hand-written orchestration code doesn't

  • Diff and review like infrastructure. pyagent-blueprint diff old.yaml new.yaml produces a semantic diff over the IR — not a text diff of hand-wired Python — so a PR reviewer can see exactly which agent, route, or SLA changed.
  • Validate before you run anything. Static analysis (dangling references, schema violations) catches mistakes before an LLM call is ever made.
  • Governance is never silently dropped. Budgets, SLAs, memory tiers, guardrails, recovery policies, and human-in-the-loop checkpoints are either honored by the adapter or surfaced as a stable CompileDiagnostic code (e.g. BUDGET_UNSUPPORTED, MEMORY_TIER_UNSUPPORTED, CHECKPOINT_UNSUPPORTED) — so you always know, deterministically, what a given runtime supports.
  • Package and test without live API calls. pyagent-blueprint test (contract conformance) and pyagent-blueprint package (Agent Unit archives) both work against a MockLLM, so CI can validate a system's shape before spending a token.
  • Zero mandatory runtime dependency. Core pyagent-blueprint depends only on pydantic, pyyaml, and click. You install a runtime adapter — the bundled pyagent reference stack, one of four zero-dependency stdlib adapters, or a third-party package — only when you're ready to run.

When you don't need PyAgent at all

Be direct about this before anything else: if your task is a single LLM call — summarize this document, classify this tweet, answer this question — you don't need an orchestration framework, a pattern, or a blueprint. Import your provider's SDK, make the call, done. Reaching for pyagent-patterns or pyagent-blueprint here adds a dependency and a mental model for zero benefit; there's no second agent to hand off to, no state to share, no run to observe across calls. The same applies to a one-off script that calls a model in a loop with no persistence between calls — a for loop is the right tool, not a Pipeline or Supervisor pattern.

The signal to actually reach for PyAgent is more than one agent, or state that needs to survive across calls — routing between specialists, a review loop, a shared memory tier, a run you need to trace. Below that threshold, every pillar here is overhead, not architecture.

When a blueprint isn't the right fit

To be direct about the tradeoff: if your orchestration logic depends on dynamic, runtime-computed control flow that can't be expressed as a static graph (e.g. an agent that decides to spin up an arbitrary number of sub-agents based on a live computation), hand-written code in your chosen framework is still the right tool. Blueprint's IR models agents, typed workflows, and named patterns — it's declarative by design, and that's a real constraint, not just a feature.

See the pattern-specific comparisons for how this plays out against real frameworks:

Or start from the concepts: What is an agent blueprint? and What is multi-agent orchestration?