Graph Engineering: Engineering Coordination Instead of Smarter Agents

Reliable agent systems are not defined by the number of agents they contain. They are defined by the contracts that govern what moves between them. Graph Engineering: Why AI Agents Need Contracts, Not Just Prompts One agent can fix a bounded problem. Several agents can still leave a human doing the hardest work: deciding what starts next, which output is trustworthy, what state crosses a handoff, and when a failure should stop instead of retry. That is the coordination gap. The recent conversation around graph engineering is trying to name this layer of system design. The term is still fresh, and its definition is not settled. But the problem behind it is already visible in production agent systems: once work spans several agents, tools, evaluators, and human approvals, reliability depends less on the intelligence of any single model and more on the shape of the handoffs between them. Loop engineering designs how one unit of work converges. Graph engineering designs how many units of work coordinate. Graphs do not replace loops. A loop is a graph with a cycle. Production agent graphs usually contain several local loops: an implementation loop that repairs failing tests, a research loop that closes an evidence gap, or an operations loop that retries a recoverable action. The graph decides where those loops begin, what they are allowed to change, what evidence they must produce, and who is allowed to declare the wider task complete. The Problem Is Not More Agents. It Is More Relationships. The first useful agent system usually looks like this: prompt -> model -> tool -> observation -> retry That is enough for a focused task. As the work becomes longer-running, teams add a researcher, implementer, reviewer, security check, deployment gate, and human approver. The system is then described as “multi-agent,” but that label hides the real engineering question. What does the reviewer receive: a summary, a diff, test output, or the entire conversation history? Can the reviewer send work back? Can it veto a deployment? If two reviewers disagree, who resolves the conflict? Which data is shared, which data is immutable, and which node owns the final state? These are graph questions. They are not solved by adding another prompt or asking a supervisor agent to be “careful.” They require explicit control over state, routing, ownership, evidence, and authority. A Practical Vocabulary Before drawing an architecture, separate five concepts that are often collapsed into the word “agent.” An agent is a probabilistic actor. A node is any work unit: model call, deterministic function, evaluator, or human gate. A loop is a bounded feedback cycle. A graph is the topology of nodes, transitions, state, and dependencies. A governor owns decisions when nodes disagree, or risk is high. The important implication is easy to miss: not every node should be an agent. Routing, schema validation, permissions, joins, checks, and budget enforcement are usually better as deterministic software. They are faster, cheaper, easier to test, and less likely to invent a reason to proceed. A node deserves to exist when it has a distinct objective, permission set, input/output contract, or independent verifier. Draw boundaries around responsibilities, not around model count. A Graph Is More Than a Flowchart Every workflow can be drawn as boxes and arrows. That does not make it engineered. An engineering graph gives every arrow operational meaning. An edge is not simply “then.” It is a contract that states what structured state moves, what evidence is required, who owns the next state, what route type is being taken, and which budget or permissions are inherited by the destination. An edge contract carries evidence, authority, routing, and budget between work nodes. Consider the difference between these two handoffs: Researcher -> Implementer and: Researcher -> Implementer input: { verified_constraints, source_links, acceptance_tests } transition only when: each constraint has provenance authority: implementer may modify code, not acceptance tests budget: one branch, 30 minutes, no deploy permission The first is a diagram. The second is a control boundary. This is familiar terrain in distributed systems. Interfaces, ownership, retries, and failure semantics determine whether components compose. Agent systems need the same discipline, with one extra complication: some nodes are probabilistic and will confidently misread an ambiguous handoff. State Is the Real Multi-Agent Problem The hardest part of multi-node agent work is not calling models. It is deciding what state exists, who can change it, and how downstream nodes know whether to trust it. The tempting design is to give every agent the same global conversation history. That works until it does not. A speculative note becomes another node’s assumed fact. Parallel branches overwrite each other. A failed branch leaves behind state that looks complete. Context grows until nobody knows which part is evidence and which part is commentary. Use a typed state schema instead. Separate facts , proposals , decisions , artifacts , and budgets . They do not have the same trust level, so they should not live as undifferentiated text in one shared prompt. from typing import Literal, TypedDict class Evidence(TypedDict): kind: Literal["test", "source", "log", "review"] value: str source: str observed_at: str class Decision(TypedDict): status: Literal["accepted", "returned", "escalated", "stopped"] authority: str reason: str class GraphState(TypedDict): task_id: str facts: list[Evidence] proposals: list[str] decisions: list[Decision] artifacts: dict[str, str] remaining_retries: int The point is not this exact schema. The point is separation. A model’s plan should not have the same status as a failing test log. A reviewer comment should not become an accepted decision unless the graph has a route that grants it that authority. For consequential systems, an append-only evidence ledger is often safer than mutable shared memory. Nodes can add evidence; a governor or deterministic reducer decides what changes the accepted state. This makes the workflow inspectable after the fact. A Reference Graph for Software Delivery Consider a change request that affects a production service. The shape below is intentionally ordinary: intake, triage, investigation, implementation, test repair, verification, review, and a merge gate. The value is not novelty. The value is that every handoff has a reason to exist. A graph engineering control plane for agent work The implementation loop is local. It can modify code, run sandboxed tests, read resulting failures, and make a bounded repair attempt. It cannot silently lower acceptance criteria, approve its own output, or deploy to production. Independent verification is a separate node because it has a different incentive and authority. It checks the artifact against the original contract. It might run tests, inspect a diff, validate a schema, or ask a separate evaluator to review a claim. The exact technique is less important than the separation: the node that generated a result should not be the only node that accepts it. The graph also makes failure useful. An evidence gap returns to investigation. A known test failure returns to implementation. A policy conflict goes to a governor. Those are materially different routes. If they all become “ask the supervisor agent,” the system loses its ability to explain and control its behavior. The Failure Modes Worth Designing For More nodes do not automatically make a system safer. They introduce coordination failure modes that a good graph must make visible. Ambiguous ownership: two agents each assume the other approved a change. Assign one governor and explicit write authority. Shared-state races: parallel branches overwrite or invalidate each other. Use versioned state, immutable evidence, and merge rules. Context leakage: a speculative result becomes accepted fact downstream. Separate proposals from verified facts and preserve provenance. Invalid joins: branches finish, but their outputs conflict. Define join preconditions and a conflict-resolution route. Circular delegation: agents hand work around without a new observation. Bound cycles and require evidence before retrying. Consensus theater: several agents agree because they inherited the same flawed context. Use independent evidence, diverse checks, or a human gate. Unbounded fan-out: a broad task spawns costly duplicated branches. Set concurrency, spend, and deduplication limits. The warning is not “never use graphs.” It is that coordination complexity must pay for itself. A two-step task with one owner rarely needs a multi-agent topology. A typed function call and a deterministic test may be the better architecture. Workflow Graphs Are Not Knowledge Graphs The word “graph” also creates a common confusion. A knowledge graph represents connected domain information: entities, relationships, provenance, and semantics. RDF represents graph data as subject-predicate-object triples. Property-graph systems model nodes, relationships, labels, and properties. The graph is a substrate for retrieval, reasoning, and data integration. An agent workflow graph represents control: which work unit may run next, what it can receive, what evidence it must emit, and which authority can move the system into a new state. The two are complementary. A workflow graph can ask a knowledge graph for grounded context. A knowledge graph can help a verifier trace the sources behind a claim. But a retrieval graph does not decide whether a deployment is allowed, and an orchestration graph does not make facts trustworthy by itself. Start With One Loop, Then Earn the Graph A single feedback loop is a graph; a governed topology adds branching, verification, and approval. Start with one loop and earn the graph. The smallest useful architecture is usually a bounded loop with a goal, a tool surface, evidence, and a stop condition. Add graph structure only when a real coordination pressure appears. Externalize state. Replace hidden conversation history with named artifacts, evidence, and budgets. Add an independent verifier. Separate producing a result from accepting it. Introduce one explicit return route. Route evidence gaps, test failures, and policy conflicts differently. Branch only when work is genuinely independent. Parallelism without isolation often multiplies conflicts rather than throughput. Name the governor. Define the human, service owner, or policy node that resolves conflict and approves irreversible action. Measure the topology. Track where work waits, retries, escalates, fails, and consumes budget. The graph is a system, not a slide. If you cannot observe where work is cycling or why a transition fired, the topology is decorative. Actionable Takeaways Before adding another model call, ask seven questions: Can every node explain its responsibility, inputs, outputs, and permission scope? Does every edge specify the evidence required to move forward? Are facts, proposals, decisions, artifacts, and budgets represented differently? Can a verifier reject output without relying on the generator’s self-report? Are retries allowed only after new evidence or changed strategy? Is there a named governor for conflict, risk, and irreversible actions? Can an operator inspect why the graph branched, joined, escalated, or stopped? If the answer is no, the system may still work in demos. It will be difficult to operate when the task becomes ambiguous, expensive, or risky. Conclusion Prompting changes what a model is likely to say. Context engineering changes what it can see. Harness engineering limits what one run can do safely. Loop engineering helps a unit of work converge against evidence. Graph engineering adds the missing outer structure: how several bounded work units share state, hand off artifacts, run in parallel, resolve conflict, and stop under an authority visible to operators. The name may change. The requirement will not. Once a system contains more than one actor, reliability depends less on the brilliance of any individual node and more on the contracts that govern their relationships. Graph Engineering: Engineering Coordination Instead of Smarter Agents was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.