Agent Architecture and Orchestration
Agent Graph Engineering
What it is
Making an agent system's execution structure explicit: nodes perform work, edges decide which step may follow, and state carries the evidence and artifacts on which those decisions depend. A node may contain ordinary code, a model request, a tool call, or an entire agent run. Graph Engineering applies to a single-agent workflow as well as coordinated agents.
An execution graph describes how work proceeds. A knowledge graph describes entities and relationships being reasoned about. Retrieving over a knowledge graph can be one node in an execution graph; the two graphs have different identities, invariants, and lifecycles.
Why the structure matters
Explicit transitions let the system require evidence before taking an action instead of hoping the model follows a narrated sequence. The useful design question is where model judgment may choose a path and where a deterministic guard must constrain it. More nodes do not automatically improve reliability: unnecessary structure adds state, routing, and recovery work to a task that one bounded agent could complete.
The design contract
Define the state schema before adding branches. For every node, specify required inputs, allowed writes, output validation, and external effects. For each edge, define its guard and what happens when inputs are absent or contradictory. Give concurrent writers separate fields or an explicit merge rule; completion order should not silently settle factual disputes.
An execution graph may contain cycles. Each cycle needs a progress signal and an allowance that bounds unsuccessful iteration. Graphs also need identifiable entry, waiting, failure, and completion states, not just a success path drawn on a diagram.
Worked example: a single-agent ticket workflow
Consider a request to create a ticket from a supplied incident. The model drafts content; code controls project eligibility, validation, approval, and submission. This is an illustrative design, not a requirement that all ticket systems use the same approval policy.
| Node | Reads and writes | Allowed next transition |
|---|---|---|
| Inspect | Read authorized project facts; store source references | Draft, or wait for missing input |
| Draft | Produce a versioned candidate payload | Validate |
| Validate | Check required fields and evidence; record issues | Review if valid; revise within the allowance otherwise |
| Review | Bind any required approval to the exact payload revision | Submit if permitted; revise, wait, or stop otherwise |
| Submit | Recheck permission; record operation intent and returned identifier | Verify, or reconcile an uncertain outcome |
| Verify | Read the created record and compare with the requested effect | Complete if matched; report a discrepancy otherwise |
State includes the objective, candidate revision, validation result, approval binding where required, remaining allowance, and an effect record. Editing the candidate invalidates its old validation and approval. The submission edge checks those bindings rather than relying on which node happened to execute last.
If submission times out, the next step is to determine whether the write happened. A checkpoint of the preceding state cannot prove that the external write did not happen. Use an operation identifier and reconciliation or backend-supported idempotency; an unresolved effect remains uncertain rather than becoming a fresh submission automatically.
Key decisions
- Which transitions are fixed, condition-based, or chosen by a bounded agent.
- What constitutes a valid state update, and how parallel branch outputs combine.
- Whether a nested agent exposes intermediate state or only a validated result to its parent.
- Which boundaries can be checkpointed and how waiting runs survive deployments.
- How changes to node contracts or state schemas affect existing continuations.
- Which path properties must hold across all traces, including denial and recovery paths.
Failure modes
- A branch reaches a write node without the checks that other paths require.
- Two parallel nodes overwrite the same artifact and the join hides the losing result.
- A revision retains approval for a payload the reviewer never saw.
- A cycle has no progress measurement and consumes the run's whole budget.
- Replay invokes a non-idempotent write after an earlier response was lost.
- A graph diagram is updated while executable guards still implement the old transitions.
Related capabilities
- Multi-agent Orchestration — coordination when nodes contain several agents
- Shared State Management — concurrent state authority
- Workflow Definition and State Machine — transition and persistence contract
- Agent Harness Engineering — services executing the nodes
- Loop Engineering — feedback and repeated work around graph executions
- Knowledge Graph — graph-structured knowledge with a different purpose
Applies: Production readiness · Design questions