Graph engineering: your agents have an org chart, and you should design it

A bug fix and a software release want opposite shapes. Handing both the same supervisor-and-workers diagram is how you get a system that works for one and fails quietly for the other.

Most teams adopting AI agents today get handed a single architecture — usually a supervisor delegating to workers — and told to apply it to everything. That is roughly like running a company where the incident bridge and the audit committee are forced to use the same org chart. It works for the problems that shape happens to fit, and fails for the rest. Sometimes expensively, and often invisibly.

There is a different starting point:

Companies should not be given one universal multi-agent architecture. They should be able to engineer the topology of their AI organization.

We call that discipline graph engineering. Agents and humans are nodes. Delegation, review, escalation and reporting are typed, directed edges. Once you see the organization that way, the design questions stop being vibes and start being answerable: who can talk to whom, who can command whom, where is iteration allowed, where does shared state live, who approves, and when is the work actually done.

Watch it before you read the rest

The four-minute version, recorded in a real terminal — including a live fleet where a Codex agent reviews a Claude agent's work and sends back a correction:

If the embed does not load, it is here on YouTube.

The absence of an edge is a design decision

This is the sentence the whole discipline turns on. When two agents cannot talk to each other, that is not an oversight to be fixed later — it is a guarantee you have bought.

Consider a hard debugging problem. The instinct is to give five agents the same bug and let them coordinate. What you get is correlated reasoning: five copies of one investigation, all confidently wrong in the same direction. Assign each agent a different hypothesis and remove the lateral edges between them, and the structure now guarantees something the prompt never could — that competing explanations each get a full-strength advocate. Half that work is "wasted" on wrong hypotheses by design. That waste is the price of not spending three days fixing the wrong thing.

Now consider a release. Here more communication is a defect. You want a strict, gated, acyclic pipeline where nothing skips a stage, and where the agent that certifies the build is not the agent that produced it. Same platform, same models, opposite shape — because the work is a different shape.

A bug fix, meanwhile, wants what neither of those has: a deliberately cyclic pair. Diagnose, fix, retest, repeat, until an exit condition holds. A bug is not a task; it is a conversation with a system that keeps answering.

Structure is a governance instrument

The part worth stealing even if you never touch rysh: topology gives you guarantees that hold even when an agent misbehaves, because they are properties of the graph rather than of the model.

• An agent with no edge to production cannot deploy, however convinced it is that it should.
• A verifier that shares nothing with the remediator cannot inherit its blind spots.
• A gate on the only path cannot be skipped — only passed, or stopped at.
• Two swarm agents with no lateral edge cannot converge on each other's error.

None of that depends on a model doing the right thing. That is the difference between governance engineering and governance prompting, and it is why the topology deserves the same review rigor as the code. The graph is where your actual guarantees live.

The same reasoning makes the human a node, not an exception. Mature agent organizations do not treat human input as an interruption of automation; they model people as explicit nodes with typed edges — authority, approval, task — so the dependency is designed and visible rather than ad hoc.

What this looks like in a terminal

In rysh, each agent in the video is a real, observable session in its own pane. Orders travel down as messages (rysh ansa prompt @worker-1), and results travel up onto a shared board (rysh board post). That asymmetry is deliberate: a message interrupts an agent and can be missed, while a post cannot — whoever is waiting on you polls the board.

You can watch the whole thing happen. That is most of the point. An agent organization you cannot observe is one you cannot debug, and a topology you cannot see is one you cannot review.

What this deliberately does not claim

Graph engineering is a discipline of honest structure, so the same standard applies to how we describe the platform:

• rysh's worktree isolation is file isolation on your machine — not containers, not sandboxes, not remote execution.
• The board is a monitoring view, not an audit log.
• Budget ceilings are cost controls, not security boundaries.
• The fleet hierarchy's org chart is in-house tooling on shipped primitives, not a shipped orchestrator.
• We do not claim fully autonomous multi-agent delivery. These patterns make agent organizations governable, which is a different promise from unattended.

The graph structures themselves — DAGs, actor systems, supervisors, debates, feedback loops — are not new. What is new is treating their selection and composition as a first-class engineering discipline, owned by the organization rather than fixed by the vendor.

Read the long version

The white paper works through fifteen patterns — manager–worker star, investigator–fixer loop, PR review graph, hypothesis swarm, architecture debate, incident command, release pipeline and more. Each one gets the same treatment: the organizational problem it answers, the topology that fits, how work flows through it, why that shape beats the alternatives, and the failure modes when it is misapplied. There is also a selection guide, because a real company runs several topologies at once and routes work between them.

If you take one thing from it, take this: draw your agents' org chart before you build it, and be as deliberate about the edges you leave out as the ones you put in.

The terminal multiplexer the video is recorded in is open source, Apache-2.0, at github.com/rysh-ai/rysh-cli-code — five short video tutorials are on its README, and go install github.com/rysh-ai/rysh-cli-code/cmd/rysh@latest gets you the build they were filmed against.