What is shared state for agents?

Shared state is the canonical surface where humans and agents both read and write the same plan, the same tasks, the same drafts, the same decisions.

That is the definition. Everything else in this article unpacks what counts, what does not, and why the absence of shared state is the reason most multi-agent setups feel like a hallway full of doors that all lead to different rooms.

The thing we keep rediscovering

Anyone who has spun up more than two agents has hit the same wall. The first agent works. The second agent works. Putting them in the same project does not work. They duplicate each other. They contradict each other. They overwrite each other. They make decisions that look fine in isolation and fall apart when combined.

The reflex is to blame the models. Better prompts. Better tools. Bigger context windows. None of it solves the problem because the problem is not in the agents. The problem is that there is no single place where the work lives.

Every agent has its own memory. Its own scratchpad. Its own running record of what it thinks is going on. Two agents working on the same project are not collaborating. They are doing parallel solo projects that happen to share a name.

Shared state is the fix. One surface. Everything that matters lives there. Every agent reads from it before acting and writes to it after acting. The state is the truth. Anything not in the state did not happen.

What shared state is not

It is worth being precise, because the term gets used loosely.

Shared state is not a vector database. A vector DB is per-agent retrieval. Each agent embeds documents into its own index and queries that index when it needs background. Useful, but it is not shared and it is not state in the structural sense. Two agents with two vector DBs are still two islands.

Shared state is not a Redis cache. A cache is ephemeral key-value storage for fast lookups. It accelerates retrieval. It does not represent the work itself. Cached values disappear and the system keeps running. Shared state values cannot disappear without the system losing its memory of what happened.

Shared state is not a chat log. A chat transcript is a record of what was said. Shared state is a record of what is true right now. The transcript helps you reconstruct history. The state tells you the current plan. These are different artifacts and they answer different questions.

Shared state is not a file system. Files are containers. Shared state is structured representation of work in progress. You can store shared state in files. You can store it in a database. You can store it on a typed surface. The storage medium is not the point. The point is that there is a canonical thing every party reads from and writes to.

What lives in shared state

Five things, roughly. The list is not exhaustive but it is the working set.

Plans. The current intent. What we are trying to accomplish, in what order, with what dependencies. When a planning agent updates the plan, the next executing agent reads the new plan, not the old one.

Tasks. The unit of work. Each task has a status, an owner, an input, an expected output, a deadline if one applies. Tasks move through states as agents pick them up and finish them. The task list is the operational surface of the system.

Drafts. The output that is still being shaped. A research note. A code change. An email being composed. Drafts are read by editors and reviewers, written by drafters, and promoted to final when they are ready. Without a shared draft, every reviewer is reviewing a different copy.

Decisions. The choices that have already been made. We chose to use this approach. We rejected that one. We agreed on this scope. Decisions matter because they constrain future work. An agent that does not see the decisions will re-litigate them and waste cycles.

Contributions. Who did what. The provenance trail. The audit log of every write, who wrote it, when, and based on what. This is what makes the shared state trustworthy instead of a black box of accumulated edits.

That is the load-bearing content. Everything else is supporting infrastructure.

What does not belong

Equally important. Stuffing too much into shared state is how you get a slow, brittle surface that nobody wants to read from.

Ephemeral context does not belong. The intermediate steps an agent took to reach its output. The chain of thought. The tool calls it made along the way. These should be logged somewhere for debugging, but they do not need to be visible to every other agent reading the state. Most of it is noise.

Prompts do not belong. The system prompts and instructions that define each agent are configuration, not state. They belong in the agent's own definition, not in the shared surface. If you put them in shared state you will end up with agents reading each other's prompts and getting confused about which role they are playing.

Per-agent memory does not belong. Each agent may keep notes about how it tends to approach problems, what it has learned about the user, what its preferences are. That is local to the agent. Shared state holds the work, not the worker.

Raw model outputs do not belong. The full response from the model, including hedges and asides and exploration, is not the work. The work is the distilled action or artifact. Shared state should be the distilled version.

The principle is simple. If removing it from shared state would not break coordination, it does not belong in shared state.

Why this is the missing primitive

Most of what we call agent infrastructure today is wiring. Frameworks for tool use. Protocols for context exchange. Orchestrators that dispatch jobs. All useful. None of it answers the question of where the work actually lives.

The result is that every multi-agent system ends up inventing its own answer to that question. Some put the work in a chat thread and hope agents read enough of the history. Some put it in a hidden internal blob that humans cannot inspect. Some pass JSON between agents and reconstruct state from the latest message. All of these are workarounds for the absence of a primitive.

The primitive is shared state. A typed, persistent, append-friendly surface that humans and agents both treat as authoritative. When you have it, coordination gets cheap. Agents stop duplicating because they can see what already exists. Humans stop losing track because they can read the same surface the agents are reading. Handoffs stop dropping because the next agent picks up the state where the last one left it.

The reason this is hard is not technical. It is editorial. You have to decide what counts as state. You have to enforce that decision across every agent in the system. You have to resist the temptation to put everything in there. The discipline is the product.

How shared state changes the org

Once shared state exists, a few things happen in sequence.

Specialization gets cheap. You can have a researcher agent, a drafter agent, a reviewer agent, a publisher agent, and they all work on the same project because they all read and write the same surface. The drafter does not need to know how the researcher works. It just reads what the researcher produced.

Humans become readable. Instead of asking an agent what is going on, the human reads the state directly. The agent stops being a chat partner that has to explain itself. It becomes a coworker whose work shows up where you can see it.

Oversight becomes structural. You do not have to interview each agent about what it did. You read the state. You look at the contribution log. You see what changed, who changed it, and based on what. Trust gets built into the surface instead of being a separate effort.

Scaling stops breaking. Adding a fifth agent or a tenth does not multiply the chaos. The new agent reads the same state, writes to the same state, gets the same view. The marginal cost of another agent collapses, because the cost of coordinating was already paid by the surface.

The shape of the work

Building shared state is not glamorous. It looks like data modeling. Choosing what fields exist. Choosing what types they are. Deciding what gets exposed to which role. Writing the validation that prevents a confused agent from corrupting the surface.

The unglamorous part is the point. The glamorous part of agent work, the prompts and the demos and the impressive single-shot outputs, is what people show off. The unglamorous part, the structured surface that holds the work in place, is what makes any of that actually compound into a system.

The teams that figure this out get a flywheel. Every new agent slots into the existing surface. Every new human can be onboarded by pointing them at the state. Every new feature is a new column or a new section in the same canonical artifact. The system gets denser instead of more tangled.

The teams that do not figure it out keep rebuilding the same hallway full of doors.

Where to start

If you are running more than two agents on the same project and they keep stepping on each other, you do not have a prompting problem. You have a state problem. Pick the smallest version of shared state you can ship.

Start with one surface that holds the plan and the tasks. Make every agent read it first. Make every agent write its output back to it. Do not let any agent keep work in its own head that is not in the state. See how far that gets you.

It will get you further than you expect. Shared state is the cheapest piece of infrastructure to add and the one that returns the most coordination for the least code. It is also the one that almost nobody adds, because it is structural work and it does not feel like progress.

Add it anyway. The agents that read from the same surface are the ones that act like a team.