Roles, Communication & Shared State
A team is only as good as how its members are defined and how they talk. Roles, messages, and shared state are where multi-agent systems live or die.
🎯 By the end you'll understand
How to give each agent a focused role (a tailored system prompt and only the tools it needs), the three main ways agents communicate work to each other, what a shared state or "blackboard" is and when to use it instead of passing messages, the coordination problems that quietly wreck teams, and the practical rules — crisp roles, structured outputs, one source of truth, a human or critic checkpoint — that keep a team honest.
KEY INSIGHTThe one idea to take away
In 5.2 you drew the org chart. This lesson is the job descriptions and the meeting protocol — and that's where teams actually succeed or fail.
Architecture (who reports to whom) is the easy part. The reason real multi-agent systems break is almost never the diagram — it's fuzzy roles (two agents both think they own the draft), messy communication (an agent gets a wall of free text and misreads it), or contested state (two agents edit the same file and one silently wins). Get roles, messages, and state right and the architecture mostly takes care of itself.
Three things define a working team: (1) crisp roles — each agent has one job, a tailored prompt, and only its tools; (2) structured communication — agents pass parseable messages, not vibes; (3) one source of truth — everyone agrees where the real, current answer lives. Miss any one and the team drifts.
CORE CONCEPTDesigning roles: one job each
A role is just an agent that's been pointed at a narrow task. Same underlying model as everyone else — what makes it a "researcher" or a "critic" is two things you configure: its system prompt and its tools.
The system prompt is the agent's job description. From Lesson 3.2 you know a good one states a goal and its constraints. For a role, you write it tight: "You are a fact-checker. Your only job is to flag claims in this draft that aren't supported by the cited sources. Do not rewrite. Output a list of issues." That single paragraph is what turns a general model into a specialist.
The tools are the agent's permissions. Here you apply least privilege from Lesson 4.10: a researcher gets web search but not the publish button; a writer gets the draft store but not the ability to send email. Each agent can only touch what its job requires. That's not just safety — it's clarity. An agent with three tools makes better decisions than one drowning in thirty.
A role is a focused job assigned to one agent, defined by a tailored system prompt (its goal + constraints) and a minimal tool set (only what that job needs). The model is shared; the role is the configuration that specializes it.
Why bother splitting jobs at all, instead of one do-everything agent? Two honest reasons, both callbacks:
- Smaller, cleaner context per agent (Lesson 2.3). A researcher's context holds search results; a writer's holds the findings and a style guide. Neither is cluttered with the other's mess, so each stays sharp.
- Clearer evaluation. When the article is weak, a focused team lets you ask which role failed — was the research thin, or the writing flat? With one agent doing everything, you can only shrug. Roles make failure legible.
Common roles you'll assemble over and over: a manager / orchestrator (plans and routes), a researcher (gathers), a writer (produces), a critic / reviewer (finds flaws), a QA / verifier (checks against a spec or runs tests), and tool-specialists (one agent that owns a tricky API or database). You met the team shapes that arrange these in Lesson 2.7; here we're defining the members themselves.
You should be able to describe an agent's job in one sentence and list its tools on one hand. If you can't — if the description has an "and also" in it — you probably have two roles wearing one hat. Split them.
FRAMEWORKHow agents communicate: passing the work along
Once agents have roles, they have to hand work to each other. There are really only a few ways this happens, and you'll see them mixed in any real system.
Direct hand-off
Agent A's output becomes agent B's input. The researcher's findings are pasted into the writer's prompt. Simple, linear — a pipeline (2.7).
Structured messages
Agents agree on a shared schema — a fixed format like {claim, source, confidence} — so every output is machine-parseable instead of free prose. The receiver always knows where to look.
Manager routing
A central manager decides who does what next, collects results, and dispatches the next task. The hub-and-spoke version of communication.
The most important upgrade here is the jump from free text to structured messages. If the researcher returns three paragraphs of prose, the writer has to re-interpret them — and might miss a key number, or invent emphasis the researcher never intended. If instead the researcher returns a clean list of {finding, source, confidence} objects, nothing is left to interpretation. Structure is how you stop the team playing telephone.
Every hand-off is a chance to lose or distort information — and across a chain, small distortions compound (this is the cascading-errors problem from Lesson 2.9). A vague phrase from the researcher becomes a confident overstatement in the writer's draft, which the publisher then ships as fact. Longer chains amplify drift. Structured messages and a checkpoint are how you fight it.
CORE CONCEPTShared state: the team's blackboard
There are two fundamentally different ways for a team to share information. The first you've just seen — pass it in messages, hand to hand. The second is to keep a shared workspace that every agent can read from and write to. Classically this is called the blackboard: imagine a whiteboard in a war room that everyone walks up to, reads, and adds to.
Concretely, shared state is just a store outside the agents — a document, a database row, a scratchpad file, a task list — that holds the current state of the work. The researcher posts findings to it. The writer reads the findings and posts a draft. The critic reads the draft and posts notes. Nobody re-sends anything; they all look at the same board.
Shared state is a common workspace (a store outside any single agent) that all agents in a team can read from and write to. The blackboard pattern is the classic version: agents coordinate by posting to and reading from one shared surface instead of messaging each other directly. (It's the multi-agent cousin of the long-term memory store from Lesson 2.4.)
So which do you use? Each buys you something and costs you something:
| Structured hand-offs 📨 | Shared state 🗂️ | |
|---|---|---|
| How info moves | passed agent → agent in messages | posted to one common workspace |
| Big win | clean, explicit, easy to trace who sent what | no re-sending; everyone sees the latest |
| Big risk | context can get lost across the chain | conflicting edits & stale reads |
| Best for | linear pipelines, clear stages | many agents on one evolving artifact |
Shared state's appeal is obvious: in a hand-off chain you keep re-pasting the same context into each prompt; with a blackboard you write it once and everyone reads it. But that convenience invites trouble. If two agents write to the same field at the same time, whose version wins? If the writer drafts from findings the researcher has since revised, the writer is working from stale data. Hand-offs don't have these problems — but they can quietly drop context that wasn't explicitly passed along.
Use structured hand-offs for clean linear flows. Reach for shared state when several agents collaborate on one evolving artifact — and the moment you do, declare one source of truth so there's never a question of which copy is real.
WEAKNESSCoordination problems that wreck teams
When you put autonomous agents in a room together, a predictable set of failures shows up. None are exotic — they're the same problems human teams have, minus the social cues that usually defuse them.
- Conflicting edits. Two agents change the same thing and one overwrites the other. The lost change is invisible — nobody errors, the work is just silently wrong.
- Who decides? The writer wants to keep a sentence; the critic wants it cut. With no clear authority, they ping-pong, or the last one to write simply wins by accident. Someone has to hold the final call.
- Deadlock / ping-pong. Agent A waits for B, B waits for A — or the writer-and-critic loop never converges because each keeps "improving" the other's work forever. Without a stop condition, the team spins.
- Accountability. When the final output is wrong, which agent introduced the error? In a tangle of hand-offs and shared writes, it can be genuinely hard to tell — and what you can't attribute, you can't fix.
Every agent and every hand-off you add multiplies the chances of conflict, drift, and deadlock. This is the coordination overhead from Lesson 2.7 showing its teeth. The fix is rarely "more agents" — it's clearer roles, structured messages, and an explicit decider.
SEE ITDesign your team
Goal: produce a researched article. Toggle roles on or off, pick how the agents communicate, and watch the team diagram redraw. The readout tells you the team's strengths — and warns you if a key role is missing or if you've over-staffed a job that doesn't need it. Everything is deterministic; there's no "right" answer baked in, just consequences of your choices.
Note: the warnings are hand-authored heuristics, not a simulation — but they reflect the real tradeoffs above: a missing critic means no independent check, and piling on roles for a simple goal just adds coordination overhead.
PRACTICALThe roles cheat-sheet
A reference for the roles you'll reach for most. Notice the last column — every good role exists to prevent a specific failure. That's how you know it earns its seat.
| Role | Its one job | Tools it needs | What it prevents |
|---|---|---|---|
| 🎛️ Manager / orchestrator | plan, route tasks, synthesize results, hold the final call | delegate-to-agent; read shared state | chaos & ping-pong — gives the team a decider |
| 🔎 Researcher | gather facts and sources on a narrow angle | web/doc search (read-only) | unsupported claims — grounds the work in evidence |
| ✍️ Writer | turn findings into clear, structured prose | read findings; write to draft store | disorganized output — produces the actual artifact |
| 🧐 Critic / reviewer | find flaws, gaps, and unsupported claims | read draft + sources (no write) | confident-wrong shipping — an independent check |
| ✅ QA / verifier | check the result against a spec or run tests | run checks/tests; read spec | spec drift — confirms it meets requirements |
| 🧰 Tool-specialist | own one tricky API, DB, or system | just that one system's tools | scattered, error-prone tool use — centralizes expertise |
PRACTICALFour rules that keep a team honest
Everything above distills into four practices. If you remember nothing else when you go to build (which is next, in Lesson 5.4), remember these.
Define crisp roles
One job per agent, one-sentence description, tools on one hand. If you can't name what an agent prevents, it may not deserve a seat.
Use structured outputs between agents
Agree on a schema so hand-offs are parseable, not prose. Structure is the cheapest defense against telephone-game drift.
Keep one source of truth
For any shared artifact, declare exactly where the real, current version lives. No ambiguity about which copy is canonical.
Put a checkpoint on important results
A critic agent and/or a human reviews before anything ships. An independent check is what catches the confident-but-wrong mistake (2.9).
Crisp roles, structured messages, one source of truth, a checkpoint, and a clear decider. That's not a fancy framework — it's just what any functional team needs. Agents don't change the rules of teamwork; they just remove the social glue that papers over its absence, so you have to design it in on purpose.
WEAKNESSCommon mistakes to avoid
If two agents both "kind of" own the draft, they'll step on each other, duplicate effort, and you won't know which one to fix when it's wrong. Each role needs a sharp boundary and a single owner for each piece of work. "And also" in a job description is a smell — split the role.
Passing a wall of prose from agent to agent forces each receiver to re-interpret it, and interpretation drifts. A key number gets dropped; a hedge becomes a certainty. Use a shared schema ({finding, source, confidence}) so nothing is left to guesswork across the chain.
When several agents read and write the same artifact with no canonical copy, you get conflicting edits, stale reads, and silent overwrites. Always name one place where the current, real version lives — and make every agent read from and write to that, not their own private copy.
KEY INSIGHTWhere this connects in your course
- Tools (2.2) — "agent-as-tool" communication is just a tool call where the tool is another agent. Same plumbing you already know.
- Context windows (2.3) — the deep reason for focused roles: each agent gets a small, clean context instead of one cluttered one.
- Memory / stores (2.4) — shared state is the team-scale version of an external store: write it down, let others read it back.
- Multi-agent systems (2.7) — the team shapes (orchestrator, pipeline, critic) that arrange the roles you're defining here.
- Cascading errors (2.9) — the telephone-game drift across hand-offs; structured messages and checkpoints are the antidote.
- System prompts (3.2) — each role is a tailored system prompt: a goal plus constraints, written narrow.
- Least privilege (4.10) — give each agent only the tools its job needs. Safer, and it makes the agent's decisions cleaner.
- Build it in code (5.4) — next lesson you'll wire real roles, hand-offs, and a shared store into a running multi-agent system.
Hold the through-line: roles + communication + shared state. The architecture from 5.2 is the skeleton; this lesson is the muscle that actually makes it move.
GLOSSARYKey terms introduced
- Role
- A focused job for one agent, defined by a tailored system prompt (goal + constraints) and a minimal set of tools.
- System prompt (per agent)
- The job description for a single agent in a team — what it's for, its constraints, and how to format its output.
- Hand-off
- Passing work from one agent to another: agent A's output becomes agent B's input.
- Structured message
- Output in an agreed, parseable format (a shared schema) so the receiver doesn't have to re-interpret free text.
- Shared state / blackboard
- A common workspace all agents can read from and write to, instead of (or alongside) passing messages directly.
- Source of truth
- The one canonical place where the current, real version of a shared artifact lives, so there's never doubt about which copy is real.
- Coordination
- Managing how agents share work and state — and avoiding conflicting edits, deadlock, and unclear accountability.
ACTIVE RECALLCheck your understanding
Answer in your own words first, then reveal.
1What two things define an agent's "role," and what does each give you?›
A tailored system prompt (its goal + constraints — recall 3.2), which turns a general model into a specialist; and a minimal tool set (least privilege — recall 4.10), which is both safer and keeps the agent's decisions clean. Same model underneath; the role is the configuration.
2Why prefer structured messages over free-text hand-offs between agents?›
Free text forces each receiver to re-interpret it, and interpretation drifts — a number gets dropped, a hedge becomes a certainty. Across a chain those distortions compound (cascading errors, 2.9). A shared schema like {finding, source, confidence} makes outputs parseable so nothing is left to guesswork.
3Shared state vs. structured hand-offs — give the main win and main risk of each.›
Shared state (blackboard): win — no re-sending, everyone sees the latest; risk — conflicting edits and stale reads. Hand-offs: win — clean, explicit, easy to trace; risk — context can be lost across the chain. Use hand-offs for linear flows; use shared state when many agents work one evolving artifact — and then declare one source of truth.
4Name two coordination problems a multi-agent team faces, and one practice that helps.›
Any two of: conflicting edits (silent overwrites), no clear decider (ping-pong), deadlock (loops that never converge), unclear accountability (can't tell who broke it). Helpful practices: crisp roles, structured messages, a single source of truth, an explicit decider, and a critic/human checkpoint on important results.