Multi-agent systems divide work among AI agents, each with separate instructions and context. One agent researches a topic while another inspects a codebase. An orchestrator then combines their findings. Workers can use the same underlying model and still have different tools and responsibilities.
The main design question is whether the task benefits from that separation. Independent research can run in parallel. Work that needs the same information at every step may fit one agent better. Context size, tool selection, and the cost of passing work between agents determine how much a split helps.
Copy link to headingWhat is a multi-agent system?
An AI agent uses a model to decide what to do, call tools, and work with the results. A multi-agent system coordinates two or more of these agents on a shared task.
In an orchestrator-worker design, the orchestrator assigns work and combines the findings. For example, a research agent can ask three workers to investigate separate questions, then use their summaries to write an answer. Application code can also assign the work when the steps are known in advance.
Other designs let agents transfer control or coordinate through shared records. Separate contexts do not prevent agents from sharing information. The application decides which messages, files, and database records each agent can access.
Copy link to headingHow single-agent and multi-agent systems compare
A single agent has one main decision loop. It can retrieve information, summarize its history, and change which tools are available as the task progresses. Adding capabilities does not always require another agent.
Multiple agents let workers inspect different materials and return selected findings. The application then has to track which worker produced each result and whether the orchestrator has enough information to use it.
Copy link to headingHow to decide whether your task needs more agents
Run representative tasks with one agent first. Record failures, completion time, and cost. Those results show whether a worker could address a specific problem.
Copy link to headingCheck whether the work can run independently
Research into separate products or codebase areas can run concurrently. Each worker gets a question and returns findings that the orchestrator can combine.
If workers repeatedly need each other's unfinished results, coordination introduces waiting and additional context transfers. Keep those steps together or run them in a defined sequence. A separate reviewer can still help when evaluations show that the extra pass catches errors worth the added time.
Copy link to headingReduce context before splitting the agent
An agent that reads many files can fill its context with material it no longer needs. Context engineering determines which information reaches the model at each step. Retrieval can bring in relevant passages. Compaction summarizes the working history while preserving the goal, decisions, and references needed to continue.
Check whether those changes let the agent finish the task. If it still needs to inspect more material than its context can hold, assign a worker a bounded area to investigate and ask for a summary with source references.
Copy link to headingMeasure tool selection errors
Tool count alone does not tell you when to split an agent. Similar names, overlapping capabilities, and vague descriptions can cause errors even in a small catalog.
Track incorrect choices and failed arguments. Rename ambiguous tools, remove unused ones, and expose the tools needed for the current step. If distinct groups still cause selection problems, give each group to a specialist. There is no fixed tool-count ceiling that applies to every model and workload.
Copy link to headingCompare the cost per completed task
Each worker adds model calls. The orchestrator also spends tokens to assign work and to use the results. Short summaries reduce the context returned to the parent, but the worker's own calls still cost money.
Anthropic's 2025 research-system analysis reported that agents used about 4× the tokens of chat interactions and multi-agent systems used about 15×. Its BrowseComp analysis associated token usage with 80% of performance variance. These findings describe the evaluated system and workload. Use your own tasks to measure the cost and quality change.
Count planning, retries, tool charges, and final synthesis in the comparison. Keep the additional agents when they reliably complete valuable work or meet a latency requirement that the single agent cannot meet.
Copy link to headingHow agents coordinate work
The task's structure determines which agent orchestration pattern fits. AI SDK supports routing, parallelization, and orchestrator-worker workflows, which differ in how they assign work and combine results.
Use application logic for assignments you can define in advance. Model-generated planning adds calls before work starts, but lets the system adapt when it cannot know all the subtasks up front.
Copy link to headingHow to pass work between agents
Workers need enough information to complete their assignment without receiving the full conversation. Define the task, the evidence they need, and the result the orchestrator expects.
Copy link to headingGive each worker a bounded assignment
A codebase researcher might inspect one package with read-only tools. A coding worker might edit an assigned set of files. An integration worker might call one external API.
Include the goal, relevant decisions, resource permissions, and completion criteria in the assignment. Set limits on worker count, retries, and execution time. Ask workers to return findings with source references, unresolved questions, and completion status. AI SDK subagents use separate contexts to keep that intermediate work out of the orchestrator's history.
An orchestrator can use generateText with Output.object() and a Zod schema to produce a structured plan. The schema checks its shape. The application code still needs to check that the proposed work is relevant, permitted, and within budget.
Copy link to headingKeep execution state separate from saved progress
In AI SDK 7, use runtimeContext for shared execution state and toolsContext for values needed by individual tools. Hooks such as prepareStep can read the runtime state. A tool can validate its own context with contextSchema.
When passing state to AI SDK tools and agents, keep request identifiers and tool credentials in the execution context. Include the information the model needs to reason about in its messages. For ToolLoopAgent, configure context in the constructor, or use callOptionsSchema and prepareCall for values that change with each invocation. Save plans, completed results, and recovery checkpoints in durable storage when they must survive a process restart.
Store source references and validation status alongside agent-generated findings. Later agents need a way to check a saved claim before building on it.
Copy link to headingCheck results before another agent uses them
A worker's summary should identify the evidence behind its answer and any work it could not finish. Verify results before using them to make changes or trigger external actions. Confirm that an edit produced the file, a test passed, or an external operation reached the intended state.
The NeurIPS 2025 paper Why Do Multi-Agent LLM Systems Fail? examined more than 1,600 traces across seven frameworks. It reported failure categories of system design issues at 41.8%, inter-agent misalignment at 36.9%, and task verification at 21.3%. These percentages describe the analyzed data.
Use the failed run to decide what to change. A worker may need a missing decision, a clearer completion check, or a task that requires fewer transfers between agents.
Copy link to headingTrace the full run
Register the @ai-sdk/otel integration and configure an OpenTelemetry provider and exporter to collect AI SDK 7 traces. Share run, agent, and delegation identifiers through the application so you can follow work across contexts.
For requests routed through AI Gateway, its session logs group model calls by session and show cost, models, providers, and cached input across turns.
Choose sampling for the traffic and retention budget. Tail sampling can use information collected across a trace to retain errors or expensive runs. A fixed percentage alone cannot guarantee that those runs will be kept.
Before production, evaluate complete tasks for correctness, unsupported claims, unwanted side effects, latency, and cost. An AI agent observability setup connects these evaluations with the traces behind each result. Use the traces to investigate a failure, then repeat the evaluations to check whether a change fixes it across the workload.
Copy link to headingHow to build and run multi-agent systems on Vercel
AI SDK defines the agents and their tool calls. The execution requirements then depend on what the workers do. Model calls need spend controls, generated code needs an execution environment, and long tasks need saved progress.
Copy link to headingExpose a subagent as an AI SDK tool
An orchestrator can delegate through a tool whose execute function calls another ToolLoopAgent. The worker returns its answer as the tool result, and the orchestrator continues. This differs from a handoff that transfers control to another agent.
The example below gives a research worker access to two supplied notes.
import { ToolLoopAgent, isStepCount, tool } from 'ai';import { z } from 'zod';
const notes = { workload: 'Research three independent topics and combine the findings.', constraint: 'Keep delegation bounded and return evidence with each summary.',};
const researchSubagent = new ToolLoopAgent({ model: 'anthropic/claude-sonnet-5.5', instructions: 'Read the supplied notes before answering. Return a concise finding, ' + 'the note IDs supporting it, and any unresolved questions.', stopWhen: isStepCount(5), tools: { readNote: tool({ description: 'Read one supplied research note.', inputSchema: z.object({ id: z.enum(['workload', 'constraint']), }), execute: async ({ id }) => ({ id, text: notes[id] }), }), },});
const researchTool = tool({ description: 'Delegate analysis of the supplied notes to a researcher.', inputSchema: z.object({ task: z.string() }), execute: async ({ task }, { abortSignal }) => { const result = await researchSubagent.generate({ prompt: task, abortSignal, }); return result.text; },});
const mainAgent = new ToolLoopAgent({ model: 'anthropic/claude-sonnet-5.5', instructions: 'Use the research tool to inspect the supplied notes, then explain ' + 'a suitable coordination pattern and its tradeoffs.', stopWhen: isStepCount(5), tools: { research: researchTool },});
const result = await mainAgent.generate({ prompt: 'Which coordination pattern fits the workload in the notes?', abortSignal: AbortSignal.timeout(120_000),});
console.log(result.text);The tool's input schema defines what the orchestrator sends to the worker. The example forwards cancellation and sets a five-step limit for each agent loop. These limits bound execution steps, while a spending budget controls dollar usage.
Replace readNote with retrieval or search when the worker needs external sources. To show intermediate progress, add streaming subagent results. AI SDK's toModelOutput controls which part of the tool output reaches the orchestrator's model, so the interface can display more detail than the model receives.
Copy link to headingPay for CPU while agent code runs
Agents that call hosted models spend time waiting for responses. With Fluid compute pricing, Active CPU billing pauses during input/output waits. Provisioned Memory remains billable until the last in-flight request completes.
Fluid compute reuses instances for concurrent requests and is the default for new projects. Vercel reported savings of up to 85% for high-concurrency workloads when it announced that change. Measure your application's CPU work and memory usage to estimate its costs.
Copy link to headingSet budgets for model calls
AI Gateway budgets cap spend at the team, project, API key, or team member scope. Project budgets count requests authenticated with that project's OpenID Connect (OIDC) tokens. Member budgets count usage from keys attributed to that member.
Budgets are soft caps. A request that crosses the limit can finish, concurrent requests can overshoot it, and subsequent requests receive HTTP 402. AI Gateway budgets exclude spend billed directly to your provider via bring-your-own-key (BYOK) credentials.
Configure model fallbacks to try another model after a failed call. Test the tools and output requirements against each fallback. Handle an exhausted budget by waiting for its reset or changing the limit.
Vercel's Cline case study reported a 43.8% reduction in API error rates and model-specific improvements in 99th-percentile streaming latency.
Copy link to headingChoose how to isolate workers in Vercel Sandbox
Each Vercel Sandbox runs in a Firecracker micro virtual machine. Assigning a sandbox to each worker gives workers separate virtual machine boundaries.
The JavaScript SDK also supports separate Linux users within one sandbox. Each user has a private home directory, and groups let selected users share files. Users in that sandbox share its kernel and network environment. Keep privileged SDK handles outside agent-controlled code.
Choose separate sandboxes when workers need separate virtual machine boundaries. Use Linux users when file permissions within one sandbox meet the task's requirements.
Sandbox quotas allow 10,000 concurrent sandboxes on Pro and Enterprise, with a maximum of 24 hours per session. Stopping and resuming a persistent sandbox starts a new session, so that cap does not bound its total lifetime. A new sandbox has a five-minute timeout by default, so configure or extend it for longer work. Creation rates have separate quotas.
Conductor uses Vercel Sandbox to run parallel coding agents in the cloud. Work can continue after the developer closes their laptop. A durable AI code agent combines Sandbox with workflow steps to generate code, run tests, and retry failed work.
Copy link to headingSave long-running work with Vercel Workflows
WorkflowAgent from @ai-sdk/workflow runs an agent loop inside a function marked with "use workflow". Its durable tool executions use functions marked with "use step" to persist results and retry failures. Install the Workflow SDK integration and configure the build to transform those functions. Set an explicit stopWhen condition, such as isStepCount(20), because WorkflowAgent has no default step limit.
Vercel Workflows has no maximum overall run or sleep duration. Individual steps still follow Vercel Functions execution limits, and each run has limits on steps and events. It supports concurrency of up to 100,000, depending on the plan's Vercel Functions limits.
Make retried operations safe to repeat. A retry should recover any unfinished work without duplicating a payment or any other external action. Handle exhausted retries and terminal failures so the application can report or recover work that did not finish.
Copy link to headingStart with one agent and compare results
Run one agent on tasks that represent the application. Check which failures come from missing context, incorrect tool choices, or work that could run independently. Add a worker for one of those cases and compare completion quality, latency, and cost per successful task.
Use a Vercel template as the foundation for your application, or import an existing project.
Copy link to headingFrequently asked questions about multi-agent systems
Copy link to headingWhat is the difference between single-agent and multi-agent systems?
A single agent uses one main decision loop. A multi-agent system coordinates several loops with separate contexts and responsibilities. Workers can run independently, but the application must pass information between them and combine their results.
Copy link to headingWhat is an example of a multi-agent system?
Anthropic's research system uses a lead agent to assign research questions to workers and combine their findings. It illustrates the orchestrator-worker pattern for research with independent lines of inquiry.
Copy link to headingHow many tools should each agent have?
Use selection accuracy and argument errors to decide. Improve overlapping descriptions and expose relevant tools for each step before splitting the catalog across agents. The appropriate number depends on the model and the work.
Copy link to headingHow can you control multi-agent costs?
Set limits on workers, steps, retries, and result size. Track all model and tool charges for each completed task. Configure spend controls for each billing path, including provider-side controls when using BYOK credentials.
Copy link to headingWhat causes multi-agent systems to fail?
Workers can receive incomplete instructions, use conflicting states, or return results without enough evidence. Tools and external services can also fail. Follow the run's trace to identify the cause, then evaluate the change on similar tasks.