agent-scaffold-cli 0.1.1__py3-none-any.whl

agent_scaffold/_bundled_deployments/docs/patterns/multi-agent-hierarchical.md

@@ -0,0 +1,83 @@
+# Pattern: Multi-Agent Hierarchical (Supervisor + Workers)
+
+**One-liner:** A supervisor agent delegates sub-tasks to specialized worker agents, coordinates their outputs, and decides when the job is done.
+
+## When to use
+
+- The task is complex and decomposes into sub-tasks that require different specializations.
+- You need centralized coordination — someone to decide what happens next based on intermediate results.
+- Sub-agents may need to be called multiple times or in different orders depending on results.
+- You want a clear chain of command for audit and debugging purposes.
+
+## When NOT to use
+
+- The task doesn't require multiple specializations (use a single agent with tools).
+- All sub-tasks are independent with no coordination needed (use Parallel Calls or Flat Multi-Agent).
+- The number of sub-agents is small (2) and the interaction is simple (just use Routing).
+
+## Core flow
+
+```
+User task
+    |
+    v
+  [Supervisor] ──> "I need Agent A to do X first"
+    |
+    v
+  [Agent A: Researcher] ──> results
+    |
+    v
+  [Supervisor] ──> "Now I need Agent B to do Y with A's results"
+    |
+    v
+  [Agent B: Writer] ──> draft
+    |
+    v
+  [Supervisor] ──> "Agent C should review this"
+    |
+    v
+  [Agent C: Reviewer] ──> feedback
+    |
+    v
+  [Supervisor] ──> "Done" or "Agent B, revise based on feedback"
+    |
+    v
+  Final output
+```
+
+### Variants
+
+- **Single-level hierarchy:** One supervisor, N workers. Most common.
+- **Multi-level hierarchy:** Supervisor → sub-supervisors → workers. For very complex tasks.
+- **Supervisor with self-delegation:** The supervisor can also do work itself, not just delegate.
+- **Dynamic team:** The supervisor can spawn new workers as needed based on the task.
+
+## Key components
+
+- **Supervisor agent:** The orchestrator. Decides which worker to call, with what input, and when to stop. Has access to all worker agent descriptions but not their tools directly.
+- **Worker agents:** Specialized agents with their own system prompts and tools. Each handles one domain.
+- **Delegation protocol:** How the supervisor invokes workers — typically as tool calls where each worker is a "tool" the supervisor can call.
+- **State manager:** Tracks what's been done, what's pending, and intermediate results. LangGraph's state graph is ideal.
+- **Termination logic:** The supervisor decides when the task is complete. Can be explicit ("all sub-tasks done") or LLM-judged.
+
+## Common pitfalls
+
+- **Supervisor bottleneck:** Every interaction goes through the supervisor, adding latency. For independent sub-tasks, let workers run in parallel.
+- **Over-delegation:** The supervisor breaks the task into too many tiny sub-tasks. Give it examples of good delegation granularity.
+- **Lost context:** Each worker only sees its sub-task, not the full picture. The supervisor must provide enough context in each delegation.
+- **Supervisor hallucination:** The supervisor claims a worker returned results it didn't. Validate worker outputs in state.
+- **Worker scope creep:** A worker tries to do work outside its specialty. Keep worker system prompts narrowly focused.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| LangGraph | `langgraph-supervisor` package — purpose-built supervisor pattern | Best fit — each worker is a compiled sub-graph |
+| CrewAI | Hierarchical process mode with `manager_agent` | Built-in but less flexible than LangGraph |
+| Mastra | Agent workflows with delegation | TS-native, manual but flexible |
+| Pydantic AI | Manual orchestration — supervisor agent with workers as tools | Works but you build the coordination |
+| Vercel AI SDK | Manual orchestration | No built-in hierarchy |
+
+## Reference implementations
+
+- [recipes/hierarchical-agent.md](../recipes/hierarchical-agent.md) — Hierarchical multi-agent with LangGraph supervisor (skeleton)

agent_scaffold/_bundled_deployments/docs/patterns/parallel-calls.md

