Declared Graphs vs Nested in Agent Engineering
Declared graphs beat nested structures for agent engineering because they make the agent’s state, dependencies, and execution order explicit and inspectable, which is essential for debugging, reuse, and parallel execution. In an agent system, a declared graph is a data structure that defines nodes (tasks or tools) and edges (transitions) separately from the agent’s control flow, while a nested approach embeds those relationships inside the agent’s code as hierarchical calls. This article explains why the explicit graph model wins for building robust, maintainable agents, and where nested designs still make sense.
Background: How Agent Structures Evolved
Early agent frameworks often used nested function calls: an agent’s behavior was a tree of sub-agents, each calling others directly. This is intuitive—it mirrors how a human might break a task into subtasks. But as agents grew to handle multiple tools, dynamic planning, and human-in-the-loop checkpoints, the nested model became brittle. The community shifted toward graph-based orchestration, popularized by frameworks like LangGraph and Temporal, because graphs separate the “what” (nodes) from the “how” (edges). This separation enables features that nested calls cannot easily provide: dynamic rerouting, parallel branches, and explicit state persistence.
How Declared Graphs Work
A declared graph is a data structure, often defined in JSON or YAML, that lists nodes and edges. For example, a simple research agent might have nodes: search, summarize, and final_answer, with edges: search → summarize, summarize → final_answer. The agent runtime reads this graph and executes nodes in order, but the graph itself is just data—it can be edited, validated, or even generated by another agent. This is in contrast to a nested implementation where the same logic would be written as:
def agent():
results = search()
summary = summarize(results)
return final_answer(summary)
That nested code is fine for a fixed pipeline, but it hard-codes the order and makes it hard to insert a human-approval step between search and summarize without rewriting the function.
Key Advantages of Declared Graphs
- Inspectability: You can print the graph, visualize it, or log which node is running. With nested calls, you only see the current call stack, not the whole plan.
- Reusability: A graph can be a subgraph inside another graph. In nested code, you would have to refactor to share a subtree.
- Dynamic control: A graph can be modified at runtime—add a node, skip an edge—based on intermediate results. Nested code requires conditional logic scattered throughout.
- Parallelism: Graphs with multiple incoming edges to a node can run those branches concurrently. Nested code can do this only with explicit threading or async, which complicates the logic.
- Persistence and recovery: A graph’s state can be saved between nodes, allowing an agent to pause and resume after a failure or a human review. Nested calls lose that state unless you build a custom checkpointing system.
When Nested Still Makes Sense
Nested structures are not always wrong. For a simple, linear agent with two or three fixed steps, a nested function is easier to read and has less overhead. Also, when the agent’s behavior is truly hierarchical—like a manager delegating to sub-agents that never interact—a tree is a natural fit. For example, a customer-support agent that first classifies a request, then calls a specialized sub-agent for billing or technical issues, can be implemented cleanly with nested calls. The problem arises when the hierarchy becomes a DAG (directed acyclic graph) with shared sub-tasks or feedback loops. Nested code cannot express a loop without adding a while-loop around the whole tree, which breaks the tree metaphor.
Common Problems with Nested Approaches
- Hidden dependencies: In nested code, a sub-agent might implicitly rely on a global variable or a side effect from a sibling call. This is hard to track and test.
- Testing difficulty: To unit-test a nested agent, you must mock the entire call stack. With a graph, you can test a single node in isolation because the graph provides the inputs and outputs explicitly.
- Debugging nightmares: When a nested agent fails, you get a stack trace that shows where, but not why the agent chose that path. A graph can log the path taken and the state at each node.
- Scaling limits: As you add tools and conditions, nested code becomes a tangled web of if-else and function calls. The graph remains a flat list of nodes and edges, which is easier to reason about.
How to Choose Between Them
Start with the simplest structure that meets your needs. If your agent has fewer than five steps and no branching or loops, use nested functions. If you anticipate any of the following, move to a declared graph:
- You need to visualize the agent’s flow for stakeholders.
- You plan to add human-in-the-loop checkpoints or tool calls that might change the flow.
- You want to run multiple branches in parallel.
- You expect to reuse parts of the agent in other agents.
- You need to persist the agent’s state across sessions or crashes.
In practice, most production agents benefit from a graph because even a simple “research and answer” agent benefits from being able to retry a failed search without restarting the whole pipeline.
Real-World Example: Research Agent
Consider an agent that answers questions by searching the web and summarizing results. A nested version might be:
def answer(question):
results = search(question)
if not results:
results = search(question, retry=True)
summary = summarize(results)
return summary
This works, but what if you want to add a step that asks the user to clarify the question if the first search returns nothing? In the nested version, you must add a loop. In a graph, you would have nodes: search, check_results, ask_user, summarize. The edge from check_results can go to ask_user if results are empty, and then back to search with the clarified query. The graph makes this flow explicit and testable.
Frequently Asked Questions
Is a declared graph always faster than nested code?
No. The graph itself adds a small overhead for node dispatch and state management. For simple, linear pipelines, nested code is faster. The advantage of graphs is not speed but maintainability and flexibility. In most agent applications, the bottleneck is network calls or LLM inference, so the overhead is negligible.
Can I mix nested and graph approaches?
Yes. Many frameworks allow a node in a graph to be a nested agent. For example, a graph node might call a sub-agent that itself uses nested logic. This is a good pattern: use graphs for the overall orchestration and nested calls for simple, self-contained sub-tasks.
What is the learning curve for declared graphs?
If you are familiar with state machines or workflow engines, graphs are intuitive. The main challenge is thinking in terms of nodes and edges rather than function calls. Most graph frameworks provide visualization tools, which help. Expect a few days to become comfortable, but the payoff is easier debugging and reuse.
Do declared graphs work with LLM-based agents that plan dynamically?
Yes. The graph can be generated by the LLM itself. For example, the LLM can output a JSON graph describing the steps it will take, and the runtime executes it. This is a common pattern in advanced agent frameworks. The graph becomes the LLM’s “plan” that can be inspected and edited by a human.
What are the downsides of declared graphs?
They can be overkill for trivial agents, and they require a runtime that understands the graph format. Also, if you define the graph in a static file, you lose some of the flexibility of code—though you can generate the graph programmatically. Finally, debugging a graph can be harder if the framework does not provide good tracing, but most modern frameworks do.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.