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.json targeting ES2022 and moduleResolution bundler

• 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