@@ -0,0 +1,73 @@
+# Pattern: Parallel Calls (Fan-out / Fan-in)
+
+**One-liner:** Run multiple independent LLM calls or tool invocations concurrently, then aggregate their results.
+
+## When to use
+
+- You have N independent sub-tasks that don't depend on each other (e.g., enrich N records, summarize N documents).
+- Latency matters — sequential execution of N tasks takes N× as long.
+- Each sub-task uses the same prompt/tool with different inputs (batch processing pattern).
+- You need to aggregate or merge results after all sub-tasks complete.
+
+## When NOT to use
+
+- Sub-tasks depend on each other's outputs (use Prompt Chaining).
+- N is very large (100+) and you'd hit rate limits. Add concurrency controls.
+- The sub-tasks need to coordinate or share state mid-execution (use Multi-Agent).
+
+## Core flow
+
+```
+Input (list of items)
+    |
+    v
+  [Fan-out] ──> spawn N concurrent tasks
+    |
+    ├──> [Task 1: process item A] ──┐
+    ├──> [Task 2: process item B] ──┤
+    ├──> [Task 3: process item C] ──┤
+    └──> [Task N: process item N] ──┘
+                                    |
+                                    v
+                              [Fan-in / Aggregate]
+                                    |
+                                    v
+                              Combined result
+```
+
+### Variants
+
+- **Homogeneous fan-out:** All tasks use the same prompt/tool, different inputs. Classic batch processing.
+- **Heterogeneous fan-out:** Different tasks run different prompts/tools in parallel (e.g., summarize + extract entities + classify sentiment simultaneously on the same document).
+- **Fan-out with partial failure:** Some tasks may fail. Collect successes, report failures, optionally retry.
+- **Chunked fan-out:** For large N, split into batches with concurrency limits (e.g., 10 at a time).
+
+## Key components
+
+- **Splitter:** Divides the input into independent work units.
+- **Worker:** The LLM call or tool invocation applied to each unit. Should be stateless and idempotent.
+- **Concurrency controller:** Limits how many workers run simultaneously. Prevents rate-limit exhaustion. In Python: `asyncio.Semaphore`. In TS: `Promise.all()` with chunking.
+- **Aggregator:** Merges individual results into a combined output. May be a simple list, a summary, or a structured merge.
+- **Error handler:** Decides what to do when individual tasks fail (skip, retry, abort all).
+
+## Common pitfalls
+
+- **No concurrency limit:** Firing 100 parallel LLM calls will hit rate limits. Use a semaphore or batch size.
+- **One failure kills all:** If using `Promise.all()` or `asyncio.gather()` without error handling, one failure cancels everything. Use `Promise.allSettled()` / `return_exceptions=True`.
+- **Results out of order:** Parallel results may return in any order. Preserve input-output mapping (index or ID).
+- **Context window limits:** If the aggregator tries to merge too many results into one prompt, it may exceed the context window. Summarize incrementally.
+- **Cost multiplication:** N parallel calls = N× the cost of one call. Make sure parallelism is worth it vs. a single batched prompt.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| Pydantic AI | `asyncio.gather()` with multiple `agent.run()` calls | Natural — async-first, clean ergonomics |
+| Mastra | `Promise.all()` with agent calls, or workflow parallel steps | TS-native async |
+| LangGraph | `Send()` API for map-reduce fan-out | Works but heavier than raw async |
+| Vercel AI SDK | `Promise.all()` with `generateText()` calls | Simple and effective |
+| CrewAI | Parallel task execution in a crew | Built-in but less control over concurrency |
+
+## Reference implementations
+
+- [recipes/parallel-enricher.md](../recipes/parallel-enricher.md) — Parallel batch enrichment with Pydantic AI / Mastra (skeleton)

agent_scaffold/_bundled_deployments/docs/patterns/plan-execute-reflect.md

