> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sketricgen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Best practices for building multi-agent workflows in SketricGen — control flow, handoff design, structured I/O, tool usage, and orchestration patterns.

Build your AgentSpace like a team: a **Manager/Triage** agent receives the message first, decides what’s needed, and **passes control** to the right specialist. Your job is to make control flow **predictable** with clear instructions and tool usage notes.

## Control flow: who’s in charge?

* **Handoffs transfer control**: when Agent A hands off to Agent B, **B owns the run** until it’s done (or hands off again). The final answer normally comes from the **last agent** that handled the message.
* **Agent as Tool returns control**: use this for bounded sub-tasks; the callee runs, returns a result, and control goes **back to the caller**. Great for reusable utilities (classify, extract, redact).
* **Routing is AI-decided**: agents choose when to hand off based on **instructions + input** (not hard-coded paths). Keep your instructions explicit about *when* to call which tool/agent.
* **Forced handoffs for guaranteed paths**: when you need deterministic execution (e.g., compliance pipelines or sequential processing), use **forced handoffs** to ensure Agent B always runs after Agent A — regardless of AI judgment.

## Write crisp instructions

* Give **role**, **goal**, **success criteria**, and **when to hand off**.
* Break work into **clear steps**; call out **required fields** before tools/hand-offs.
* Borrow existing SOPs/policies to reduce ambiguity.

## Structure where it matters

* Prefer **Structured Inputs** for child agents (so the parent knows exactly what fields to supply before a handoff).
* Use **Structured Outputs** primarily on **ending agents** (so user-facing or API consumers get consistent JSON).
* Avoid forcing intermediate agents to emit final JSON unless they’re the responder. They will always return JSON output and this is not very human/customer friendly.
* **Tip:** Structured Outputs is powerful for Agents as Tools!

## Tooling principles

* Map only the fields you need; set retries/fallbacks for flaky endpoints; redact sensitive params in traces.
* Use **File Search** with curated sources or the crawler; add **Web Search** when freshness matters.
* Keep repeatable logic in **Agent as Tool** to shorten paths and improve latency.

## Orchestration patterns to start with

* **Manager → Specialist**: triage decides, then hands off to a single expert agent.
* **Manager → (Agent-as-Tool utilities) → Specialist**: small helpers (classify/extract) as tools, then a full handoff.
* **Manager → Researcher → Writer**: research pulls context; writer composes the final answer.
  Begin simple (one or two specialists), then scale the team as the workload grows.

## Iterate fast (the core loop)

**Edit → Test → Observe → Improve** in one UI: update instructions/tool notes, run a test, open **Trace Explorer** (steps, tool I/O, durations, credits), then refine. Save **snapshots** and compare **diffs** to prevent regressions.

## Protocols you benefit from

* **MCP (Model Context Protocol)**: a standard “USB-C for AI” to connect models to tools and data safely and consistently. Use MCP servers for clean, reusable capabilities.
* **A2A (Agent-to-Agent)**: emerging standard for interop between agents across systems—useful when your flows span other vendors or services.

## Common mistakes (and fixes)

1. **Misunderstanding control flow**
   * *Mistake*: Parent calls multiple children assuming they all reply; or expecting a child to “call back” without an explicit handoff.
   * *Fix*: Remember: **handoff transfers control**; add an explicit **handoff back** if needed. Otherwise use **Agent as Tool** to keep control with the parent.
2. **Structured output in the wrong place**
   * *Mistake*: Forcing JSON at intermediate layers then accidentally replying to the user with that JSON.
   * *Fix*: Put **Structured Inputs** on children; keep **Structured Outputs** for **final responders**.
3. **Vague instructions = noisy routing**
   * *Mistake*: Not telling agents when/why to use a tool or hand off.
   * *Fix*: Add crisp decision rules and success criteria in instructions; include prerequisites for tools.
4. **Over-engineering too early**
   * *Mistake*: Starting with many agents before you have a baseline.
   * *Fix*: Start with a single manager + one specialist; expand only when a boundary is clear.