DEV Community: JackChen

Goal-Driven Agent Orchestration vs Explicit Graphs: A TypeScript Framework Taxonomy

JackChen — Wed, 03 Jun 2026 12:57:35 +0000

Most multi-agent framework reviews compare features. This post argues you should compare a different axis first: where the framework places the decomposition cost. Goal-first frameworks pay it at runtime in tokens; graph-first frameworks pay it at design time in code. The right default depends on what kind of work your team actually has.

If you spent any time in 2025 evaluating TypeScript agent frameworks, you probably hit the same wall I did. The product pages do not distinguish themselves on the axes that matter once you ship anything. They all promise "multi-agent". They all show a cooperating-agents diagram. They all link to a half dozen integrations. None of them tell you what the framework is going to make you write at 2am when a customer reports a regression.

The thing the pages do not tell you is who decides the topology. That is the central design choice of every multi-agent framework, and it sorts cleanly into two camps. Graph-first frameworks make you decide. Goal-first frameworks let a coordinator agent decide for you at runtime. Each has costs the other does not.

I am the maintainer of one of the goal-first frameworks (open-multi-agent, the TypeScript-ecosystem answer to CrewAI), so my bias is going to show. I am going to try to be honest about what goal-first costs you, because I think the choice between paradigms is more interesting than which framework wins a feature checklist.

The two-axis problem with most comparison posts

Read any "Top N TypeScript Agent Frameworks 2026" listicle and you will get a feature grid: which framework supports streaming, structured output, retries, observability, MCP, Zod schemas, lifecycle hooks, agent handoffs, and so on. Every framework gets a check or a partial mark.

The grid is not useless, but it conceals the design choice that determines whether you will be productive on the framework six months in. That choice is:

Who decides which agent runs next, and when?

Two answers:

You do, at design time. The framework gives you primitives for nodes, edges, conditions, and you wire them. The execution path is whatever your code says it is.
A coordinator does, at runtime. You declare the agents and the goal. The framework runs an LLM call to plan a task DAG, then executes it.

Call these graph-first and goal-first respectively. They are not feature sets. They are paradigms with different cost shapes, different failure modes, and different right-fit use cases.

This post is the taxonomy. The same two-agent task appears inline below, implemented in four TypeScript frameworks (LangGraph.js, Mastra workflows, KaibanJS, open-multi-agent), so you can read each surface and judge for yourself.

What "graph-first" and "goal-first" mean

Graph-first

You declare the topology yourself. Nodes are agents (or steps). Edges declare execution order or conditions. The compiled object is a deterministic state machine. The framework executes it; it does not change it.

Canonical examples:

LangGraph.js: StateGraph with explicit Annotation.Root schema, addNode per agent, addEdge for transitions, addConditionalEdges for routing. You compile the graph and invoke it.
Mastra workflows: createWorkflow with typed inputSchema and outputSchema, createStep per stage, .then() to chain. A linear-graph DSL on top of typed steps.

Goal-first

You declare agents (role, model, system prompt). You hand the orchestrator a sentence-level goal. At runtime, a coordinator agent (an LLM call you do not write) decomposes the goal into a task DAG, assigns tasks to agents, runs them in dependency order, and synthesizes a final answer.

Canonical examples:

CrewAI (Python): the prototype. Crew.kickoff() on a list of agents plus tasks. CrewAI uses the role/goal/backstory metaphor to seed agent behavior.
open-multi-agent: OpenMultiAgent orchestrator plus runTeam(team, goal). The coordinator pattern lives in src/orchestrator/orchestrator.ts (runTeam method) and is described inline in the JSDoc, six steps: decompose, queue, schedule, execute with parallelism, persist results, synthesize.

What about KaibanJS

KaibanJS lives between the two. You define Agent and Task objects with explicit dependencies (the writer's task description references the researcher's output by convention), then the framework's Kanban board moves tasks across columns. Topology is mostly explicit in your task list, but the state machine that drives execution is hidden inside the board abstraction. Call it a hybrid. Closer to graph-first than goal-first in practice.

Four-way side by side: the same task in four frameworks

The task is small on purpose: a researcher agent gathers a brief on a topic, and a writer agent turns the brief into a 400-word summary. The writer depends on the researcher. The snippets below are the relevant core of each implementation, written to show the API surface side by side rather than as a packaged runnable project.

LangGraph.js

const State = Annotation.Root({
  topic:   Annotation<string>,
  brief:   Annotation<string>,
  summary: Annotation<string>,
})

async function researcher(state: typeof State.State) {
  const res = await model.invoke([
    { role: 'system', content: '...' },
    { role: 'user',   content: `Topic: ${state.topic}` },
  ])
  return { brief: String(res.content) }
}

async function writer(state: typeof State.State) {
  const res = await model.invoke([
    { role: 'system', content: '...' },
    { role: 'user',   content: `Brief:\n${state.brief}` },
  ])
  return { summary: String(res.content) }
}

const graph = new StateGraph(State)
  .addNode('researcher', researcher)
  .addNode('writer',     writer)
  .addEdge('__start__',  'researcher')
  .addEdge('researcher', 'writer')
  .addEdge('writer',     '__end__')
  .compile()

const result = await graph.invoke({ topic: '...' })

What you see in the code: a state schema, two node functions, three edges, a compile-and-invoke. The dependency between researcher and writer is the edge addEdge('researcher', 'writer'). The writer reads state.brief because the researcher wrote to it.

Mastra workflows

const researchStep = createStep({
  id: 'research',
  inputSchema:  z.object({ topic: z.string() }),
  outputSchema: z.object({ brief: z.string() }),
  execute: async ({ inputData }) => ({ brief: await callLLM(inputData.topic) }),
})

const writeStep = createStep({
  id: 'write',
  inputSchema:  z.object({ brief: z.string() }),
  outputSchema: z.object({ summary: z.string() }),
  execute: async ({ inputData }) => ({ summary: await callLLM(inputData.brief) }),
})

const wf = createWorkflow({ id: 'r+w', inputSchema: ..., outputSchema: ... })
  .then(researchStep)
  .then(writeStep)
  .commit()

What you see: Zod-typed steps, a .then() chain. The dependency between research and write is positional in the chain. Mastra workflows expose more types than LangGraph at this complexity level, and trades graph generality for linear DSL clarity.

KaibanJS

const researchTask = new Task({
  description: 'Research the topic {topic} and produce a brief.',
  agent: researcher,
})
const writeTask = new Task({
  description: 'Using the brief produced previously, write a 400-word summary.',
  agent: writer,
})

const team = new Team({
  name: 'Research and Write',
  agents: [researcher, writer],
  tasks: [researchTask, writeTask],
  inputs: { topic: '...' },
})

await team.start()

What you see: agents and tasks declared, dependency implicit in task order and prose references. The board state machine drives execution under the hood.

open-multi-agent

const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-sonnet-4-6', defaultProvider: 'anthropic' })

const team = orchestrator.createTeam('research-and-write', {
  name: 'research-and-write',
  agents: [researcher, writer],   // researcher + writer AgentConfig
  sharedMemory: true,
})

const goal = 'Research "Multi-agent orchestration tradeoffs in TypeScript" and write a 400-word summary.'
const result = await orchestrator.runTeam(team, goal)

What you see: agents declared, a goal sentence, one call. What runTeam() can do for you, on a goal complex enough to need it, is a coordinator planning pass that decomposes the goal into a DAG (here a researcher → writer dependency), runs the tasks in order, and synthesizes the final summary. One honest caveat, expanded in the cost section below: this particular goal is simple enough that OMA short-circuits and skips the coordinator entirely, dispatching straight to one agent.

Where the cost actually lives

These four snippets look like a "fewer lines = better" comparison. They are not.

Graph-first frameworks make you pay the decomposition cost in code, at design time, in your file. You write the State schema, you write the edges, you decide the routing. The cost is visible, version-controlled, diffable, and stable: the graph behaves the same on Tuesday as it did on Monday because nothing about it has changed.

Goal-first frameworks make you pay the decomposition cost at runtime, in tokens, in a coordinator LLM call. The cost is invisible in your source code but visible in your bill and your trace. A non-trivial runTeam() call spends a coordinator turn to plan the DAG, plus a synthesis turn to combine results, before any of your agents do their actual work. Those two extra turns are the overhead: proportionally heavy on a tiny job, shrinking toward noise as the real work grows. Simple goals skip it entirely, through the short-circuit described below.