@@ -0,0 +1,77 @@
+# Pattern: Plan, Execute, Reflect
+
+**One-liner:** The agent creates a plan of steps, executes them one by one, then reflects on results to decide if re-planning is needed.
+
+## When to use
+
+- The task is complex enough that jumping straight to execution would miss steps or go off track.
+- You want the agent to be self-correcting — detecting when a step failed and adapting.
+- The task has a verifiable goal (code review: "all issues found"; research: "question answered").
+- You need an auditable trace: plan → what was done → what was learned → revised plan.
+
+## When NOT to use
+
+- The task is simple enough for a single LLM call or a fixed pipeline (use Prompt Chaining).
+- There's no way to evaluate whether a step succeeded (reflection has nothing to work with).
+- Latency is critical — the plan/reflect overhead adds 2+ extra LLM calls per cycle.
+
+## Core flow
+
+```
+User task
+    |
+    v
+  [Planner] ──> step list (ordered, with dependencies)
+    |
+    v
+  [Executor] ──> execute step 1 ──> result
+    |                    |
+    |                    v
+    |             [Reflector] ──> "step succeeded" / "step failed, because..."
+    |                    |
+    |         ┌──────────┴──────────┐
+    |         v                     v
+    |    continue to             [Re-planner] ──> revised steps
+    |    step 2                     |
+    |         |                     v
+    |         └─────────────────> next step
+    |                    ...
+    v
+  Final output (after all steps pass reflection)
+```
+
+### Variants
+
+- **Plan-Execute (no reflection):** Simpler version — plan once, execute all steps, return results. Good when steps are unlikely to fail.
+- **Plan-Execute-Reflect:** Full version with a reflection step after each execution. Re-plans if reflection identifies problems.
+- **Iterative deepening:** Start with a coarse plan, execute, reflect, then create more detailed sub-plans for steps that need it.
+
+## Key components
+
+- **Planner:** An LLM call that takes the task description and produces a structured step list. Each step has: description, expected output, success criteria.
+- **Executor:** Runs one step at a time. May use tools (search, code execution, API calls) to complete each step.
+- **Reflector:** Evaluates the executor's output against the step's success criteria. Returns pass/fail + reasoning.
+- **Re-planner:** If reflection fails, takes the original plan + what happened + what went wrong, and produces a revised plan.
+- **State store:** Holds the plan, completed steps, and their results. LangGraph's checkpointer is ideal for this.
+
+## Common pitfalls
+
+- **Over-planning:** The planner produces 15 steps for a task that needs 3. Constrain the planner with max steps or examples of good plans.
+- **Reflection hallucination:** The reflector says "looks good" when the step clearly failed. Use concrete success criteria, not vibes.
+- **Infinite re-planning:** Reflection keeps failing, re-planner keeps generating new plans. Set a max replanning budget (2-3 attempts).
+- **Executor can't do the step:** The planner writes steps that require capabilities the executor doesn't have. Ground the planner in available tools.
+- **State explosion:** Each cycle adds to state. Summarize completed steps rather than carrying full outputs.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| LangGraph | Planner, Executor, Reflector as graph nodes with conditional edges for re-planning | Best fit — state management handles plan evolution |
+| Pydantic AI | Separate agents for planner/executor/reflector, manual orchestration | Works but you manage state yourself |
+| Mastra | Workflow steps for plan/execute/reflect cycle | TS-native, workflow primitives help |
+| CrewAI | Sequential crew with planner + executor agents | Possible but less control over reflection loop |
+| Vercel AI SDK | Manual orchestration with `generateObject()` / `generateText()` | Lightweight but no built-in state management |
+
+## Reference implementations
+
+- [recipes/code-review-agent.md](../recipes/code-review-agent.md) — Plan-and-Execute code reviewer with LangGraph (skeleton)

agent_scaffold/_bundled_deployments/docs/patterns/prompt-chaining.md

