Graph Engineering for AI Agents: A Practical Guide to Tasks, Dependencies, Inputs, Outputs & Completion Checks
The most important idea in workflow graph engineering is simple:
an AI agent should not receive a vague goal and be left to improvise the entire business process. A production workflow usually needs a deliberate structure that explains what must happen, what depends on what, what information enters each task, what each task must produce, which paths are allowed, and what evidence proves that the overall job is actually complete.
Think of a workflow graph as the map of execution. A task is a meaningful piece of work. A dependency explains why one task must wait for another. Inputs describe what a task is allowed to consume. Outputs describe what it must hand forward. A completion check answers the most important operational question: “What evidence tells us that the business outcome was really achieved?”
This article teaches those ideas from beginner intuition to production design using one fictional enterprise scenario: an AI system that handles a supplier invoice exception. The example is intentionally invented; it is a teaching model, not a description of a private company implementation.
Imagine a school project where one child gathers information, another checks the information, another writes the answer, and a teacher approves the final result. The workflow graph is the plan that says who goes first, who waits, who can work at the same time, and what “finished” means.
The exact boundary between a graph, an agent runtime, a harness, and an application varies by architecture. Anthropic describes workflows as systems in which code defines the orchestration path, while agents dynamically direct their own process and tool usage. Current agent frameworks also expose their own orchestration abstractions, so the graph concepts in this article should be treated as engineering ideas rather than as one universal framework standard. Anthropic’s workflow and agent discussion is a useful reference point for that distinction.
- What Graph Engineering Actually Means
- Start With the Goal and Define What Success Means
- Turn the Goal Into the Right-Sized Tasks
- Give Every Task Clear Inputs and Outputs
- Connect Tasks With Dependencies
- Add Routes, Branches, Parallel Work, Joins, and Loops
- Design Completion Checks, Not Just a Final Node
- Place the Model, Agent, Graph, Harness, Tools, State, and Sandbox Correctly
- Design Failure Recovery and Human Decisions
- Build Security Into the Graph
- Test and Trace the Graph
- Enterprise Rollout
- Common Mistakes
- ❓ FAQ
- 🔗 References & Further Reading
- 📝 Summary
A graph should make the intended execution path easier to explain, test, constrain, and recover than an unstructured agent loop.
01
What Graph Engineering Actually Means
The word graph can sound mathematical, but the practical idea is straightforward. A workflow graph represents units of work and the relationships between them.
A node usually represents a task such as “validate invoice,” “retrieve purchase-order data,” “compare values,” “request approval,” or “post the approved adjustment.” An edge represents a permitted transition or dependency: “after validation, continue,” “if the comparison fails, route to review,” or “run these two information-gathering tasks before reconciliation.”
That is different from a knowledge graph. A knowledge graph primarily represents relationships among entities and facts. A workflow graph primarily represents execution and control flow. It is also different from a graph database, which is a storage technology rather than a workflow design concept.
| Element | Question it answers | Example | Evidence |
|---|---|---|---|
| Goal | What outcome are we trying to achieve? | Resolve an invoice exception | Business success criteria |
| Task | What meaningful work must happen? | Compare invoice to PO | Task output |
| Dependency | What must happen before something else? | Validation before posting | Known prerequisite |
| Completion check | How do we know the job really finished? | ERP update confirmed | Observed evidence |
The graph therefore becomes a kind of executable explanation. A well-designed graph lets another engineer answer questions such as:
- Which task owns this decision?
- What information is required before the task starts?
- What happens when an input is missing?
- Which tasks can run in parallel?
- Which actions require stronger authorization?
- What evidence proves that the workflow is complete?
Those questions are why graph engineering matters. The objective is not to make the system look sophisticated. The objective is to make execution explicit enough to reason about.
The process contains multiple tasks, branching conditions, external actions, approvals, retries, or state that must survive across steps.
02
Start With the Goal and Define What Success Means
Many weak workflows begin with technology: “Which agent should I create?” or “Which tool should the model call?” Graph engineering should begin one level higher: What outcome must be achieved?
“Clean the room” is a goal. “Put books on the shelf, place clothes in the basket, remove trash, and make sure the floor is clear” is a task breakdown. “Your room is ready when you can walk from the door to the desk without stepping on anything” is a completion check.
For AI systems, a useful goal should describe a business outcome and a boundary. Compare these two instructions:
“Handle this invoice.”
Stronger goal:
“Resolve the invoice exception by validating the invoice, reconciling it with authoritative purchasing data, obtaining required approval for any financial adjustment, recording the approved outcome, and confirming that the resulting transaction state is correct.”
The stronger goal contains a hidden but important idea: completion is an observable state, not a feeling.
Before creating nodes, write a small goal contract:
- Outcome: What business result should exist at the end?
- Scope: Which records, users, systems, and actions are inside the workflow?
- Exclusions: What is explicitly outside the workflow?
- Success evidence: What facts must be observable before completion?
- Stop conditions: When must the workflow stop rather than continue?
For the fictional invoice scenario, the goal contract might say that the workflow may inspect invoice, purchase-order, receipt, and approval information but may not make a payment or modify supplier master data. That single boundary already changes the graph design.
Goal: resolve an invoice mismatch safely.
Not enough: “The agent produced a recommendation.”
Better: the mismatch was classified, supporting records were reconciled, the correct business route was selected, any required approval was recorded, the authorized transaction was executed, and the resulting external state was re-read and verified.
Notice that the model's generated recommendation is only one intermediate artifact. The business outcome exists outside the model.
A project conversation starts with “build an agent” before anyone has written down what completed success actually looks like.
03
Turn the Goal Into the Right-Sized Tasks
A task is a bounded unit of meaningful work. It should have a reason to exist, a clear input boundary, an expected output, and a recognizable end state.
Imagine packing a suitcase. “Pack everything” is too large to reason about. “Put one sock into the suitcase” is too small to be useful as a workflow step. “Pack clothing” is a more meaningful unit because it has a clear purpose and result.
A useful task usually passes four questions:
- Purpose: Can I explain why this task exists?
- Input contract: Does it have a bounded set of required inputs?
- Output contract: Does it produce something the next task can use?
- Failure boundary: Can I identify what went wrong if this task fails?
For the invoice scenario, a reasonable decomposition is:
2. Validate required invoice fields
3. Retrieve purchase-order details
4. Retrieve receipt or fulfillment evidence
5. Reconcile invoice, PO, and receipt
6. Classify the exception
7. Select the permitted business route
8. Prepare recommendation or adjustment request
9. Obtain approval when required
10. Execute the authorized action
11. Re-read the external record
12. Verify completion evidence
13. Notify the relevant party
This list is not automatically the final graph. It is the task inventory. The graph still needs to answer which tasks depend on one another, which can run together, which paths are conditional, and which actions are reversible.
There is an important design trade-off here. Combining too many activities into one giant task makes failures opaque. Splitting every tiny operation into a separate node makes the graph noisy and can add unnecessary coordination overhead. The right boundary is usually where the task has a meaningful purpose, a useful output, a distinct failure mode, or a distinct policy boundary.
“Retrieve PO” is a sensible task because it has a distinct external dependency and produces data needed later. “Set the HTTP header” is usually an implementation detail inside that task rather than a business-level graph node. The graph should describe meaningful execution boundaries, not every line of code.
Current LangGraph documentation uses a similar decomposition idea: discrete nodes represent steps, with different categories such as LLM steps, data steps, action steps, and user-input steps. That is a framework-specific implementation, but it illustrates the broader engineering principle that graph nodes should have understandable responsibilities. LangGraph: Thinking in LangGraph
A workflow contains a vague “agent step” that seems to do everything. Split it until each important responsibility has an inspectable boundary.
04
Give Every Task Clear Inputs and Outputs
A graph becomes much easier to reason about when every important task can answer two questions: “What do I need?” and “What do I promise to produce?”
A recipe is easier to follow when the cook knows which ingredients are required and what each step produces. “Make something tasty” is not an interface contract. “Take two eggs and produce beaten eggs” is much clearer.
In a workflow graph, inputs can come from several places:
- Request input: information supplied by the user or triggering system.
- Prior-task output: a value produced earlier in the graph.
- External data: information retrieved from an authoritative system.
- Persistent state: information intentionally retained across steps.
- Authorization context: identity, scope, approval, or policy information needed before an action.
The last category is particularly important. Authorization is not merely “another prompt input.” A system should not tell the model, “You may update this record because the prompt says so,” and then rely on the model to enforce the rule. Authorization belongs in deterministic controls outside the model wherever practical.
Task: ReconcileInvoice
Inputs:
- validated_invoice
- purchase_order
- receipt_evidence
- policy_context
Outputs:
- reconciliation_status
- mismatch_reasons[]
- confidence_notes
- recommended_route
Must not:
- update ERP records
- release payment
That final “must not” line is valuable because it turns a vague expectation into a boundary. If the reconciliation task is not authorized to change financial state, its tool set should reflect that restriction.
For state design, one useful principle documented in current LangGraph guidance is to keep state focused on durable data and decisions rather than storing prompt-formatted text everywhere. That makes the workflow easier to inspect and allows different nodes to construct their own immediate working context. See the state-design discussion in LangGraph documentation.
Risk → An untrusted document field is accidentally treated as an instruction or authorization input.
Control → Represent external content as data, keep authorization separate, validate structured values, and enforce permissions at the tool or downstream service boundary.
Remaining risk → A model can still misinterpret legitimate data or produce an incorrect recommendation, so downstream validation remains necessary.
A node seems to rely on “whatever happens to be in the conversation.” Define the minimum explicit inputs and the exact output that the next stage needs.
05
Connect Tasks With Dependencies
A dependency answers a very practical question: why can't task B safely run yet?
Not all dependencies are the same. Recognizing the type prevents accidental coupling.
| Dependency type | Meaning | Invoice example | Design implication |
|---|---|---|---|
| Data | B needs data produced by A. | Reconciliation needs validated invoice data. | Define the data contract. |
| Control | B must occur after A. | Posting cannot happen before approval. | Make the transition explicit. |
| Policy | A required authorization or condition must exist. | Financial adjustment requires approval. | Do not encode policy only in model instructions. |
| Side-effect | An earlier action changes what a later action should do. | A posted adjustment changes the record that must be verified. | Re-read authoritative state after the action. |
One of the most useful graph-engineering habits is to ask whether an arrow represents a real prerequisite or merely a convenient sequence.
Suppose “retrieve PO” and “retrieve receipt evidence” both depend on a validated invoice identifier. They do not necessarily depend on each other. If they can run safely at the same time, the graph can express parallelism rather than forcing a serial chain.
START
↓
Validate Invoice
├───────────────┐
↓ ↓
Retrieve PO Retrieve Receipt
└───────┬───────┘
↓
Reconcile
This is a small example of dependency-aware design. The graph becomes faster without becoming less understandable because the parallel tasks have independent work and a clear join point.
A dependency should also carry a consequence. If receipt retrieval fails, does reconciliation wait? Can the graph continue with a degraded decision? Should it retry? Should it route to manual review? The dependency itself does not answer those questions; your error policy does.
If the purchase order is unavailable for a temporary technical reason, the workflow may retry the retrieval task. If the purchase order exists but its supplier ID conflicts with the invoice, retrying is unlikely to fix the business problem. That path should probably move into a validation or review route instead.
A graph has become a long serial chain simply because the original designer drew the steps in the order they thought about them.
06
Add Routes, Branches, Parallel Work, Joins, and Loops
Once tasks and dependencies are clear, the graph begins to describe possible execution paths.
A simple workflow is a straight line:
A conditional route looks more like:
├─ no mismatch → Ready for standard processing
├─ small mismatch → Approval route
└─ unresolved mismatch → Human investigation
The important point is that the graph should define what routes are legitimate. A model can help classify a situation, but a reliable system should validate that the resulting route is one of the permitted routes.
There are four recurring graph patterns worth understanding.
1. Sequential work
Use it when a later task genuinely needs a result from the earlier task.
2. Branching
Use it when different conditions require different paths.
3. Parallel work with a join
Use it when independent tasks can run simultaneously and a later task requires the combined result.
4. Controlled loops
Use them when the system may need another attempt or refinement, but always define a stopping rule.
Loops are where an apparently helpful agent can become operationally dangerous. “Keep trying until it works” is not a production completion rule.
A bounded loop should define at least one of the following:
- Maximum attempts.
- Maximum elapsed time.
- Maximum external actions.
- A measurable condition that ends the loop.
- A fallback route when progress stops.
Risk → A loop repeatedly invokes an external action, causing duplicate updates, cost growth, rate-limit pressure, or uncontrolled side effects.
Control → Separate retryable reads from non-idempotent writes, set attempt limits, use idempotency controls where appropriate, and route repeated failure to a known recovery path.
Remaining risk → A technically successful retry can still produce the wrong business outcome if the underlying decision was wrong.
Current agent-system guidance also illustrates why different graph shapes exist: Anthropic documents sequential chaining, routing, parallelization, orchestrator-worker patterns, and evaluator-optimizer loops as distinct patterns with different trade-offs. These are architecture patterns rather than mandatory building blocks. See Anthropic’s documented workflow patterns.
A workflow diagram contains branches or loops that cannot be explained with a clear condition and stop rule.
07
Design Completion Checks, Not Just a Final Node
A common beginner mistake is to assume that the workflow is complete because it reached its final node. That is not necessarily true.
Imagine a child is told to water a plant. Filling the watering can is not completion. Pouring water into the soil is closer, but the real question is whether the plant actually received the intended amount of water without flooding the pot.
The final node describes what the workflow attempted to do. A completion check verifies what the system can observe afterward.
For the invoice scenario, “Execute approved adjustment” is an action. “Verify the authoritative transaction now contains the expected adjustment, the record identifier matches the case, and the workflow has a durable audit reference” is a completion check.
A strong completion design usually checks several layers:
- Task completion: Did the node return a valid result?
- Graph completion: Did all required prerequisites and branches complete?
- Business completion: Does the requested outcome now exist?
- External-state confirmation: Did the authoritative system reflect the expected result?
- Evidence completion: Do we have enough trace or audit information to explain what happened?
Action: call the ERP update operation.
Weak completion: the API returned HTTP success.
Stronger completion: the returned transaction reference is recorded, the authoritative record is re-read, the expected business values are present, and the case is marked complete only after that verification passes.
This pattern is particularly important for external systems because an API response and the resulting business state are not always the same thing. Network failures, retries, delayed processing, duplicate submissions, and downstream asynchronous behavior can complicate the meaning of “success.”
complete =
validation_ok
AND reconciliation_ok
AND required_approval_recorded
AND authorized_action_confirmed
AND authoritative_state_verified
AND audit_reference_present
otherwise → workflow remains incomplete or enters a recovery path
This is one of the strongest ways to make an agent workflow testable. Instead of asking “Did the agent seem successful?”, you can ask “Which completion predicate failed?”
A project declares success because the last LLM response was generated, even though the actual business action still needs verification.
08
Place the Model, Agent, Graph, Harness, Tools, State, and Sandbox Correctly
The terms around agentic systems are often mixed together. For graph engineering, it helps to give each one a narrow mental model.
| Component | Simple meaning | Typical responsibility |
|---|---|---|
| Model | The reasoning or generation engine. | Interpret text, classify, generate, reason, propose actions. |
| Agent | A model configured to pursue a task with tools and runtime behavior. | Decide or act within its allowed operating scope. |
| Workflow graph | The map of tasks and permitted execution relationships. | Route, sequence, join, loop, pause, and complete. |
| Harness | The runtime and control layer around an agent or workflow. | Execution, tool dispatch, limits, state handling, telemetry, runtime controls. |
| Tool | An interface to an external capability. | Read data, perform an action, or interact with a service. |
| State | Persisted information needed to understand and continue execution. | Carry facts, decisions, identifiers, statuses, and recovery information. |
| Sandbox | An isolation boundary for execution when one is used. | Contain files, commands, or other execution capabilities within defined limits. |
These are conceptual boundaries, not a universal product architecture. One framework may combine some of them into one runtime object. Another may expose them separately.
For example, OpenAI's current Agents SDK documents agents, tools, handoffs, guardrails, sessions, human-in-the-loop support, and tracing. That is one concrete implementation model. It should not be treated as proof that every agent system must use those exact abstractions. OpenAI Agents SDK documentation
For graph engineering, the key question is not “Which box is the coolest?” It is “Which responsibility must be explicit so that the system can be tested and controlled?”
Model
↓ proposes / classifies / generates
Agent
↓ decides or acts within allowed scope
Workflow Graph
↓ determines permitted path
Harness
↓ enforces runtime behavior and limits
Tool
↓ interacts with an external system
External System
↓ produces authoritative state
State Store
↓ preserves what the workflow needs to continue
Do not ask the model to enforce a boundary that the surrounding system can enforce deterministically.
Design discussions keep using “agent,” “workflow,” “runtime,” and “tool” as if they were interchangeable.
09
Design Failure Recovery and Human Decisions
A production graph is not defined only by its happy path. It is defined by what happens when something goes wrong.
A useful classification is:
| Failure | Example | Possible graph response |
|---|---|---|
| Transient technical | Temporary timeout | Retry within a bounded policy |
| Invalid data | Missing supplier identifier | Route to data correction or human review |
| Decision uncertainty | Evidence conflicts | Escalate instead of guessing |
| Policy failure | Approval is missing | Pause until the authorization requirement is satisfied |
| Unexpected system failure | Unknown exception | Stop safely, preserve state, alert operations |
This classification matters because retrying is not a universal error strategy.
Retrying a read operation may be reasonable. Retrying a financial write without idempotency protection can create a duplicate effect. Asking the model to “try again” when required business evidence is missing can turn a data-quality problem into an incorrect decision.
Human intervention should also be modeled as a real workflow state, not as an emergency email sent from somewhere outside the graph.
PrepareRecommendation
↓
CheckApprovalRequirement
├─ not required → ExecuteAuthorizedAction
└─ required → AwaitHumanApproval
├─ approved → ExecuteAuthorizedAction
├─ rejected → CloseAsRejected
└─ needs changes → ReviseRecommendation
Current LangGraph documentation demonstrates one implementation approach in which execution can pause for human input and resume with persisted state. Again, that is a framework-specific feature, but the graph-engineering principle is broader: waiting for a human should be an explicit state transition. LangGraph human-input and recovery example
Risk → A human approval step becomes meaningless because the review screen hides the actual action or uses untrusted text to describe what will happen.
Control → Show the concrete action, target, material parameters, and authorization context in a trusted interface, and enforce approval in the execution layer rather than merely asking the model to respect it.
Remaining risk → Human review itself can be mistaken or rushed, so approval is one layer of control rather than a universal safety guarantee.
The workflow must survive waiting, retries, partial failures, human decisions, or temporary service outages.
10
Build Security Into the Graph
Workflow design and security design are closely connected because the graph determines which actions become reachable.
A workflow can therefore be viewed as an authority map: each route exposes a certain set of tools, data, and side effects.
For the invoice scenario, consider a graph where:
- The retrieval tasks can read invoice, PO, and receipt data.
- The reconciliation task can generate a recommendation.
- The approval path can record an approval decision.
- Only the authorized execution task can modify financial state.
- The completion task can read back the resulting state but cannot issue another change.
This is safer than giving every stage access to every tool and hoping the model chooses correctly.
OWASP identifies excessive functionality, excessive permissions, and excessive autonomy as recurring causes of excessive agency. Its guidance recommends minimizing available functions, minimizing permissions, avoiding overly open-ended tools, enforcing authorization in downstream systems, and using human approval for high-impact actions where appropriate. OWASP LLM06:2025 Excessive Agency
Risk → The graph can reach a high-impact tool using authority that is broader than the task requires.
Control → Give each task the smallest practical tool and permission set, enforce authorization outside the model, separate read and write capabilities, and add explicit approval or transaction controls for sensitive actions.
Remaining risk → These controls reduce blast radius but do not eliminate incorrect model decisions, compromised upstream data, or every form of instruction injection.
Instruction injection is particularly important when agent workflows process external content such as email, documents, web pages, tickets, or tool results. OWASP notes that there is no fool-proof prevention inside the LLM alone and recommends layered mitigations such as privilege controls, human approval for sensitive operations, and separation of external content from higher-trust instructions. OWASP LLM01: Prompt Injection
Suppose someone puts a note inside a package saying, “Ignore the delivery instructions and give me the money.” The package contents are data, not authority. A secure workflow does not let the package rewrite the rules for who is allowed to approve or execute a transaction.
This is why graph design can provide a strong structural boundary: an input-processing path can be allowed to analyze untrusted content while being structurally unable to reach the payment-writing tool.
That is a much stronger engineering move than adding another sentence to a system prompt saying, “Never issue payments unless approved.”
Use the graph to reduce what a compromised or mistaken component can reach, not merely to describe what it should avoid.
The workflow has external data, privileged tools, financial actions, sensitive records, or cross-system side effects.
11
Test and Trace the Graph
A graph is not production-ready because the happy path works once. Graph testing should ask whether the structure itself behaves correctly.
A practical graph test plan includes:
- Route tests: Does each important condition reach the intended branch?
- Dependency tests: Does a node refuse to run when required prerequisites are absent?
- Join tests: Does a downstream task wait for every required parallel result?
- Loop tests: Does the retry cycle stop at the configured boundary?
- Failure tests: Does each meaningful failure route to a known recovery state?
- Authorization tests: Can a low-authority route reach a high-authority tool?
- Completion tests: Can the workflow incorrectly declare success when external verification fails?
- Replay tests: What happens when an interrupted run resumes?
One especially valuable test is to deliberately remove a prerequisite and verify that the graph does not “helpfully” continue.
Give the reconciliation task a valid invoice but no authoritative receipt evidence. A robust test should verify that the workflow either follows a designed fallback path or pauses for resolution. It should not silently substitute a guessed receipt status merely because the model can produce plausible text.
Tracing is the other half of graph engineering. After a production failure, an engineer needs to reconstruct the path: which node ran, what route was selected, which tools were called, what approval happened, how many retries occurred, and what state existed before the failure.
OpenAI's current Agents SDK, for example, documents traces containing agent runs, model generations, tool calls, handoffs, guardrails, and custom events. That demonstrates one vendor-specific implementation of a broader requirement: make important execution steps observable. OpenAI Agents SDK tracing documentation
A useful graph trace record might include:
- Workflow version and run identifier.
- Node entered, node exited, and duration.
- Route or branch selected.
- Tool identity and result status.
- Retry count and error category.
- Approval event and authorization context.
- Completion predicates that passed or failed.
Risk → Logs become a secondary leakage channel because they contain prompts, document content, tool arguments, identifiers, or secrets.
Control → Log the minimum information needed for diagnosis and auditing, redact sensitive values, protect trace access, and apply retention rules appropriate to the data.
Remaining risk → Even carefully filtered telemetry can contain sensitive metadata, so observability must be treated as a data-governance concern.
A team can see the final answer but cannot reconstruct why a particular path, tool, approval, or failure occurred.
12
Enterprise Rollout
Moving a graph from a development experiment to enterprise operation is primarily a control and lifecycle problem.
The graph definition itself becomes a production artifact. Changes to task boundaries, tools, routes, completion checks, or authorization rules can change system behavior even when the underlying model remains unchanged.
A practical rollout path is:
- Observe: run against representative cases without taking consequential actions.
- Bound: enable a narrow subset of read operations and low-impact outputs.
- Approve: introduce human-controlled gates for consequential actions.
- Expand: increase automation only after route, completion, failure, security, and operational evidence is satisfactory.
The graph should be versioned like software. When the graph schema changes, existing state and in-flight runs may need a migration strategy. When a tool changes its input or output contract, dependent nodes need compatibility testing.
Enterprise ownership should answer:
- Who owns the business outcome?
- Who owns each external tool?
- Who can change the graph?
- Who approves new permissions?
- Who investigates failed or suspicious runs?
- How long is execution and audit data retained?
NIST's AI Risk Management Framework and its Generative AI Profile provide broader risk-management guidance for organizations, while the graph-specific controls described here are an engineering interpretation focused on execution, authority, verification, and recovery. NIST AI Risk Management Framework
Changing a graph can change who gets called, when an approval happens, which data is exposed, how many times a tool can run, and what counts as completion. Treat graph changes with the seriousness of application-logic changes.
At larger scale, teams also need budgets. These can include execution time, tool-call counts, retries, model usage, concurrency, or maximum workflow duration. The exact limit should come from the business and technical risk of the workflow rather than from a decorative number.
A graph is moving beyond a prototype and multiple teams, systems, identities, approvals, or regulated records are involved.
13
Common Mistakes
| Mistake | Why it happens | Consequence | Correction |
|---|---|---|---|
| One giant agent node | The team starts from the prompt instead of the process. | Poor observability and unclear failures. | Split meaningful responsibilities into explicit tasks. |
| Too many tiny nodes | Trying to model every implementation detail. | Noisy graph and unnecessary coordination. | Keep implementation details inside meaningful task boundaries. |
| Hidden dependencies | The designer assumes context will “just be there.” | Ordering bugs and brittle execution. | Declare required inputs and prerequisites. |
| Broad tool access | Convenience during development. | Larger blast radius from mistakes or injection. | Use task-specific tools and least privilege. |
| Retry everything | Retries feel like a universal reliability mechanism. | Duplicate side effects or wasted cost. | Classify failures and bound retries. |
| Trust the final message | The LLM response looks complete. | Business state may remain unchanged or incorrect. | Verify authoritative external state. |
| No cancellation path | Only the happy path was designed. | Work can continue after the business no longer wants it. | Model cancellation, expiration, timeout, and safe stopping explicitly. |
One mistake deserves special attention: approval fatigue. If every route requires human approval, people eventually stop inspecting the details and begin clicking mechanically. Approval should therefore correspond to meaningful authority boundaries, not simply compensate for poor graph design.
Another mistake is designing only forward motion. Real systems need cancellation, timeout, recovery, and sometimes compensation. A graph that can proceed but cannot safely stop is incomplete.
Risk → The workflow continues executing after the original goal is cancelled, the data becomes stale, or a security policy changes.
Control → Add cancellation checks, expiration rules, authorization re-checks around sensitive actions, and safe terminal states.
Remaining risk → In-flight operations may already have reached external systems, so cancellation cannot necessarily undo effects that have already occurred.
A graph looks elegant on paper but has not been challenged with missing inputs, stale state, duplicate execution, cancellation, permission failure, and external-service outages.
14
❓ FAQ
What is a workflow graph in AI agent engineering?
A workflow graph is an explicit representation of tasks, dependencies, routes, state transitions, and completion conditions that determines how an AI-enabled workflow can progress.
How do I decide whether something should be a separate task?
Make it a separate task when it has a meaningful responsibility, a useful input and output boundary, a distinct failure mode, or a distinct policy or authorization boundary.
What is the difference between a task dependency and a route?
A dependency explains why a task must wait or what prerequisite it needs, while a route describes which permitted path the workflow should take under a particular condition.
What makes a completion check different from the final node?
The final node describes an attempted operation, while a completion check verifies observable evidence that the intended business outcome actually exists and any required audit evidence is present.
Should every AI agent use a fixed workflow graph?
No. Fixed workflow structure is useful when important paths can be defined in advance, while more dynamic agent behavior can be appropriate for tasks whose steps genuinely cannot be predicted beforehand. The choice should follow the task and its risk.
15
🔗 References & Further Reading
The following primary sources were consulted to verify architecture-specific and security-related claims used in this article. The teaching structure, analogies, running example, task contracts, pseudocode, tables, and explanations in this article are original. Vendor and project names remain the property of their respective owners.
- Anthropic — Building effective agents — workflow versus agent distinctions and documented workflow patterns.
- OpenAI Agents SDK — agents, tools, handoffs, guardrails, sessions, human-in-the-loop, and tracing concepts.
- OpenAI Agents SDK — Tracing — current tracing concepts and execution observability.
- LangGraph — Thinking in LangGraph — nodes, state, routing, errors, persistence, and human-interruption patterns.
- OWASP GenAI Security Project — LLM06:2025 Excessive Agency — excessive functionality, permissions, autonomy, least privilege, downstream authorization, and human approval.
- OWASP GenAI Security Project — LLM01: Prompt Injection — layered defenses and the limits of relying on the LLM itself.
- NIST — AI Risk Management Framework — broader organizational AI risk-management context.
Source note: framework behavior, APIs, and platform guidance can change. Links above should be rechecked at publication time, especially when an implementation depends on a particular SDK release.
16
📝 Summary
- Start with the goal: define the business outcome before choosing agent components.
- Turn the goal into tasks: use meaningful boundaries rather than one giant agent step or hundreds of tiny nodes.
- Define inputs and outputs: every important task should have an understandable contract.
- Make dependencies explicit: distinguish data dependencies, control ordering, policy requirements, and side-effect relationships.
- Make routes intentional: branches should represent permitted paths, not accidental model behavior.
- Bound loops: retries and refinement cycles need stopping conditions.
- Verify completion: a final node finishing is not the same as the business outcome being confirmed.
- Separate responsibilities: the model, agent, graph, harness, tools, state, and sandbox can have different jobs.
- Design recovery: real workflows need retries, pauses, cancellation, fallback, and failure states.
- Secure the reachable surface: minimize tools, permissions, and autonomy, and enforce authorization outside the model.
- Test the graph itself: route coverage, failure paths, authorization, state recovery, and completion checks belong in testing.
Good graph engineering turns “the agent should figure it out” into a system that can explain what it is allowed to do, what it needs, where it can go, how it recovers, and how it proves that the job is finished.
Comments
Post a Comment