--- name: orchestrating-multi-agent-systems-00dea5e3895b description: 'Execute orchestrate multi-agent systems with handoffs, routing, and workflows across AI providers. Use when building complex AI systems requiring agent collaboration, task delegation, or workflow coordination. Trigger with phrases like "create multi-agent system", "orchestrate agents", or "coordinate agent workflows". ' allowed-tools: Read, Write, Edit, Grep, Glob, Bash(npm:*) version: 1.38.0 author: Jeremy Longshore license: MIT tags: - ai - workflow - agent-orchestration compatibility: Designed for Claude Code --- # 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 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 [`references/implementation.md`](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 [`references/errors.md`](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 [`references/examples.md`](references/examples.md) for additional examples. ## Resources - [AI SDK v5 Documentation](https://sdk.vercel.ai/docs) -- agent creation, tool definitions, handoffs - [Zod Schema Library](https://zod.dev) -- 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 --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/ai-ml/ai-sdk-agents/skills/orchestrating-multi-agent-systems/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Jeremy Longshore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/ai-ml/ai-sdk-agents/skills/orchestrating-multi-agent-systems/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management Roles: Backend Developer, ML / AI Engineer, Product Manager Specialties: API, Backend, Design, Word Documents, Frontend, Playwright, Stripe, Testing Tools: Ai Sdk V5, Anthropic, Google, Openai Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 16e99a856152a6b0e0a28909a302e5d521040ea8dad7dbdbbdd50b1cdf21decb