gabrielmoreira Orchestrating Multi-Agent Systems
Overview
Design and implement multi-agent systems using AI SDK v5 with structured handoffs, intelligent routing, and coordinated workflows across AI providers. This skill covers agent role definition, tool scoping, inter-agent delegation via handoff rules, and workflow orchestration patterns including coordinator-worker and supervisor topologies.
Prerequisites
- Node.js 18+ and TypeScript 5.0+ runtime
- AI SDK v5 (
npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google) - API keys for target providers set in environment variables (
OPENAI_API_KEY,ANTHROPIC_API_KEY,GOOGLE_GENERATIVE_AI_API_KEY) - Zod for input/output schema validation (
npm install zod) - Familiarity with agent-based architecture patterns (coordinator, pipeline, broadcast)
Instructions
- Initialize a TypeScript project with
tsconfig.jsontargeting ES2022 and moduleResolutionbundler - Install AI SDK v5 core and provider packages for each model backend required
- Define agent roles by creating separate modules per agent, each with a system prompt, model binding, and scoped tool set
- Implement tool functions using
ai.tool()with Zod input/output schemas for type-safe execution - Configure handoff rules using
ai.handoff()to delegate tasks between agents with clear trigger conditions and context passing - Build routing logic that classifies incoming requests by topic or intent and dispatches to the appropriate specialist agent
- Wire agents into a workflow using sequential, parallel, or conditional orchestration patterns
- Add state management to persist context across multi-step workflows using a shared context object or external store
- Implement circuit breakers and timeout guards to prevent workflow deadlocks
- Test each agent in isolation, then validate end-to-end handoff chains with representative inputs
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the detailed implementation guide.
Output
- TypeScript agent modules with AI SDK v5 provider bindings and system prompts
- Tool definitions with Zod-validated input/output schemas
- Handoff configuration mapping agent-to-agent delegation triggers
- Workflow orchestration files defining sequential, parallel, and conditional execution paths
- Routing classifier that maps user intents to specialist agents
- Integration test suite covering handoff chains and fallback paths
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Provider configuration invalid | Missing or malformed API key in environment | Verify process.env.*_API_KEY values; check provider SDK version compatibility |
| Circular handoff detected | Agent A hands off to B which hands back to A | Implement handoff depth counter; set maxHandoffDepth and add a fallback terminal agent |
| Task routed to no agent | Routing classifier returned no match for input | Add a default catch-all route; improve classifier training data or keyword coverage |
| Tool access violation | Agent invoked a tool outside its scoped permission set | Review tools array per agent; ensure tool names match registered definitions exactly |
| Workflow timeout | Multi-step workflow exceeded deadline without completion | Set per-step timeouts with AbortController; add workflow-level deadline and partial-result handling |
See ${CLAUDE_SKILL_DIR}/references/errors.md for the full error reference.
Examples
Scenario 1: Customer Support Triage -- A coordinator agent classifies incoming tickets as billing, technical, or general. Billing queries hand off to a specialist agent with access to Stripe tools. Technical queries route to a code-analysis agent with filesystem read tools. Resolution rate target: 85% automated within 3 handoff steps.
Scenario 2: Research Pipeline -- A sequential workflow chains a web-search agent, a summarization agent, and a report-writer agent. Each agent produces structured JSON output consumed by the next. The pipeline processes 50 research queries per batch with a p95 latency under 30 seconds per query.
Scenario 3: Code Review Multi-Agent -- A supervisor agent distributes pull request diffs to specialized reviewers (security, performance, style). Each reviewer returns findings with severity scores. The supervisor aggregates results into a unified review with prioritized action items.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
- AI SDK v5 Documentation -- agent creation, tool definitions, handoffs
- Zod Schema Library -- input/output validation for tools and flows
- Provider integration guides: OpenAI, Anthropic, Google Gemini
- Coordinator-worker and supervisor orchestration pattern references
- OpenTelemetry tracing for multi-agent observability