@@ -0,0 +1,73 @@
+# Pattern: Prompt Chaining
+
+**One-liner:** Break a complex task into a fixed sequence of LLM calls where each step's output feeds the next step's input.
+
+## When to use
+
+- The task naturally decomposes into ordered stages (e.g., research → outline → draft → edit).
+- Each stage has a clear input/output contract.
+- You want deterministic flow — every request follows the same pipeline.
+- Quality benefits from specialized prompts per stage rather than one monolithic prompt.
+
+## When NOT to use
+
+- The sequence of steps isn't known upfront (use ReAct).
+- Steps need to run in parallel, not sequentially (use Parallel Calls).
+- The agent needs to decide whether to skip or repeat steps (use Plan-and-Execute).
+
+## Core flow
+
+```
+Input
+  |
+  v
+[Stage 1: Research] ──> research notes
+  |
+  v
+[Stage 2: Outline] ──> structured outline
+  |
+  v
+[Stage 3: Draft] ──> full draft
+  |
+  v
+[Stage 4: Edit] ──> polished output
+  |
+  v
+Final output
+```
+
+### Variants
+
+- **Linear chain:** A → B → C → D. Simplest form.
+- **Chain with validation gates:** After each stage, validate the output (schema check, quality check). Retry or fail early if validation fails.
+- **Chain with accumulation:** Each stage receives not just the previous output, but all prior outputs (snowball context).
+- **Chain with human-in-the-loop:** Pause between stages for human review/approval before continuing.
+
+## Key components
+
+- **Stage:** A single LLM call with a focused system prompt. Each stage is a pure function: input → output.
+- **Schema:** Structured output types (Pydantic models / Zod schemas) that define the contract between stages. Type safety prevents silent failures.
+- **Pipeline orchestrator:** Runs stages in order, passing outputs forward. Can be as simple as sequential `await` calls.
+- **Validation gate (optional):** Checks stage output before passing it to the next stage. Can retry, modify, or abort.
+
+## Common pitfalls
+
+- **Context bloat:** If you pass all prior stage outputs to every stage, context grows linearly. Only pass what each stage needs.
+- **Error propagation:** A bad output from stage 1 cascades through all subsequent stages. Add validation gates at critical points.
+- **Prompt coupling:** If stage 2's prompt assumes a specific format from stage 1, changing stage 1 breaks stage 2. Use explicit schemas.
+- **Unnecessary chaining:** If one good prompt can do the job, don't split it into 3 stages. More stages = more latency + cost.
+- **No partial results:** If the pipeline fails at stage 3, you lose stages 1-2 unless you persist intermediate outputs.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| Pydantic AI | Sequential `agent.run()` calls with typed `result_type` per stage | Natural fit — type safety between stages |
+| Vercel AI SDK | `generateObject()` per stage, pipe outputs manually | Clean TS implementation |
+| LangGraph | Linear graph with one node per stage | Works but overkill for simple chains |
+| Mastra | Sequential agent calls or workflow steps | Mastra workflows support chaining natively |
+| CrewAI | Sequential task execution in a crew | Works but heavy for a simple pipeline |
+
+## Reference implementations
+
+- [recipes/content-pipeline.md](../recipes/content-pipeline.md) — Multi-stage content generation pipeline (Pydantic AI / Vercel AI SDK, skeleton)

agent_scaffold/_bundled_deployments/docs/patterns/rag.md

