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 (OPENAIAPIKEY, ANTHROPICAPIKEY, GOOGLEGENERATIVEAIAPIKEY)
• Zod for input/output schema validation (npm install zod)
• Familiarity with agent-based architecture patterns (coordinator, pipeline, broadcast)

Instructions

1. Initialize a TypeScript project with tsconfig.json targeting ES2022 and moduleResolution bundler
2. Install AI SDK v5 core and provider packages for each model backend required
3. Define agent roles by creating separate modules per agent, each with a system prompt, model binding, and scoped tool set
4. Implement tool functions using ai.tool() with Zod input/output schemas for type-safe execution
5. Configure handoff rules using ai.handoff() to delegate tasks between agents with clear trigger conditions and context passing
6. Build routing logic that classifies incoming requests by topic or intent and dispatches to the appropriate specialist agent
7. Wire agents into a workflow using sequential, parallel, or conditional orchestration patterns
8. Add state management to persist context across multi-step workflows using a shared context object or external store
9. Implement circuit breakers and timeout guards to prevent workflow deadlocks
10. Test each agent in isolation, then validate end-to-end handoff chains with representative inputs

See ${CLAUDESKILLDIR}/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