Multi-Agent Orchestration in Notion: When One Agent Hands Off to Another

The 60-second version

Single mega-agents are tempting and bad. Specialized agents in a sequence with clear handoffs are harder to design but much more reliable. The principle: each agent does one thing well and hands a structured result to the next. Three handoffs is about the practical limit before debugging becomes painful. Beyond three, refactor.

Three orchestration patterns that work

1. The pipeline pattern.
Agent A produces structured output → Agent B consumes and produces → Agent C consumes and produces final result. Each agent’s output schema matches the next agent’s input schema. Clear linear flow.
2. The router pattern.
A routing agent decides which specialist agent should handle the request, then dispatches. Specialists are scoped tightly to their domain. The router doesn’t do work itself; it just routes.
3. The reviewer pattern.
A producer agent generates output. A reviewer agent checks against criteria and either approves or returns specific feedback. Iterates until approved or max-attempts hit.

Three patterns that fail

1. Recursive agent chains. Agent A calls Agent B which calls Agent A again. Debugging is awful. Don’t.
2. Shared mutable state. Two agents writing to the same database row simultaneously. Race conditions and overwrites. Don’t.
3. Implicit handoffs. Agent A produces unstructured text; Agent B parses it. The first format change breaks everything. Use structured handoffs.

Designing the handoff contract

The handoff between agents is the highest-risk surface. Three rules:
– Define the schema explicitly. The output of Agent A is JSON-schema-validated input to Agent B.
– Version the schema. Schema changes are breaking changes. Version like APIs.
– Test the handoff in isolation. Mock Agent A’s output; test Agent B’s handling. Mock Agent B’s expected input; test Agent A’s production.

Where orchestration goes wrong in production

1. Cost compounds with depth. Each agent call consumes credits. A three-handoff workflow costs roughly 3x a single-agent workflow. Budget accordingly.
2. Latency compounds too. A 5-second agent x 3 handoffs is 15 seconds end-to-end.
3. Failure modes multiply. Agent A succeeds, Agent B fails, what happens? Define the failure handling explicitly.