The graph-first model is more predictable. The goal-first model is more compressive: the line count is lower because the work moved into a place you cannot see. Neither is free.

This is the part most comparisons skip. Picking a framework is not picking a feature set. It is picking where you want the topology cost to live: in your repo or in your API bill.

Which paradigm fits your work

Graph-first when the shape of the work is fixed. A pipeline that runs the same five steps on every record is worth writing once as an explicit graph; goal-first would just rediscover that DAG every run and bill you a coordinator turn for it. Same when you need an audit trail (compliance, legal, medical, finance), where "the coordinator decided to skip step 4 this run" is not an answer and an explicit edge from node 3 to node 5 is. Same, doubly, when the problem is a real state machine: cycles, retries that mutate state, interrupt-and-resume across long pauses; LangGraph.js is the most mature option there. And the most common reason of all, less technical than the rest: if your senior engineers do not yet trust an LLM making the routing call, build graph-first and earn that trust before you hand it over.

Goal-first when the shape of the work varies. "Summarize this 3-page contract" and "summarize this 80-page master services agreement" want different sub-tasks; hard-coding the maximum graph and gating it with conditionals is doable but ugly, and a coordinator handles it naturally. It is also the faster paradigm while you are still discovering the decomposition, since changing a sentence-level goal beats redrawing a graph after every user conversation. Once you have several similarly-capable agents, letting a coordinator route between them beats encoding a soft "who does what" call as hard edges. And if your product's value is that it adapts to the user's goal rather than running a fixed automation, you want that planning surface visible, not buried in a graph DSL.

The Coordinator: what the framework writes for you in goal-first

Goal-first sounds magical when you describe it from outside. From inside, the trick is mundane: it is one well-prompted LLM call.

When you call runTeam(team, goal) in open-multi-agent, the orchestrator does this in the runTeam method (full source in src/orchestrator/orchestrator.ts, see the JSDoc on the method):

A temporary coordinator agent receives the goal and the list of agents on the team, with their names, models, and system prompts.
The coordinator is asked to output a JSON array of tasks. Each task has a title, description, assignee (one of the agent names), and an optional dependsOn field listing which earlier tasks must complete first.
Title-based dependency tokens are resolved to task IDs and the array is loaded into a TaskQueue.
A scheduler assigns ready tasks to the named agent. The queue's topological dependency resolution (src/task/queue.ts) figures out which tasks are unblocked.
Independent tasks run in parallel up to maxConcurrency. Results are written to shared memory after each task completes, so downstream tasks can read them.
After all tasks complete, the coordinator runs once more to synthesize a final answer from the collected outputs.
A TeamRunResult is returned with per-agent token usage and a total.

There is a short-circuit: if the goal is short and contains no multi-step signals, the orchestrator skips the coordinator and dispatches the goal directly to the best-matching agent. That keeps trivial goals from paying the planning tax.

The cost is genuinely real, and the example here has a sharp edge worth knowing. The two-agent goal in the OMA example above is simple enough that the short-circuit fires: the coordinator never runs, the goal is dispatched straight to a single agent, and for this goal the tax is zero. You pay the planning-plus-synthesis overhead only once a goal is genuinely multi-step, and when you do, it is proportionally heavy on small jobs and minor on large ones. Do not trust a generic number for it: measure your own workload from result.totalTokenUsage, because the ratio depends entirely on how large your real agent work is next to the two coordinator turns.

What goal-first loses on

Now the honest counterweight: where goal-first is the weaker choice.

The clearest cost is tokens. Whenever a goal is complex enough that the coordinator runs, you pay for that planning turn plus a synthesis turn on top of the actual agent work. Putting the coordinator on a cheap model softens that but does not remove it. There is also a subtler cost that grows with the team: every dependent task carries upstream results forward as context, so agents spend tokens re-reading state they did not produce. Ken W Alger aptly named that the "Prose Tax", and it is the argument for passing explicit, typed results between agents rather than free-form prose.

Then there is control flow. A flat DAG is the natural unit, so anything that is really a state machine (cycles, retry-with-mutation, interrupt-and-resume across long pauses, deeply nested conditionals) can be bent to fit but should not be. If your problem is a state machine, do not pretend it is a DAG.

Debugging is less predictable too. The coordinator can pick a slightly different decomposition between runs, which shifts the output shape. Low temperature, a pinned prompt, and reviewing the plan through the onPlanReady hook all help, but none of them are as deterministic as reading a graph file you wrote yourself.

And there is social proof. Graph-first frameworks have shipped at LinkedIn, Klarna, and J.P. Morgan; goal-first is younger in production at that tier, so it is the harder sell in a board-level review today. For a documented case of an LLM-driven routing system hitting these walls and the engineering response, see Mastra's year of network-to-supervisor, traced through its own issue tracker.

Human-in-the-loop: the bridge to production, already shipped

