AI Agent Orchestration

The routing pattern is the front door of any multi-agent system. Instead of sending every user message to a single monolithic prompt, it classifies the input first and dispatches it to a specialized sub-agent — each with its own system prompt, model, and toolset.

At the core is a classification step powered by generateObject. A Zod schema defines the possible intent categories (like "technical", "billing", or "sales"), and a fast, inexpensive model makes the routing decision. The downstream agent then handles the actual response with a more capable model if needed.

The key architectural insight is separation of classification from generation. The classifier runs something like GPT-4o-mini to keep latency under 200ms, while the responding agent can use a heavier model for quality. This keeps costs manageable at scale — you only pay for expensive inference on the messages that need it.

This pattern also includes load balancing across providers and graceful fallback handling. If the primary model is unavailable, the router can redirect to an alternative without the user noticing. Use this when your application serves multiple distinct user intents that benefit from specialized prompts or different model configurations.

The sub-agent orchestrator demonstrates how to build a custom Agent class that routes queries to specialized child agents. Rather than one agent trying to handle everything, the orchestrator delegates to focused sub-agents — research, analysis, and support — each with their own capabilities.

What makes this pattern powerful is the options passing mechanism. Each sub-agent receives typed configuration that controls its behavior, and the orchestrator coordinates their outputs into a structured response using Output.object. This gives you type-safe orchestration without sacrificing flexibility.

The pattern uses the ToolLoopAgent abstraction, which handles the agent execution loop automatically — calling tools, checking results, and deciding when to stop. The orchestrator sits above this loop, making routing decisions and merging results.

Build on this pattern when you need a hub-and-spoke architecture: a central coordinator that understands the shape of the problem and delegates to specialists. It scales naturally — adding a new capability means adding a new sub-agent, not rewriting the core logic.

Most AI workflows run sequentially — analyze this, then summarize that, then format the result. The parallel processing pattern breaks this assumption by running multiple agents simultaneously on the same input, each providing a different perspective.

Under the hood, this uses Promise.all with multiple generateText calls. Each agent has its own system prompt tuned for a specific analytical lens — sentiment analysis, factual extraction, creative interpretation, or whatever your domain requires. The results are collected and presented together, giving the user a multi-faceted view in roughly the same time as a single analysis.

The performance benefit is significant. If each analysis takes 2-3 seconds sequentially, five analyses would take 10-15 seconds. Running them in parallel brings that back down to 3 seconds — the time of the slowest individual call.

Use this pattern for document review, research synthesis, content evaluation, or any scenario where multiple independent perspectives improve the final output. The key constraint: each parallel task must be independent. If one agent needs the output of another, use sequential chaining instead.

The orchestrator-worker pattern tackles complex, multi-phase projects by breaking them into discrete tasks assigned to specialized worker agents. An orchestrator agent plans the work, assigns tasks, tracks progress, and synthesizes the final deliverables.

This is the most advanced coordination pattern in the collection. The orchestrator uses new Agent with strongly-typed tools to manage the full project lifecycle: planning phases, assigning workers, monitoring progress, resolving blockers, and collecting results. Each worker agent is scoped to a specific domain — design, engineering, testing — with tools and prompts tailored to their specialty.

The key difference from simple routing is state management. The orchestrator maintains a project state object that tracks which tasks are complete, which are blocked, and what the overall progress looks like. Workers report back through structured tool outputs, and the orchestrator decides what to do next.

This pattern shines for multi-step, multi-discipline projects: software feature development, content production pipelines, research coordination, or anything that requires planning before execution. It is more complex to set up than routing or parallel processing, but the payoff is full lifecycle management of non-trivial work.

The multi-step tool pattern gives an agent the ability to reason through complex problems iteratively — calling tools, evaluating results, and deciding what to do next, all within a single conversation turn.

Unlike simple tool calling where the model makes one tool call and returns, this pattern uses stepCountIs to allow the agent to take multiple steps. The agent might search the web, analyze the results, search again with a refined query, and then synthesize everything into a final answer. Each step builds on the previous one.

The pattern includes real-time web search and news integration through typed tools. The agent can pull current information, cross-reference sources, and build up context progressively. The hasToolCall utility lets you check what tools were invoked, enabling conditional logic in the UI.

This is the pattern to reach for when a single tool call is not enough. Research tasks, market analysis, technical debugging — anything that requires the kind of iterative exploration a human would do. The agent decides how many steps it needs; you just set the upper bound.

The URL analysis workflow is the simplest entry point into prompt chaining with the AI SDK. It takes a URL, scrapes the content, analyzes it through an AI model, and returns a structured summary — all in a single, linear pipeline.

Each step in the chain is a discrete function: scrape, analyze, summarize. The output of one feeds directly into the next. This is not an autonomous agent making decisions — it is a deterministic pipeline where you control the exact sequence of operations.

The pattern uses streamText for real-time output and tool() for the scraping step. The simplicity is the point: no routing decisions, no parallel branches, no state management. Just a clean, predictable chain that transforms input into output.

Start here if you are new to AI workflows. The linear structure makes it easy to debug, test, and extend. Once you outgrow it, graduate to routing (for branching logic) or parallel processing (for concurrent analysis). But many production use cases — content summarization, document processing, data enrichment — never need more than this.

The Workflow DevKit orchestrator pattern brings durable execution to multi-agent coordination. Unlike the chat-based orchestrator pattern, this uses the Workflow DevKit (WDK) to ensure that long-running workflows survive failures, retries, and server restarts.

The workflow plans a feature implementation by generating a list of file changes, then spawns parallel workers for each change type — create, modify, and delete. Each worker runs as a separate workflow step, and the WDK ensures exactly-once execution even if the server crashes mid-workflow.

The generateObject call produces a structured plan that the orchestrator uses to dispatch work. Workers execute in parallel using the WDK's built-in concurrency primitives, and results are collected when all workers complete.

Choose this pattern over the chat-based orchestrator when you need reliability guarantees: workflows that take minutes or hours, involve external API calls that should not be repeated, or run in serverless environments where functions may be interrupted. The WDK adds complexity but provides production-grade durability that pure in-memory orchestration cannot match.