@@ -0,0 +1,84 @@
+# Pattern: RAG (Retrieval-Augmented Generation)
+
+**One-liner:** Ground LLM answers in retrieved documents so the model answers from your data, not its training set.
+
+## When to use
+
+- User asks questions that should be answered from a specific corpus (docs, KB articles, policies).
+- You need citations or source attribution in answers.
+- The knowledge base changes over time and can't be baked into prompts.
+- You want to reduce hallucination by constraining the model to retrieved context.
+
+## When NOT to use
+
+- The answer space is small enough to fit in the system prompt (use direct prompting).
+- You need the agent to take *actions*, not just answer questions (use ReAct or Routing).
+- The corpus is unstructured and doesn't chunk well (consider summarization pipelines first).
+
+## Core flow
+
+```
+User question
+    |
+    v
+  [Embed query] ──> [Vector search] ──> top-K chunks
+    |                                        |
+    v                                        v
+  [Build prompt]  <──────────────────  [Retrieved context]
+    |
+    v
+  [LLM generates answer grounded in context]
+    |
+    v
+  Answer + citations
+```
+
+### Variants
+
+- **Naive RAG:** Embed > retrieve > generate. Simple, works for most cases.
+- **RAG + reranker:** Add a cross-encoder reranker after retrieval to improve precision.
+- **Agentic RAG:** The LLM decides *when* and *what* to retrieve (retrieval as a tool call). This is what the `docs-rag-qa` prototype implements.
+- **Multi-step RAG:** Decompose complex questions, retrieve per sub-question, synthesize.
+
+## Key components
+
+- **Chunker:** Splits documents into retrieval-sized pieces. Sentence-boundary splitting with overlap is the baseline. Typical chunk size: 300-800 characters.
+- **Embedder:** Converts text to vectors. In this repo, Qdrant handles storage; embedding is done by the Qdrant client or a dedicated model.
+- **Retriever:** Searches the vector store for chunks similar to the query. Returns top-K with relevance scores.
+- **Generator:** The LLM that synthesizes an answer from the retrieved chunks. Gets the chunks injected into its prompt or via tool call results.
+- **Citation extractor:** Maps answer spans back to source documents for attribution.
+
+## Common pitfalls
+
+- **Chunks too large:** The model ignores the middle of long contexts. Keep chunks focused.
+- **Chunks too small:** Loss of surrounding context makes chunks meaningless. Use overlap.
+- **No relevance threshold:** Returning irrelevant chunks harms answer quality. Filter by score.
+- **Stuffing all chunks into one prompt:** With many results, use map-reduce or iterative refinement instead.
+- **Ignoring metadata:** Filtering by document type, date, or source before vector search dramatically improves precision.
+- **Not evaluating retrieval separately:** Measure retrieval recall/precision independently from generation quality. RAGAS is purpose-built for this.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| LangGraph | Built-in retriever nodes, checkpointing for multi-step RAG | Best for complex RAG with state management |
+| Pydantic AI | Tool-based retrieval, type-safe citation schemas | Clean DX for simple agentic RAG |
+| Mastra | Built-in RAG primitives, vector store integrations | TS-native, batteries included |
+| Vercel AI SDK | Tool-based retrieval via `tool()` | Lightweight, good for simple RAG |
+| CrewAI | Possible but not idiomatic | Better suited for multi-agent patterns |
+
+## Evaluation metrics
+
+RAG has dedicated metrics beyond general agent eval:
+
+| Metric | What it measures | Tool |
+|--------|-----------------|------|
+| Context recall | Did retrieval find the right chunks? | RAGAS |
+| Context precision | Are retrieved chunks relevant (not noise)? | RAGAS |
+| Faithfulness | Is the answer grounded in retrieved context (not hallucinated)? | RAGAS |
+| Answer relevancy | Does the answer address the question? | RAGAS / DeepEval |
+| Answer correctness | Is the answer factually correct vs. gold standard? | DeepEval |
+
+## Reference implementations
+
+- [recipes/docs-rag-qa.md](../recipes/docs-rag-qa.md) -- Agentic RAG with Pydantic AI (Py) and Vercel AI SDK (TS)

agent_scaffold/_bundled_deployments/docs/patterns/react.md