The path from goal-first as a fast-prototyping paradigm to goal-first as a production paradigm runs through human-in-the-loop, and in open-multi-agent that path is already in place. Two primitives, both shipped, let you put a human between the plan and its execution: the onPlanReady hook (a callback that receives the coordinator's task list and returns approve or reject before anything runs) and PlanOnly mode (runTeam(team, goal, { planOnly: true }), which returns the plan without executing it, so you can inspect or edit it first).

This is the move that brings goal-first into the same audit story graph-first has had since day one: the planning is still LLM-driven, but the executed plan is human-approved. You get the goal-first benefit (you did not write the topology yourself) and the graph-first guarantee (a human signed off on it).

That is the piece that turns goal-first from a prototyping convenience into something you can defend in a production review. The ergonomics will keep improving, but the load-bearing primitives are available today.

Decision rubric

Take this as a starting point, not gospel:

Signal	Lean graph-first	Lean goal-first
Pipeline shape varies per input	weak	strong
Audit trail required	strong	weak
Prototyping a new product	weak	strong
Team unfamiliar with LLM planning	strong	weak
3+ agents with overlapping skills	weak	strong
Cycles or interrupts needed	strong	weak
Goals expressed in user language	weak	strong
Token cost per run is the bottleneck	strong	weak

If your signals split, build the first version graph-first. Graph-first is the safer starting place when you cannot tell which way the pendulum goes. You can always swap to goal-first later when you have learned enough to trust the planning. The reverse migration is harder because you have to invent the explicit topology you never wrote down.

What I'd build first

If you are starting a new TypeScript agent project today and have not picked a framework, I would advise this sequence:

Build the first three weeks graph-first in Mastra workflows. It is the cleanest TypeScript graph DSL right now and gets you to running in the least surface area.
When you find that you are spending most of your time editing the graph rather than the agent prompts, that is the signal your task shape is varying. Try the same task in open-multi-agent with a goal sentence and see whether the coordinator's plan matches what you would have written.
If the coordinator plan is consistently good, switch your prototype to goal-first. If it is consistently off, you are in graph-first territory and you have just saved yourself a six-month detour.

None of this is provably right; it is what I would tell a friend. The frameworks are not enemies, and which paradigm fits your work matters more than which one wins a feature checklist. Pick the paradigm, and the framework choice mostly follows.

About open-multi-agent. TypeScript-native multi-agent orchestration framework, MIT-licensed. Goal-first by design, with a coordinator pattern that decomposes a sentence-level goal into a parallel task DAG at runtime. Three runtime dependencies (@anthropic-ai/sdk, openai, zod). The TypeScript-ecosystem answer to CrewAI's role/goal/crew pattern.

Repo: https://github.com/open-multi-agent/open-multi-agent. Coordinator implementation: src/orchestrator/orchestrator.ts.

Related posts.

5 Walls Multi-Agent Frameworks Hit: the empirical companion to this taxonomy. One TypeScript framework's year-long migration from LLM-driven routing to a supervisor tree, traced through its issue tracker, is the production evidence behind the goal-first / graph-first split.

5 walls multi-agent frameworks hit: receipts from Mastra's year of .network() to Supervisor migration

JackChen — Thu, 21 May 2026 16:28:50 +0000

Multi-agent in TypeScript is engineering-hard. Context propagation between agents, routing quality across providers, observability inside LLM-driven decisions, nesting depth, performance under concurrency: each of these has bitten Mastra over the past year, with public GitHub issues to prove it.

This post pulls 5 engineering walls out of Mastra's year-long migration from .network() to the Supervisor pattern. I searched the Mastra GitHub repo for AgentNetwork, multi-agent, supervisor, and network, got 32 relevant issues spanning May 2025 to May 2026, and cite 18 representative ones below.

Why Mastra specifically? Because they are the most public case study. On April 9, 2026, Mastra raised a $22M Series A led by Spark Capital, bringing total funding to $35M. Same day, they launched Mastra Platform. I read the Series A post, the Platform announcement, and the pricing page end to end: the exact phrase "multi-agent" appears zero times across all three. They still mention subagents once in the Series A post, so multi-agent coordination has not vanished as a capability. But "multi-agent" as a positioning word is gone.

This is a shift. Nine months earlier, in July 2025, Mastra published "Beyond Workflows: Introducing Agent Network" and positioned automatic LLM-driven multi-agent routing as a step beyond workflows. Nine months later, the Series A narrative is Studio + Server + Memory Gateway. It is "agent infrastructure platform." It is "framework gives you primitives, platform gives you tools to run at scale."

What happened in between? The 32 issues are far more honest than any blog post. They cover Mastra's full arc: every iteration, every transition, every shift in positioning.

The five walls are below. Each one Mastra hit, with issue receipts.

Context: everyone was racing on multi-agent

To understand the weight of this shift, look at the field. Through 2024 and 2025, LangGraph, CrewAI, AutoGen, and Mastra all pushed multi-agent as a core narrative. The Microsoft AutoGen paper kept emphasizing "multiple agents collaborating outperform a single agent." LangChain promoted LangGraph to a top-line product. CrewAI grew to tens of thousands of stars in a year.

In the TypeScript world, Mastra was the standard bearer. Founded October 2024 by Gatsby co-founder Sam Bhagwat and team. YC W25. $13M seed round announced October 2025, from 100+ investors (the post headline says "120+ others"), including YC, Paul Graham, Guillermo Rauch, Amjad Masad, and Balaji Srinivasan. Three founders from a framework used by hundreds of thousands of developers.

They had every advantage: TS ecosystem, Gatsby pedigree, YC, top-tier VCs, marquee angels, a $22M Series A, and customers including Replit, Brex, Sanity, Factorial, Indeed, Marsh McLennan, MongoDB, Workday, and Salesforce.

And they still moved .network() out of the multi-agent headline.

The full timeline of Mastra's multi-agent narrative

Date	Event	Position of "multi-agent" in their story
Oct 2024	Team formed	None. Pitch was "TS framework for the next million AI developers"
H1 2025	AgentNetwork v1 (experimental)	Present, but they later admitted v1 was "pretty whack"
Oct 8, 2025	$13M seed round announced	Not a core funding narrative
Jul 3, 2025	Blog: "Beyond Workflows: Introducing Agent Network (vNext)"	Peak. Original wording: "intelligent AI orchestration that automatically routes and executes complex multi-agent tasks without predetermined workflows"
Aug 26, 2025	Blog: "Improved agent orchestration with AI SDK v5"	The "orchestration" in the title quietly downgrades to single-agent tool orchestration
Oct 10, 2025	Blog: "The evolution of AgentNetwork." `.network()` API consolidates	Multi-agent still featured, but the API is simplifying
Nov 2025	v1 Beta	Still mentions `.network()` for agent networks
Jan 2026	v1.0 stable	Multi-agent no longer a top-line feature
Feb 26, 2026	Supervisor pattern launches as the first-class primitive for multi-agent orchestration	`.network()` later marked deprecated in the migration guide
Apr 9, 2026	Mastra Platform + Series A $22M	The exact phrase "multi-agent" appears 0 times across the Series A, Platform, and Pricing pages. `subagents` still mentioned once
May 19, 2026	"Introducing A2A support"	Cross-framework interop protocol. Multi-agent capability continues, but now framed as agent-to-agent interop rather than internal orchestration

Multi-agent as primary headline ran from July 2025 to November 2025, roughly 4 to 5 months. Then a quiet downgrade in August, an API migration to Supervisor in February, and a vocabulary switch in the Series A by April.

Nine months of repositioning.

Blogs are written for press. Issues are real.

Announcement posts have communications teams. GitHub issues do not.

The Mastra repo currently has about 24.1k stars, 2.1k forks, and 200+ open issues (checked 2026-05-21). Of the 32 issues matching my search, this post cites 18 representative ones. Five themes show up repeatedly. These are not feature requests. They are not typos or doc errors. They are the actual hard problems of running multi-agent systems in production.

Mastra spent a year on them and chose to migrate to a structurally simpler design (Supervisor tree) that sidesteps some, but not all, of them.

Here are the five walls.

Wall 1: Memory, context propagation, and persistence between agents

This is the deepest wall, and the one Mastra hit longest.

Issue #11468, titled simply "Agent Network," was filed December 29, 2025 from their Discord. The original text:

"Using agent.network() I found something that when an orchestrating agent decides which secondary agent to call, the message history is not transferred to the secondary agent, making it difficult for it to understand the context for action. Please, can you help me with this? I haven't found in any documentation how to pass the memory to this flow in the final agent."

Translated to product language: the coordinator decides who to call, but the agent being called does not know why it is being called.

This problem persisted in Mastra's tracker for at least six months. Issue #5381 ("Memory for Networks?") was filed June 23, 2025. Adjacent memory/storage/persistence issues continued after the Supervisor migration, including #15336 ("LibSQL Storage/Memory Error with supervisor agent and sub agents") and #14583 ("Supervisor/Subagent Persistence Duplication"). These are not strictly the same "message history not propagated" bug as #11468, but they share a root: state management between a coordinator and its sub-agents is hard, in multiple ways.

The real engineering hardness: you cannot dump the entire conversation history into every sub-agent (token explosion, privacy, signal-to-noise), but you cannot leave them blind either (they need task context). The tradeoff is an open problem, not a few-months problem.

Wall 2: Routing quality and prompt fragility

Automatic LLM-driven routing depends on prompt robustness across models. Cross-provider, the same routing prompt behaves very differently.

The receipts:

#9873 (2025-11-07) "Network Agents does not forward the request to sub agents inside the network." Routing literally does not work
#12468 (2026-01-29) "Agent Network Routing Latency." Slow
#12955 (2026-02-11) "The sub agents are returning empty output inside network." Sub-agents return empty
#13621 (2026-02-28) "Agent Network routing prompt has trailing whitespace, causing failures with Bedrock-backed Claude models." A trailing whitespace in a routing prompt breaks the entire routing chain on Bedrock Claude.

The last one is the most diagnostic. A trailing whitespace, undebuggable across providers. This is not a user mistake. This is the brittleness of LLM-driven routing as a paradigm. Switch providers and your routing behavior may need a full re-tune.

Wall 3: AgentNetwork routing observability gap

LLMs do the routing inside AgentNetwork. Users couldn't see why.

Issue #12277 (2026-01-24) "Missing Observability for Routing and Validation LLM Calls in Agent Networks" pointed this out directly. The scope is narrow: it's specifically about tracing for AgentNetwork's internal routing and validation LLM calls, not framework-wide observability. By that date, .network() had been live for roughly three months. Production users of .network() had been flying blind on the routing layer that whole time.

Observability for AgentNetwork's routing and validation had to be a day-one design decision. Adding it months in means months of users hitting "why did the coordinator pick this agent" without an answer.

Wall 4: Three-level nesting already breaks

Issue #15013 (2026-04-03) "3-level sub-agent delegation: no progressive streaming to client."

Three levels of sub-agent delegation is enough to break streaming.

This matters because multi-agent frameworks that aspire to be an "agent OS" or "agent operating system" need to support deep organizational structures. Mastra cracks at three levels of sub-agent delegation. I haven't found public benchmarks for any framework at four levels of agent delegation, and Mastra hasn't disclosed the topology depth of their customer workloads (Brex, Indeed, Marsh McLennan), so I can't claim anything about that ceiling. What I can say is: three-level streaming broke for at least one user of Mastra, and the "deep agent organization" pitch deserves a higher evidence bar than it usually gets.

Wall 5: Performance collapse

Issue #15478 (2026-04-17, closed 2026-05-20), "[RFC] Agent Performance Optimization (Slow Responses)."

This is an RFC, not a bug. Mastra opened a public RFC acknowledging slow agent responses had reached the level of a systemic issue. The RFC was closed on May 20, 2026, the day before this post, after a maintainer commented that it had been taken care of.

The diagnosis comes via #15677 (2026-04-23):

"ObservationalMemoryProcessor.processInputStep blocks every agentic loop step with DB reads and token counting even when far below thresholds."

Translated: every agent loop iteration triggers a database read and token counting. Tolerable on a single agent. Catastrophic when amplified across a supervisor with multiple concurrent sub-agents.

The hidden cost of multi-agent is consistently underestimated. Each agent is one LLM call. Each call needs context handling, plus observability, tracing, token counting, memory I/O. Mastra is exposing the real cost of these "lightweight" operations once they are stacked on multi-agent topologies.

What happened after migrating to Supervisor

On February 26, 2026, Mastra officially launched the Supervisor pattern. The changelog described it as "a first-class supervisor pattern, exposed through the same primitives you already use, stream() and generate()." .network() was later marked deprecated in the migration guide: "will be removed in a future release. While existing code will continue to work until then, no new features will be added to it."

The logic of the migration: shift from LLM-driven routing to manually configured sub-agents in a tree. Simpler structure, more predictable decisions, fewer bug surfaces.

The issue data tells a different story.

From March to May 2026, Supervisor-related issues clustered:

#14723 (2026-03-26) Supervisor and sub-agent interactions stored as Supervisor-and-User interactions (history pollution)
#14820 (2026-03-29) No way to abort sub-agent execution in supervisor mode
#14583 (2026-03-23) Supervisor/Subagent persistence duplication
#15013 (2026-04-03) Three-level sub-agent delegation streaming broken
#15336 (2026-04-14) LibSQL storage + sub-agent throws
#15436 (2026-04-16) No control over sub-agent tool results
#15734 (2026-04-24) Suspend/resume breaks when sub-agent owns a workflow
#15887 (2026-04-28) Sub-agent calls serialized under approval mode (concurrency dies)
#16422 (2026-05-11) transformAgent drops sub-agent tool input streaming chunks
#15478 (performance RFC, closed 2026-05-20)

Supervisor is not the destination. It simplified some problems (no more LLM auto-routing), but the core multi-agent challenges (context propagation, persistence consistency, nesting depth, concurrency control, streaming) did not disappear. They got new issue numbers and resurfaced.

"Simplified design" is the story told to the community and to investors. The engineering reality is that they are still patching.

What this means

Three takeaways from a year of Mastra's public behavior.

One. The migration is not a concept failure. It is an engineering hardness.

Multi-agent as a concept is validated in research and product. LangChain, AutoGen, CrewAI are all doing it. The gap is between "concept works" and "production-stable." Crossing it took Mastra a year, dozens of issues, one major API rewrite, and a vocabulary switch in the Series A. This is not a "pick it up and ship" direction. It is a real-engineering domain.

Two. Multi-agent depth beyond two levels remains a hard, undersolved problem.

Mastra's 3-level streaming bug (#15013) suggests this isn't a Mastra-only ceiling, but I can't speak for frameworks I haven't tested. What I can say from the receipts: prompt robustness, context propagation, streaming, token accounting, error recovery each barely held at two levels in Mastra's case, got shaky at three, and I haven't found public reliable demos at four for any framework. If you have counterexamples, I'd genuinely like to see them.

Three. "Agent OS" as a buzzword does not match engineering reality.

An operating system implies stability, predictability, and deep process nesting. A system that breaks streaming at three levels of delegation, needs an RFC for performance, and took six months to figure out context propagation is at best a framework. Calling it an OS is writing a check that current technology cannot cash.

Mastra clearly knows this. Their funding announcements do not use "OS." They use "Platform." They use "framework." They use "infrastructure." These are bounded words.

Where I am sitting

I have been working on an open-source TypeScript multi-agent framework since April 2026. We call it open-multi-agent. The repo lives at github.com/open-multi-agent/open-multi-agent.

Watching Mastra's migration over the past year did not convince me the road is dead. It convinced me of something else: Mastra chose to migrate .network() into Supervisor and shift the headline vocabulary. We are choosing to walk directly into these five walls and call them out by name.

Where we are today:

Wall 1 (context propagation): SharedMemory as a namespaced key-value store, injected into prompts as markdown summaries, plus MessageBus for point-to-point and broadcast messages between agents. Different mechanism from Mastra's "pass message history." We sidestep the problem rather than solving it directly
Wall 2 (routing): Coordinator decisions are constrained by Zod schema with one automatic retry on validation failure. Local model fallback parses raw JSON and markdown-fenced JSON output formats
Wall 3 (observability): Built-in post-run task DAG dashboard (pure HTML render, no I/O dependency). Every team run renders the task DAG, assignee per task, status, timing, and token usage. Day-one design
Wall 4 (nesting): maxDelegationDepth cap, plus cycle detection (target already in delegationChain is rejected) and agent pool deadlock detection (rejected when availableRunSlots < 1). Three guards from day one
Wall 5 (performance): Three runtime dependencies only (@anthropic-ai/sdk, openai, zod). SharedMemory is in-process by default with no per-step DB I/O. Three-layer Semaphore concurrency control (agent pool, per-agent, tool execution)

What we have not solved

None of the five walls is "we figured it out with a clever design." This is industry-hard. Not a single-team intelligence problem.

I should be explicit about where we are short:

Nesting depth: maxDelegationDepth defaults to 3. That is exactly the depth at which Mastra cracked. We have not done serious engineering tests beyond four. Open problem for us too
Performance: We have not systematically load-tested 100 tasks × 10 agents. Mastra hit performance walls in customer production, and our sample size is not comparable yet
Context propagation: SharedMemory + MessageBus is directionally correct, but the policy of "what a sub-agent sees by default" is still iterating. We have not reproduced every Mastra failure case
Cross-provider robustness: We run basic routing-consistency tests across providers. Edge cases like "trailing whitespace breaks Bedrock Claude" have not been systematically swept

This post is not announcing that we solved what Mastra did not.

It is an invitation. Multi-agent is a real direction with real engineering value and real engineering difficulty. We are continuing to push on it. If you also believe this is worth doing, come help.

How to get involved

Repo: github.com/open-multi-agent/open-multi-agent

PRs welcome. Counterarguments welcome in issues. Failure cases that break our claims especially welcome.

Frequently asked questions

Did Mastra abandon multi-agent?

No. Mastra continues to support multi-agent coordination through the Supervisor pattern (launched February 26, 2026), the subagents primitive, and the A2A cross-framework interop protocol (May 19, 2026). What changed is the headline vocabulary: their Series A and Platform announcements (April 9, 2026) no longer use "multi-agent" as a positioning word. The capability stayed; the API and the marketing both shifted.

If I'm starting a multi-agent project in TypeScript today, what should I use?

It depends on what you need. Mastra's Supervisor pattern is backed by a well-funded company with enterprise customers (Replit, Brex, MongoDB, Workday, Salesforce, Indeed), and it fits well when you want manually configured sub-agents with predictable execution. If you want LLM-driven goal-to-DAG decomposition (one goal in, an auto-generated task DAG executed across multiple agents in dependency order, rather than manually configuring a supervisor tree), open-multi-agent takes that approach with 3 runtime dependencies and a Coordinator pattern. LangGraph is also worth a look if you don't mind Python.

What is open-multi-agent and how does it differ from Mastra?

open-multi-agent is an open-source TypeScript framework for multi-agent orchestration, launched April 2026 (github.com/open-multi-agent/open-multi-agent). The core difference: open-multi-agent uses a Coordinator that decomposes a goal into a task DAG via LLM, then executes tasks in dependency order across multiple agents in parallel, whereas Mastra's current Supervisor pattern uses manually configured sub-agents with the supervisor delegating at runtime. Other design choices include 3 runtime dependencies (@anthropic-ai/sdk, openai, zod), in-process SharedMemory with no per-step DB I/O by default, and built-in delegation depth caps with cycle detection.

Does open-multi-agent solve the 5 walls Mastra hit?

Honestly, partially. We have explicit design choices for each wall (SharedMemory + MessageBus for context, Zod-constrained Coordinator decisions for routing, post-run task DAG dashboard for observability, depth caps + cycle detection for nesting, in-process state for performance). But we have not load-tested at 100 tasks × 10 agents, our default maxDelegationDepth is 3 (exactly where Mastra cracked), and cross-provider routing edge cases like "trailing whitespace breaks Bedrock Claude" have not been systematically swept. This is an open invitation, not a solved problem.

Sources

Mastra posts and announcements:

GitHub issues (in order of appearance):

Context propagation: #11468 #5381 #15336 #14583
Routing quality: #9873 #12468 #12955 #13621
Observability: #12277
Nesting: #15013
Performance: #15478 #15677
Supervisor era: #14723 #14820 #15436 #15734 #15887 #16422

I work on open-multi-agent, an open-source TypeScript multi-agent framework. Comments, counterarguments, and failure cases welcome at the repo.

How to Run a Mixed-Model AI Agent Team in TypeScript?

JackChen — Sat, 16 May 2026 08:05:41 +0000

A practical walkthrough that takes you from a single-model team baseline to a mixed-provider production setup with live cost and latency monitoring, using open-multi-agent, the TypeScript-ecosystem answer to CrewAI.

If you have ever priced out a multi-agent system that runs on a single frontier model, you already know the trap. You wire up three agents, plan, build, review, and the monthly bill can hit hundreds of dollars at modest cadence (100 runs/day) and climb past four figures at production volume, because the architect, the developer, and the reviewer are all eating Opus tokens to argue about a one-line bug.

Most TypeScript agent frameworks assume one provider, one model. You can swap the model, but only globally. That single knob makes the cost-quality tradeoff harder than it needs to be. The frontier models are right for a small fraction of the team's turns. The rest is wasted spend.

This post shows the alternative. Three agents, three different model tiers, one runTeam() call. Architect on Claude Opus 4.7, developer on a cheaper hosted OpenAI model, reviewer on a local model running through Ollama. The mix is configured per agent in AgentConfig, no provider lock-in, no glue code. By the end you will have:

A concrete way to combine the existing OMA examples for multi-model teams, local models, and cost-tiered execution.
A cost ledger that gets you per-agent dollar numbers from a single onProgress callback.
A current pricing table for the providers used here, snapshot 2026-05-16, so you can do back-of-the-envelope monthly forecasts before you commit.
An honest list of what mixed-model teams cost you (because they do cost something).

The repository examples this post connects are:

examples/basics/multi-model-team.ts: different hosted models per agent.
examples/providers/ollama.ts: Claude plus a local Ollama reviewer through an OpenAI-compatible baseURL.
examples/patterns/cost-tiered-pipeline.ts: token usage and cost comparison across model tiers.
examples/providers/gemini.ts: Pro/Flash tiering inside one provider.

There is no separate companion repo for this post. The point is the pattern: per-agent model assignment is already a first-class field on AgentConfig.

What "mixed-model" actually means here

A few definitions before we start, because the term is overloaded.

Single-model team. Every agent runs on the same provider and the same model. Easiest to reason about, easiest to debug, most expensive when the model is a frontier one.

Multi-provider team. Different agents run on different providers, but each agent's model is still picked at design time, not at runtime. This is what we mean by "mixed-model" in this post.

Dynamic model routing. The framework decides which model to use per turn based on cost, latency, or quality signals. Powerful, but adds a layer of indirection and a new failure mode. Out of scope here. Static per-agent assignment gets you 80% of the value with 5% of the complexity.

The framework primitive we lean on is AgentConfig. open-multi-agent's AgentConfig carries provider, model, baseURL, and apiKey on each agent. The orchestrator instantiates the right LLM adapter (Anthropic, OpenAI, Gemini, Grok, Bedrock, Copilot, and OpenAI-compatible local servers via baseURL) lazily, so you only install the SDKs you actually use.

The four pieces, in order

The OMA repo already has the building blocks. Read them in this order; each one isolates a different part of the mixed-model pattern.

Step 1: All-Opus baseline (the cost ceiling)

import { OpenMultiAgent } from '@open-multi-agent/core'
import type { AgentConfig } from '@open-multi-agent/core'

const architect: AgentConfig = {
  name: 'architect',
  provider: 'anthropic',
  model: 'claude-opus-4-7',
  systemPrompt: 'You are a senior software architect...',
  temperature: 0.2,
}
const developer: AgentConfig = { ...architect, name: 'developer', systemPrompt: '...' }
const reviewer:  AgentConfig = { ...architect, name: 'reviewer',  systemPrompt: '...' }

const orchestrator = new OpenMultiAgent({
  defaultModel: 'claude-opus-4-7',
  defaultProvider: 'anthropic',
})

const team = orchestrator.createTeam('design-build-review', {
  name: 'design-build-review',
  agents: [architect, developer, reviewer],
  sharedMemory: true,
})

const result = await orchestrator.runTeam(team, 'Implement retryWithBackoff<T>...')
console.log(result.totalTokenUsage)

That is the entire team. Three agents, one model, one orchestrator. The coordinator that gets spawned by runTeam() decomposes the goal into tasks, assigns each task to an agent, runs them with dependency-aware parallelism, and returns a TeamRunResult with per-agent token usage in agentResults and a total in totalTokenUsage.

We use it as the cost ceiling. Everything that follows will be measured against this baseline.

Step 2: Dual-model (Opus plans, OpenAI executes)

The architect's job is to look at the goal once, decide what to build and what to skip, and lay out an API shape. It is called rarely, but each call is high leverage. Opus is right for that.

The developer and the reviewer fire many times on smaller prompts. The reviewer in particular is mostly running short checklist passes. Spending Opus tokens on those is wasteful. A mini-tier OpenAI model, for example GPT-5.4 mini at $0.75 input and $4.50 output per million tokens as of 2026-05-16, is roughly 5.5x cheaper than Opus on the output side. You can absorb the quality delta on simpler turns.

const architect: AgentConfig = {
  name: 'architect',
  provider: 'anthropic',
  model: 'claude-opus-4-7',
  systemPrompt: '...',
}
const developer: AgentConfig = {
  name: 'developer',
  provider: 'openai',
  model: 'gpt-5.4-mini',
  systemPrompt: '...',
}
const reviewer: AgentConfig = {
  name: 'reviewer',
  provider: 'openai',
  model: 'gpt-5.4-mini',
  systemPrompt: '...',
}

Same createTeam(), same runTeam(). The only thing that changes is provider and model on two of the three agents. The orchestrator handles the adapter switching internally; you do not write a single line of provider-specific code in your team setup.

Step 3: Triple-model with a local reviewer

Now we push the reviewer onto a local model. The argument is the same as Step 2, pushed harder: the reviewer does style checks, edge-case prompts, and short-form QA. A local Ollama model is often good enough for that, and the marginal cloud cost is zero.

The trick is that Ollama exposes an OpenAI-compatible endpoint, so you reuse the openai adapter and override baseURL and apiKey on the agent:

const reviewer: AgentConfig = {
  name: 'reviewer',
  provider: 'openai',
  model: 'llama3.1',
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama',
  systemPrompt: '...',
}

A note that catches people: even when the local server ignores the key, the OpenAI SDK validates that it is non-empty. Pass any placeholder. 'ollama' works.

Prerequisites for this step: ollama pull llama3.1 once, then ollama serve in a separate terminal. Swap llama3.1 for Gemma, Qwen, or whatever local model you actually use. Same setup works with vLLM, LM Studio, llama-server, or any OpenAI-compatible inference server.

Step 4: Live cost and latency monitoring

The mixed-model team is now functionally complete. The problem is you do not yet know what it costs. In production you want to find out fast when an agent hot-loops on Opus and burns $50 in an afternoon.

open-multi-agent's OrchestratorConfig accepts an onProgress callback that fires for agent_start, agent_complete, task_start, task_complete, error, and a few others. We use the start and complete events to build a per-agent ledger.

const ledger = new Map<string, { startedAt: number; finishedAt?: number; model: string }>()
const modelForAgent = (agent: string) =>
  [architect, developer, reviewer].find(a => a.name === agent)?.model ??
  (agent === 'coordinator' ? 'claude-opus-4-7' : 'unknown')

const orchestrator = new OpenMultiAgent({
  defaultModel: 'claude-opus-4-7',
  defaultProvider: 'anthropic',
  onProgress: (event) => {
    if (event.type === 'agent_start' && event.agent) {
      ledger.set(event.agent, { startedAt: Date.now(), model: modelForAgent(event.agent) })
    }
    if (event.type === 'agent_complete' && event.agent) {
      const entry = ledger.get(event.agent)
      if (entry) entry.finishedAt = Date.now()
    }
  },
})

After runTeam() finishes, you walk result.agentResults, pull tokenUsage for each agent, look up the per-million pricing for its model, and compute a dollar number. The same ledger pattern used by the cost-tiered example produces output like this (representative shape; for a real recorded run with measured numbers, see the Update 2026-05-22 section near the end of this post):

agent       | model              | latency  | tokens in/out  | cost
------------+--------------------+----------+----------------+--------
coordinator | claude-opus-4-7    |    3.4s  |   1102/   612  | $0.0208
architect   | claude-opus-4-7    |    6.1s  |   1580/  1140  | $0.0364
developer   | gpt-5.4-mini       |    8.7s  |   2240/  2106  | $0.0112
reviewer    | llama3.1           |   12.0s  |   2680/   480  | $0.0000

Grand total: $0.0684 USD

The reviewer is the slowest agent in the table because a local model on a consumer machine is usually slower than a hosted frontier model. That is the local-cost trade-off in concrete terms: zero marginal cloud dollars, more wall-clock seconds. Whether that is the right call depends on whether your team blocks on the reviewer or runs it asynchronously.

Pricing snapshot (2026-05-16)

These are the numbers used by the examples and estimates in this post. They are also the numbers you want for any cost back-of-the-envelope before you ship a mixed-model team to production. Verify on the official pages before you commit to a forecast.

Model	Input ($/1M)	Output ($/1M)	Source
Claude Opus 4.7	$5.00	$25.00	platform.claude.com
Claude Sonnet 4.6	$3.00	$15.00	same
Claude Haiku 4.5	$1.00	$5.00	same
GPT-5.5	$5.00	$30.00	openai.com/api/pricing
GPT-5.4	$2.50	$15.00	same
GPT-5.4 mini	$0.75	$4.50	same
Gemini 2.5 Flash	$0.30	$2.50	ai.google.dev/gemini-api/docs/pricing
Local model via Ollama	$0 marginal	$0 marginal	electricity + amortized hardware

A reasonable starting reading of the table: the cloud frontier models charge 4x to 8x more on the output side than on the input side. That is the inversion you want to design against. Push input-heavy agents (research, summarization, retrieval grounding) onto the cheaper models. Reserve the expensive models for agents that produce a lot of high-stakes output.

A worked cost comparison on a recurring workload

Suppose your team runs the same three-agent task 100 times a day (real-world cadence for an automation that fires on inbound webhooks, scheduled batches, or per-customer pipelines). A representative run uses roughly:

Coordinator: 1.1K input, 0.6K output tokens (Opus 4.7 in all variants)
Architect: 1.6K input, 1.1K output
Developer: 2.2K input, 2.1K output
Reviewer: 2.7K input, 0.5K output

Use this as a representative shape, not a benchmark. Your numbers will differ; the math below shows how to do it. If you want to measure your own workload, start with examples/patterns/cost-tiered-pipeline.ts.

All-Opus run (Step 1 baseline) runs to about $0.15 per execution on the token shape above. At 100/day that is roughly $450/month.

Dual-model (Step 2): Opus on coordinator + architect, GPT-5.4 mini on developer + reviewer. About $0.073 per run. Roughly $219/month.

Triple-model (Step 3): Opus on coordinator + architect, GPT-5.4 mini on developer, local Ollama model on reviewer. About $0.068 per run on the cloud side. Roughly $205/month, plus the local model's wall-clock overhead on a machine you already own.

That is a little over 50% monthly savings against the all-Opus baseline on this token shape, with the quality drop contained to lower-risk roles. The savings shape changes by workload: research-heavy, summarization-heavy, or retrieval-grounded teams can gain more by pushing input-heavy roles to cheaper models. Reasoning-heavy teams gain less and may be wrong to mix at all.

When mixed-model is the wrong call

The post would be useless if it told you to always mix. Here is the honest list of when not to.

Single-agent tasks. If your goal is small enough that one agent can finish it, do not split into a team just to mix models. The coordinator overhead and inter-agent context shuffling will dwarf the savings.

High-consistency tasks. Models from different providers disagree on edge cases. If your output is graded against a strict rubric (legal review, medical triage, anything with a regulator-facing audit trail), the variance from mixing providers will bite you. Stay on one model and pay the price.

Tight feedback loops with human reviewers. When you are still iterating on prompts and the team's behavior is unstable, mixing models adds a degree of freedom you do not want. Get the team to converge on a single model first, then push pieces out to cheaper models once each role's prompt is stable.

Cheap models with cheap output. If every agent in your team already fits a single Haiku or GPT-5.4 mini run, the absolute savings from mixing are pennies and the operational complexity is real. Mixed-model pays off when at least one role's monthly cost is meaningful enough to justify the variance.

Provider failure handling that is not in place. A mixed-model team has more failure surfaces than a single-model team. Three providers means three rate-limit ceilings, three auth flows, three latency profiles, and three ways your pipeline can stall on a 503. Decide your retry, fallback, and circuit-breaker strategy before you ship.

What the cookbook example looks like in mixed-model form

open-multi-agent ships a personalized interview simulator cookbook that runs three agents on Claude Sonnet 4.6: an interviewer, an observer, and a reporter. It is a nice match for the mixed-model pattern.

The interviewer does deep, candidate-specific question generation across many turns. That role earns Opus.

The observer reads the transcript after each turn and writes 3-6 short flags. The role is short-output, repeatable, and structurally simple. Push it to a cheaper hosted model or even a local model.

The reporter runs once at the end of the session against a strict Zod schema (recommendation: 'strong-hire' | 'hire' | ..., plus structured arrays). Structured-output agents are sensitive to the underlying model's JSON adherence. Keep that on a frontier model.

The migration is two provider and model edits, two AgentConfig blocks. You do not touch the orchestration logic. You do not refactor the prompts. You read the schema and decide where the consistency requirements actually live.

Why this lives in the TypeScript ecosystem

A small note on positioning since this is the question I get asked most.

CrewAI established the team-of-agents shape that this post leans on: an agent has a role, agents form crews, a crew has a goal, and the framework orchestrates the goal into work. CrewAI is Python-only, and the TypeScript options for the same pattern have been thin until recently. open-multi-agent treats the TypeScript ecosystem as a first-class target: 100% TypeScript runtime, three runtime dependencies (@anthropic-ai/sdk, openai, zod), and the same Goal → Result one-call surface (runTeam) that you would get from CrewAI's Crew.kickoff(). The mixed-model team is, by design, a first-class pattern rather than a custom adapter you write yourself.

If you are coming from CrewAI and looking for the team-of-roles model in TypeScript, the examples above are the migration target.

Update 2026-05-22: Real run data + thinking-mode cost

The original post (2026-05-16) uses Anthropic + OpenAI as the canonical example because that's the setup most TypeScript readers will recognize. After publishing, I ran the same runTeam-shaped pipeline with DeepSeek + a local Qwen model on an M1 16GB MacBook because those were the API credentials I had at hand. Same code path, different provider/model strings. That's the model-agnostic point of the post, applied honestly to my own constraints.

This section adds (1) the actual recorded ledger so anyone reproducing can work from measured data, (2) a side experiment on thinking-mode cost using two Qwen 3.5 9B variants, and (3) a known limitation of the OMA + OpenAI-compatible path for thinking-mode models.

Setup for the real run

coordinator / default: DeepSeek deepseek-chat (non-thinking, $0.14 / $0.28 per MTok)
architect: DeepSeek deepseek-reasoner (thinking mode, same pricing)
developer: DeepSeek deepseek-chat
reviewer: Ollama qwen3:8b (local, accessed via Ollama's OpenAI-compatible endpoint)
DAG: runTasks(team, tasks) with explicit per-task assignee (see "Why runTasks" below)
Hardware: MacBook M1, 16GB unified memory, Ollama 0.20.2

Ledger 1: real run

agent       | model              | latency  | tokens in/out  | cost
------------+--------------------+----------+----------------+--------
architect   | deepseek-reasoner  |    25.3s |   1612/  2450  | $0.0009
developer   | deepseek-chat      |    68.1s | 108219/ 10408  | $0.0181
reviewer    | qwen3:8b           |   208.5s |   1432/   696  | $0 (local)

Grand total: $0.0190 USD
Wall total : 5:03

Per-run cost is $0.0190. At 100 runs/day that is roughly $57/month against the original all-Opus baseline of $450/month. The shape is different from the post's "40-70% savings" claim because the DeepSeek pricing floor is much lower than the OpenAI mini tier the original example used. Use whichever pricing matches your stack.

Why `runTasks` over `runTeam(goal)` for mixed cloud + local

I tried runTeam(goal) three times before switching. Two failures worth recording, because they will hit anyone trying to pin a role to local inference:

Short goal (under 200 chars, no complexity keywords). OMA v1.1.0 introduced "Skip Coordinator for Simple Goals" — when isSimpleGoal(goal) returns true, the coordinator skips DAG decomposition entirely and routes the whole goal to the best-matching agent. The reviewer was never invoked.
Multi-step goal that did trigger the coordinator. The coordinator generated a DAG but folded the review work into the developer's task instead of dispatching to the reviewer agent. Even adding "the reviewer agent must independently audit" to the goal text didn't move the dispatch — the coordinator's routing decision wins over goal text hints.

For mixed cloud+local pipelines where you have intentionally pinned a role to local inference, this matters: a coordinator that optimizes your local agent away costs you both the architectural intent and the cost saving. runTasks(team, tasks) is the path that guarantees per-agent dispatch with compile-time assignee typing:

await orchestrator.runTasks(team, [
  { title: 'design-api', assignee: 'architect', description: '...' },
  { title: 'implement',  assignee: 'developer', description: '...', dependsOn: ['design-api'] },
  { title: 'review',     assignee: 'reviewer',  description: '...', dependsOn: ['implement'] },
])

For goal-driven workloads where you genuinely want the coordinator to decide, runTeam(goal) is still the right call. The two APIs are complementary; pick by whether the dispatch decision is yours or the framework's.

Thinking-mode cost: same model, estimated 4-5x latency

Side experiment. I ran the same DAG two more times, only swapping the reviewer model. First with qwen3.5:9b-mlx (Qwen 3.5 9B, MLX-optimized for Apple Silicon, 8.9GB on disk) with thinking mode on its default. Then with the same model + /no_think appended to the reviewer task description (the prompt-level workaround Qwen 3 series ships with).

Ledger	reviewer config	reviewer latency	reviewer in / out tokens	wall total
1	`qwen3:8b` (no thinking by design)	208s	1432 / 696	5:03
2	`qwen3.5:9b-mlx` (thinking default ON)	1347s	21014 / 1566	24:30
3	`qwen3.5:9b-mlx` (`/no_think` workaround)	554s	38342 / 568	10:44

Ledger 2 vs Ledger 3 is the cleanest control: same model, same hardware, only thinking mode varies. Output tokens dropped 63% (1566 → 568) with /no_think, and reviewer latency dropped 59% (1347s → 554s) — despite Ledger 3's reviewer receiving 82% more input (38K vs 21K) because the developer happened to emit more in that run. Normalizing for the input difference, the pure thinking-mode cost on this M1 16GB is an estimated 4-5x reviewer latency.

For short code-review-shaped tasks (~200-word output), thinking mode is overkill. Match the local model + thinking setting to the role, not to "biggest thing I can pull".

Caveat: OMA + OpenAI-compatible can't fully kill Qwen 3.5 thinking

I tested three ways to disable thinking from OMA's side. Two failed, one partially works:

Ollama's native think: false field via the OpenAI-compatible endpoint. Did not work. Adding "think": false to a request body sent to localhost:11434/v1/chat/completions kept the model thinking for 60+ seconds, with reasoning length still 758 chars. The OpenAI Chat Completions schema doesn't define this field, and Ollama's compatibility layer drops it silently.
OMA's AgentConfig.extraBody is designed exactly for passing provider-specific params like GPT-5.5's reasoning_effort: 'xhigh'. It hits the same OpenAI-compatible endpoint, so the same outcome is the most likely (I did not retest separately; if you do, please report back).
/no_think placed cleanly at the end of the user message / task description. Partially works. reasoning length drops, output tokens drop, latency drops (Ledger 3 above). Putting /no_think in systemPrompt with extra reinforcement ("skip the block entirely") made it strictly worse — the model pushed 1337 chars into reasoning and produced empty content because the max_tokens budget was consumed by the reasoning phase.

The fully-off path goes through Ollama's native /api/chat endpoint with "think": false. On the same review prompt, that endpoint completes in 6.7 seconds. That is the theoretical ceiling for this model + hardware on this prompt. OMA's OpenAI-compatible path leaves measurable performance on the table for thinking-mode models. If you have found a way to pass Ollama's think field through an OpenAI-compatible client without bypassing the framework, please open an issue on the OMA repo. I would like to be wrong about this limitation.

What this changes about the post above

Nothing about the architectural argument changes — per-agent model assignment through AgentConfig is still the lever, runTasks vs runTeam(goal) is still the dispatch choice, and the cost-tiered framing is still the design pattern. The cost numbers in the original worked example use a representative Anthropic + OpenAI shape; the real-run ledger here is a different provider mix with a different cost floor. Both are valid reference points, and being able to swap between them without rewriting orchestration code is exactly what the post argues for.

Wrap-up: what to take from here

Mixed-model agent teams are not a clever trick. They are the right default once your team grows beyond two agents and the workload starts running on a real cadence. The savings can be material, often 40-70% against an all-frontier baseline depending on token shape, the operational cost is real (more failure modes, more variance), and the design choice that matters most is which agent gets the expensive model.

Three takeaways:

Per-agent model assignment is a design lever, not an optimization. Decide it when you decide the team. Retrofitting it later means rewriting prompts that have already drifted to match the wrong model.
Start with two providers, then add local. Step 2 captures most of the savings with two API keys and zero infrastructure. Step 3 is incremental and depends on whether you can spare the local-model latency.
onProgress is the cheapest insurance you can buy. Twenty lines of TypeScript turn token counts into dollar numbers per run. Without it, mixed-model teams silently regress and you find out from the bill.

Start with the existing repo examples: multi-model-team, providers/ollama, and cost-tiered-pipeline. Run the one closest to your workload, then add the per-agent ledger before you scale it up. If you push this pattern to production, I would like to hear what your real cost shape looks like. The reasonable model split is probably different from the examples, and the right answer is workload-specific.

About open-multi-agent. TypeScript-native multi-agent orchestration framework, MIT-licensed. Goal → Result in one runTeam() call. Three runtime dependencies. Repo: https://github.com/open-multi-agent/open-multi-agent. The framework treats the TypeScript ecosystem as a first-class target rather than a secondary port from Python.

Edits and corrections. If a price has moved since 2026-05-16 or a model has been renamed, please open an issue against the OMA repo and I will refresh the constants in the examples.

Adding Multi-Agent Orchestration to a Vercel AI SDK App

JackChen — Wed, 15 Apr 2026 17:20:14 +0000

I hit a wall recently. I had a working AI SDK app -- streamText, useChat, the whole thing -- and then I needed it to do something that a single agent can't: research a topic with one agent, then hand that research to a second agent for writing.

You can do this manually. Glue two generateText calls together, pass context around, handle the error cases. But once you want a coordinator that figures out which tasks to run in what order, or three agents sharing state, you're writing orchestration infrastructure. I didn't want to write orchestration infrastructure.

So I wired open-multi-agent (OMA) into a Next.js API route next to the AI SDK, and the two libraries turned out to work well together. This is how.

Where each library sits

AI SDK and OMA do different jobs. They don't overlap much.

	Vercel AI SDK	open-multi-agent
What it is	LLM call layer + streaming UI	Multi-agent orchestration framework
Core strength	Unified API for 60+ providers, `useChat`, `streamText`, structured outputs	`runTeam()` -- auto task decomposition, parallel execution, shared memory
Agent model	Single agent with tool loop (`ToolLoopAgent`)	Team of agents with coordinator pattern
Streaming	First-class (`toUIMessageStreamResponse`)	Not streaming-native (batch results)
Ecosystem	23,400+ GitHub stars, 10M+ weekly downloads	5,700+ GitHub stars, 3 runtime deps

AI SDK talks to models and streams tokens. OMA sits above that: given a goal and a roster of agents, it breaks the goal into tasks, runs them in dependency order, and collects the results. The two can share the same API route.

What we're building

A Next.js chat app. User types a topic, two agents collaborate on a researched article, the result streams back through useChat.

Browser (useChat)
    |
    v
POST /api/chat
    |
    +-- Phase 1: OMA runTeam()
    |     coordinator decomposes goal
    |     -> researcher agent gathers info
    |     -> writer agent drafts article
    |     (shared memory passes context between agents)
    |
    +-- Phase 2: AI SDK streamText()
    |     streams the team's output to the browser
    |
    v
useChat renders streamed response

Phase 1: OMA runs the team. A coordinator agent (created automatically by runTeam) analyzes the goal, produces a task plan, and executes it. The researcher's output lands in shared memory so the writer can reference it.

Phase 2: the coordinator's final output gets piped into AI SDK's streamText, which streams it to the browser through useChat. This is the bridge between OMA's batch output and AI SDK's streaming protocol.

Step 1: Project setup

mkdir with-vercel-ai-sdk && cd with-vercel-ai-sdk

package.json:

{
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  },
  "dependencies": {
    "@ai-sdk/openai-compatible": "^2.0.0",
    "@ai-sdk/react": "^3.0.0",
    "@open-multi-agent/open-multi-agent": "^1.1.0",
    "ai": "^6.0.0",
    "next": "^16.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

We're using @ai-sdk/openai-compatible here because the demo points at DeepSeek. If you use Anthropic or OpenAI directly, swap in their provider package instead.

npm install

Step 2: The backend

One API route, two phases. The interesting part is how little glue code the integration needs.

app/api/chat/route.ts:

import { streamText, convertToModelMessages, type UIMessage } from 'ai'
import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
import { OpenMultiAgent } from '@open-multi-agent/open-multi-agent'
import type { AgentConfig } from '@open-multi-agent/open-multi-agent'

export const maxDuration = 120

// --- Provider setup (swap this for your preferred LLM) ---
const BASE_URL = 'https://api.deepseek.com'
const MODEL = 'deepseek-chat'

const provider = createOpenAICompatible({
  name: 'deepseek',
  baseURL: `${BASE_URL}/v1`,
  apiKey: process.env.DEEPSEEK_API_KEY,
})

// --- Agent definitions ---
const researcher: AgentConfig = {
  name: 'researcher',
  model: MODEL,
  provider: 'openai',
  baseURL: BASE_URL,
  apiKey: process.env.DEEPSEEK_API_KEY,
  systemPrompt: `You are a research specialist. Given a topic, provide thorough,
factual research with key findings, relevant data points, and important context.
Be concise but comprehensive. Output structured notes, not prose.`,
  maxTurns: 3,
  temperature: 0.2,
}

const writer: AgentConfig = {
  name: 'writer',
  model: MODEL,
  provider: 'openai',
  baseURL: BASE_URL,
  apiKey: process.env.DEEPSEEK_API_KEY,
  systemPrompt: `You are an expert writer. Using research from team members
(available in shared memory), write a well-structured, engaging article
with clear headings and concise paragraphs.`,
  maxTurns: 3,
  temperature: 0.4,
}

OMA's provider: 'openai' means "use the OpenAI-compatible chat completions API." It works with DeepSeek, Ollama, Together, or anything that speaks that protocol.

Now the request handler:

function extractText(message: UIMessage): string {
  return message.parts
    .filter((p): p is { type: 'text'; text: string } => p.type === 'text')
    .map((p) => p.text)
    .join('')
}

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json()
  const lastText = extractText(messages.at(-1)!)

  // --- Phase 1: OMA multi-agent orchestration ---
  const orchestrator = new OpenMultiAgent({
    defaultModel: MODEL,
    defaultProvider: 'openai',
    defaultBaseURL: BASE_URL,
    defaultApiKey: process.env.DEEPSEEK_API_KEY,
  })

  const team = orchestrator.createTeam('research-writing', {
    name: 'research-writing',
    agents: [researcher, writer],
    sharedMemory: true,
  })

  const teamResult = await orchestrator.runTeam(
    team,
    `Research and write an article about: ${lastText}`,
  )

  const teamOutput =
    teamResult.agentResults.get('coordinator')?.output ?? ''

  // --- Phase 2: Stream result via Vercel AI SDK ---
  const result = streamText({
    model: provider(MODEL),
    system: `You are presenting research from a multi-agent team.
The team has already done the work. Relay their output faithfully
in a well-formatted way.

## Team Output
${teamOutput}`,
    messages: await convertToModelMessages(messages),
  })

  return result.toUIMessageStreamResponse()
}

What runTeam() does internally:

A coordinator agent receives the goal plus the agent roster
It produces a JSON task plan -- tasks, assignments, dependency edges
OMA's TaskQueue topologically sorts the plan. Independent tasks run in parallel; dependent tasks wait.
Each agent writes its output to SharedMemory, so the writer can see what the researcher found
The coordinator synthesizes everything into a final output

You define agents and a goal. The coordinator decides the task graph.

Step 3: The frontend

AI SDK v6's useChat handles streaming. A few things changed from v3 that tripped me up: there's no built-in handleSubmit or input state anymore, and messages use parts instead of a content string. The isLoading boolean is gone too -- replaced by a status field with four states ('ready', 'submitted', 'streaming', 'error').

app/page.tsx:

'use client'

import { useState } from 'react'
import { useChat } from '@ai-sdk/react'

export default function Home() {
  const { messages, sendMessage, status, error } = useChat()
  const [input, setInput] = useState('')

  const isLoading = status === 'submitted' || status === 'streaming'

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    if (!input.trim() || isLoading) return
    const text = input
    setInput('')
    await sendMessage({ text })
  }

  return (
    <main style={{ maxWidth: 720, margin: '0 auto', padding: '32px 16px' }}>
      <h1>Research Team</h1>

      {messages.map((m) => (
        <div key={m.id} style={{ marginBottom: 24 }}>
          <strong>{m.role === 'user' ? 'You' : 'Research Team'}</strong>
          <div style={{ whiteSpace: 'pre-wrap' }}>
            {m.parts
              .filter(
                (p): p is { type: 'text'; text: string } =>
                  p.type === 'text',
              )
              .map((p) => p.text)
              .join('')}
          </div>
        </div>
      ))}

      {isLoading && status === 'submitted' && (
        <p>Agents are collaborating -- this may take a minute...</p>
      )}

      {error && <p style={{ color: 'red' }}>Error: {error.message}</p>}

      <form onSubmit={handleSubmit} style={{ display: 'flex', gap: 8 }}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Enter a topic to research..."
          disabled={isLoading}
          style={{ flex: 1, padding: '10px 14px' }}
        />
        <button type="submit" disabled={isLoading || !input.trim()}>
          Send
        </button>
      </form>
    </main>
  )
}

Step 4: Run it

export DEEPSEEK_API_KEY=sk-...
npm run dev

Open http://localhost:3000 and try a topic.

The OMA orchestration phase takes 30-60 seconds (coordinator planning + two agents running sequentially), then the streaming phase kicks in and you get the article token by token.

One gotcha: @ai-sdk/openai v2 defaults to OpenAI's new Responses API (/responses endpoint). If your provider doesn't support it (most don't yet), use @ai-sdk/openai-compatible instead, or call provider.chat('model-name') explicitly rather than provider('model-name'). Burned about 20 minutes on this.

Under the hood

The full request lifecycle:

useChat POSTs to /api/chat with the message history
runTeam() starts. Coordinator agent receives the goal.
Coordinator produces a task plan via LLM call (JSON with tasks, assignments, dependencies)
TaskQueue topologically sorts the tasks
Researcher agent runs, output goes to SharedMemory
Writer agent runs (reads researcher's output from shared memory), produces the article
Coordinator synthesizes the final output
streamText() takes that output and streams it through AI SDK's wire protocol
useChat renders the tokens in the browser

Steps 3-7 happen inside runTeam(). That's where OMA earns its keep -- you declare agents and a goal, it handles decomposition, ordering, and state passing.

When to use what

AI SDK alone handles most single-agent work: chatbots, RAG, tool-calling agents, structured extraction. If one agent can finish the job in a single conversation loop, adding OMA would just be extra complexity.

Add OMA when you need agents collaborating -- research + writing teams, multi-perspective code review, fan-out data collection, anything where one agent's output feeds into another and the dependency graph isn't something you want to hardcode.

Trade-offs, since every library has them:

	AI SDK	OMA
Provider support	60+ (official + community)	Anthropic, OpenAI-compatible, Gemini, Grok
DevTools	Built-in DevTools, Telemetry integration	`onProgress` / `onTrace` callbacks
Community	Massive (10M+ weekly downloads)	Smaller (5,700+ stars)
Maturity	Years of production use	Newer, iterating fast

OMA's strengths are orchestration-specific: automatic task decomposition, dependency DAGs, shared memory, concurrency control with semaphores. Its provider coverage and tooling ecosystem are thinner. Whether that matters depends on your project.

Full example

The working code is in the open-multi-agent repo:

github.com/open-multi-agent/open-multi-agent/tree/main/examples/with-vercel-ai-sdk

Clone it, set your API key, npm install && npm run dev.

If multi-agent orchestration is new to you, the single-agent example might be a better starting point.