Today we're launching Agent Controller in GA.
It's the runtime that hosts long-running agent sessions. We first built it for Mastra Code, our coding agent, and then expanded it to make it more powerful and support Mastra Factory. We now use it every day, with over 1800 commits authored by Mastra Factory this month alone. You can use Agent Controller to build your agent apps, too.
How Agent Controller works
Think of Agent Controller as the layer around the agent loop. An interaction with a single agent is simple, it takes a prompt and returns an answer. AgentController keeps this conversation open and lets you watch it, interrupt and steer. Each user gets a session with its own threads, mode, model, approvals, memory and subagents, and every client subscribed to that session sees the live state.
Back in June, we shipped it as Harness. The name made sense at first, but then we thought: if Mastra already provides tools, memory, storage, and the runtime around an agent, isn't Mastra itself a harness? So we renamed it to AgentController to better reflect what it does.
How we use it
We built Agent Controller by extracting the best parts out of Mastra Code, and then we adjusted it to build the Factory on top of it. The two products use it in different ways, which is a good test of the abstraction.
Mastra Code is used by one developer in one long session. You plan, approve, build, and steer for hours or days. The session holds the mode, the model for each mode, the granted tool permissions, and the subagents doing focused side work.
Mastra Factory runs many sessions at once. Every work item on the board opens into its own agent session, with chat, tool activity, and workspace files. People or other agents join those sessions to adjust the scope or approve actions.
What we improved
Most of the changes since June came from running Mastra Factory where the controller went from serving one developer to serving a team plus a bunch of agents.
Giving every user a separate session
When we first released Agent Controller, a few people could already share one conversation. But for the factory we needed one host to run many separate conversations at the same time. Each needed its own state, because otherwise, two users could overwrite each other's work.
In the first step, we moved the conversation-specific state from the AgentController into a Session. Now, each Session owns its conversation state, event bus, and run engine. It made independent conversations possible within one host.
Also calling createSession() with the same resourceId twice returns the same session, so a user always comes back to their own work.
Making conversation history faster to browse
In Factory, opening a thread page meant creating a session. Creating a session started its workspace, which started a sandbox. So every time someone just wanted to read old messages, the page stalled for a few seconds and consumed a sandbox slot.
We've separated those operations. Reads go straight to storage. queryThreads(), queryThreadById(), and queryThreadMessages() read threads and messages without a session, and initStorage() sets up storage without provisioning a workspace.
Optimizing memory usage
We noticed that even though functionally everything worked well, keeping the UI informed was generating a lot of traffic.
Every small streamed update triggered a full display-state snapshot. Each snapshot carried the full message plus every finished tool call, with its arguments and result. If a client wanted to keep the event history, they could run out of memory.
So we now group frequent snapshots together, keeping the ordering and the final state. We also stopped sending the full message on every update. Clients receive the initial message once, then apply deltas when they arrive.
Memory usage in long-running Mastra Code processes dropped from 2–20 GB to 300–750 MB.
How others use it
It's exciting to watch our customers run products with Agent Controller, too.
Artifact builds tools for hardware engineers:
"For Artifact, Agent Controller is the harness of harnesses. Hardware engineers use it to design actual wire harnesses on aircraft, spacecraft, and nuclear power systems."
— Corbin Klett, Co-Founder, Artifact
Frontleap uses Agent Controller behind its AI order management assistant, which helps sales reps and in-store advisors turn a customer's project into a complete, correct order in SAP.
"Behind a single chat, several agents work on the order at once. Agent Controller handles the layer between them and the user: persistent sessions, streaming, background sub-agents that report back when they're done, and visibility into token usage and cost per session. We'd otherwise have had to build and maintain that layer ourselves. Now our time goes into the order logic, not the plumbing."
— Thomas Laberge, Co-founder & CTO, Frontleap
When should you use it?
The same signs we gave in June still apply. Reach for AgentController when your agent is:
- Long-running or autonomous
- A colleague you have long conversations with
- Sent off to work on a task for more than a few minutes
- Writing and executing a lot of code, especially in a loop
- Shared by several people, or several clients, at the same time
If you want full control over a single request and response, use the Agent class.
How it fits into the harness
AgentController hosts the session. The rest of the harness capabilities support it:
- Signals let people and other agents steer a session while it runs.
- Schedules wake the agent up on a timer.
- Goals keep it working until the job is done.
- Channels forward incoming messages to the session.
Read the AgentController docs to build your own.