@@ -0,0 +1,77 @@
+# Pattern: ReAct (Reason + Act)
+
+**One-liner:** The agent iterates through a think → act → observe loop, choosing tools at each step until it can answer.
+
+## When to use
+
+- The task requires multi-step reasoning with external information (search, APIs, databases).
+- You can't predict upfront which tools the agent will need or in what order.
+- The agent needs to adapt its strategy based on intermediate results.
+- You want an auditable trace of the agent's reasoning at each step.
+
+## When NOT to use
+
+- The task is a single classification or generation (no tools needed — just prompt).
+- The workflow is a fixed sequence of steps (use Prompt Chaining instead).
+- You need guaranteed execution order or deterministic outputs (ReAct is inherently non-deterministic).
+- Latency budget is tight — each loop iteration is an LLM call.
+
+## Core flow
+
+```
+User question
+    |
+    v
+  [Reason] ──> "I need to search for X"
+    |
+    v
+  [Act] ──> call tool(search, query="X")
+    |
+    v
+  [Observe] ──> tool returns results
+    |
+    v
+  [Reason] ──> "Now I need to look up Y"
+    |            ... (loop until done)
+    v
+  [Final Answer]
+```
+
+### Loop termination
+
+The LLM decides when it has enough information to answer. Most frameworks enforce a `max_steps` limit to prevent runaway loops. In this repo, the default is 5 steps.
+
+### Variants
+
+- **Vanilla ReAct:** Single agent, flat tool list. The most common variant.
+- **ReAct + reflection:** After each observation, a separate prompt critiques whether the approach is working.
+- **ReAct + planning:** The agent first writes a brief plan, then executes via ReAct. Hybrid with Plan-and-Execute.
+
+## Key components
+
+- **Reasoner:** The LLM generating thoughts about what to do next. The system prompt defines its persona and available tools.
+- **Tool executor:** Runs the chosen tool and returns results. In Pydantic AI, tools are decorated functions. In LangGraph, `ToolNode` handles this.
+- **Observation parser:** Feeds tool results back into the next reasoning step as context.
+- **Step limiter:** Prevents infinite loops. Configurable via `max_steps` or equivalent.
+
+## Common pitfalls
+
+- **Tool description quality:** Vague tool descriptions cause the agent to pick wrong tools. Be precise about what each tool does, its inputs, and output format.
+- **Too many tools:** More than ~10 tools degrades selection accuracy. Group related tools or use a routing layer.
+- **No step limit:** Without `max_steps`, the agent can loop indefinitely on hard questions. Always set a cap.
+- **Expensive tool calls in loops:** If a tool hits a paid API, each loop iteration costs money. Consider caching or rate-limiting tool calls.
+- **Hallucinated tool names:** The agent may try to call tools that don't exist. Ensure your framework validates tool names before execution.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| LangGraph | `create_react_agent()` — purpose-built | Canonical implementation with full state management |
+| Pydantic AI | `Agent` with `@tool` decorators — built-in loop | Clean DX, auto-manages the reason/act/observe cycle |
+| Mastra | `Agent` with `tools` array — built-in loop | TS-native, similar ergonomics to Pydantic AI |
+| Vercel AI SDK | `generateText()` with `tools` + `maxSteps` | Lightweight, good for simple ReAct |
+| CrewAI | Agent with tools — uses ReAct internally | Works but less control over the loop |
+
+## Reference implementations
+
+- [recipes/research-assistant.md](../recipes/research-assistant.md) — ReAct research agent with web search (Pydantic AI / Mastra)

agent_scaffold/_bundled_deployments/docs/patterns/routing-tool-use.md

@@ -0,0 +1,69 @@
+# Pattern: Routing + Tool Use
+
+**One-liner:** Classify the user's intent, then route to a specialized handler (agent or tool) for that intent.
+
+## When to use
+
+- Incoming requests fall into distinct categories with different handling logic (e.g., billing vs. technical support).
+- You want to use a cheap/fast model for classification and a capable model for handling.
+- Each category needs different tools, system prompts, or guardrails.
+- You need clear audit trails showing why a request was routed a specific way.
+
+## When NOT to use
+
+- There's only one type of request (just use a single agent with tools).
+- The categories overlap heavily and routing would be wrong half the time.
+- The task requires multi-step reasoning across categories (use ReAct or Multi-Agent).
+
+## Core flow
+
+```
+User message
+    |
+    v
+  [Classifier] ──> intent + confidence
+    |
+    ├── billing ──> [Billing Specialist] ──> (Stripe tool)
+    ├── technical ──> [Technical Specialist] ──> (KB search tool)
+    ├── account ──> [Account Specialist] ──> (KB search tool)
+    └── general ──> [General Specialist] ──> (no tools)
+    |
+    v
+  Response
+```
+
+### Variants
+
+- **Single-hop routing:** Classify once, route once. Simple and fast.
+- **Cascading routers:** First router picks a domain, second router picks a sub-category within that domain.
+- **Confidence-gated routing:** If classifier confidence is below threshold, fall back to a general handler or ask for clarification.
+- **Tool-only routing:** Instead of separate agents, the classifier picks which tool to invoke. Lighter-weight.
+
+## Key components
+
+- **Classifier:** An LLM (often smaller/cheaper) that maps input to an intent. Returns structured output: intent enum + confidence score + reasoning.
+- **Specialist agents:** One per intent category, each with its own system prompt and tool set. Specialists are isolated — a billing agent can't accidentally call the KB search tool.
+- **Router:** Dispatches to the correct specialist based on classification. In code, this is typically a match/switch on the intent enum.
+- **Fallback handler:** Catches low-confidence classifications or unknown intents.
+
+## Common pitfalls
+
+- **Overlapping intents:** "I can't log in to pay my bill" is both account and billing. Define clear boundaries or allow multi-label classification with priority.
+- **Classifier drift:** As your product changes, new intents emerge. Monitor classification accuracy and retrain/update prompts.
+- **Over-routing:** Too many intent categories makes classification unreliable. Start with 3-5 categories.
+- **Missing fallback:** Without a fallback, unclassifiable messages get random routing. Always have a general handler.
+- **Specialist without tools:** If a specialist can't actually do anything (no tools, no data access), it's just a differently-prompted chatbot. Make sure specialists have real capabilities.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| Pydantic AI | `result_type=ClassificationResult` for structured classification, separate `Agent` per specialist | Natural fit — typed outputs + tool isolation |
+| LangGraph | Conditional edges from classifier node to specialist nodes | Works well but verbose for simple routing |
+| Mastra | Agent with `tools` per specialist, manual routing | Clean, no extra abstraction needed |
+| Vercel AI SDK | `generateObject()` for classification, `generateText()` per specialist | Lightweight TS option |
+| CrewAI | Not idiomatic — CrewAI is designed for collaboration, not routing | Use a different framework |
+
+## Reference implementations
+
+- [recipes/customer-support-triage.md](../recipes/customer-support-triage.md) — Intent classification → specialist routing (Pydantic AI / Mastra)

