Orchestration Patterns

---
context: fork
name: orchestration-patterns
description: "Catalog of agent orchestration patterns: agents-as-tools, handoff with history filter, deterministic workflows, parallelization, and LLM-as-judge loops. Triggers: orchestration, multi-agent, handoff, agent as tool, agent topology, parallelize agents, LLM-as-judge."
lang: [en]
level: 2
triggers: ["orchestration", "multi-agent", "handoff", "agent as tool", "workflow", "parallelize agents", "agent topology"]
agents: ["architect", "planner", "llm-architect"]
tokens: "~3K"
category: "architecture"
platforms: [claude-code, gemini-cli, codex-cli, cursor]
whenNotToUse:
  - "Single-agent task with no delegation"
  - "Trivial scripts that do not need an LLM"
  - "Cases already covered by Agent Teams API native handoff"
source_hash: 2d3ebb11
---

# Orchestration Patterns

## Overview

Five canonical patterns for composing multiple agents. Pick exactly one per workflow. All patterns are local — no external orchestrator or queue is required. Maps to Artibot primitives: `agentAsTool()`, `filterHandoffHistory()`, Agent Teams API, `runAll()` guardrails.

## When to Use

- Designing a workflow that spans more than one specialist agent
- Reviewing whether a hand-rolled orchestration loop should be replaced with a standard pattern
- Choosing between making a sub-agent a tool (caller stays in control) vs handing off (control transfers)

## When NOT to Use

- Single-agent calls — direct Agent invocation is enough
- Simple sequential pipelines with deterministic steps and no LLM in between (use a script)
- Patterns that require external infrastructure (queues, vector DB) — out of DATA POLICY scope

## Process

| Step | Action |
|---|---|
| 1 | Map the work into discrete cognitive units (one specialist per unit) |
| 2 | Decide caller-vs-callee semantics: agents-as-tools (caller keeps state) or handoff (callee owns state) |
| 3 | If handoff: choose history filter (default drops `function_call`, `function_call_output`, `reasoning`) |
| 4 | If parallel: ensure each unit is independent and aggregate via deterministic merge |
| 5 | Add guardrails at boundaries (input on entry, output on exit) |

## Pattern Catalog

| Pattern | When | Artibot primitive |
|---|---|---|
| Agents as tools | Caller is the planner; sub-agents are utilities | `agentAsTool({name, description})` |
| Handoff | Specialist takes over the conversation | Agent Teams + `filterHandoffHistory()` |
| Deterministic workflow | Steps are fixed; no branching needed | Plain function pipeline |
| Parallelization | N independent subtasks | `Promise.all` + reducer |
| LLM-as-Judge | Quality gate after generation | Two-agent loop with explicit threshold |

## Common Rationalizations

| Excuse | Rebuttal |
|---|---|
| "I'll just chain prompts" | Chained prompts lose state; named patterns track history and tools |
| "handoff and agent-as-tool are the same" | They differ: handoff transfers control; agent-as-tool keeps the caller in charge |
| "we don't need a history filter" | Without filtering, the next agent re-processes function-call noise as if it were instructions |
| "one big prompt is simpler" | One big prompt makes evaluation impossible; patterns let you measure each unit |

## Red Flags

- An agent-as-tool that mutates global state (must be referentially transparent)
- A handoff that re-includes raw `function_call` items (defeats the filter)
- Parallel branches that depend on each other's output (use sequential)
- "Judge" that uses the same model and prompt as the generator (rubber-stamp)

## Verification

- `tests/lib/orchestration/agent-as-tool.test.js` validates the wrapper contract
- Cross-check: each chosen pattern matches exactly one row in the catalog table
- Confirm history filter drops the documented item types in handoff cases