agent_scaffold/_bundled_deployments/docs/recipes/README.md

@@ -0,0 +1,39 @@
+# Recipes
+
+Full-spec agent blueprints showing how patterns, frameworks, and stack compose into real agents. Each file answers: **"Give me everything I need to build this agent."**
+
+## Validated (with reference implementation)
+
+| Recipe | Pattern | Framework (Py / TS) | Status |
+|--------|---------|---------------------|--------|
+| [Customer Support Triage](customer-support-triage.md) | Routing + Tool Use | Pydantic AI / Vercel AI SDK | Blueprint (validated) |
+| [Docs RAG QA](docs-rag-qa.md) | RAG | Pydantic AI / Vercel AI SDK | Blueprint (validated) |
+| [Research Assistant](research-assistant.md) | ReAct | Pydantic AI / Vercel AI SDK | Blueprint (validated) |
+
+## Design spec
+
+| Recipe | Pattern | Framework (Py / TS) | Status |
+|--------|---------|---------------------|--------|
+| [Content Pipeline](content-pipeline.md) | Prompt Chaining | Pydantic AI / Vercel AI SDK | Blueprint (design spec) |
+| [Code Review Agent](code-review-agent.md) | Plan-Execute-Reflect | LangGraph / Vercel AI SDK | Blueprint (design spec) |
+| [Ops Crew](ops-crew.md) | Multi-Agent Flat | CrewAI / Vercel AI SDK | Blueprint (design spec) |
+| [Parallel Enricher](parallel-enricher.md) | Parallel Calls | Pydantic AI / Vercel AI SDK | Blueprint (design spec) |
+| [Memory Assistant](memory-assistant.md) | Memory | LangGraph / Vercel AI SDK | Blueprint (design spec) |
+| [Hierarchical Agent](hierarchical-agent.md) | Multi-Agent Hierarchical | LangGraph / Vercel AI SDK | Blueprint (design spec) |
+
+## How to read a blueprint
+
+Each blueprint includes 13 sections:
+1. **What it composes** — links to the pattern, framework, stack, and cross-cutting docs
+2. **Architecture** — diagram of the agent's structure
+3. **Data Models** — full Pydantic + Zod schemas
+4. **API Contract** — every endpoint with request/response JSON
+5. **Tool Specifications** — each tool with parameters and examples
+6. **Prompt Specifications** — actual system prompts with design rationale
+7. **Key files** — file-by-file implementation spec (Python + TypeScript)
+8. **Implementation Roadmap** — ordered build steps
+9. **Environment & Deployment** — env vars table, Docker reference
+10. **Test Strategy** — example tests per tier
+11. **Eval Dataset** — inline golden examples
+12. **Design Decisions** — trade-offs and rationale
+13. **Reference Implementation** — full source code (validated blueprints only)