Graph Engineering for Agentic Workflows: A Code Graph for AI Agents

Agents fail less from bad reasoning than from retrieving the wrong context. The default way an agent finds code is text search, and text search has a blind spot that produces confident regressions. A code knowledge graph fixes that by indexing a repository as structure rather than text, and the same graph-shaped thinking applies to the workflow that runs the agent. Both are ways of being deliberate about what reaches the model and what authority it carries when it gets there.

What is a code graph for an AI agent?

A code graph is a retrieval layer that indexes a repository as structure instead of prose: functions, classes, routes, and the edges between them. Where text search matches a string, a code graph lets an agent traverse relationships. It answers two kinds of question that grep cannot, and those two operations carry most of the value.

The first is finding a symbol by name or by meaning, without knowing the file that holds it. The second is tracing the full caller and callee chain from a given function in both directions, which tells an agent everything that depends on a piece of code and everything that code depends on. Those are the questions a change actually raises.

Why does grep fail where a code graph works?

Grep finds a definition and tells you nothing about who calls it. An agent that changes a function without knowing its callers ships a regression, and it does so confidently, because from its point of view it read the relevant code. The failure is not a missing file. It is a missing edge.

The rule we follow before any edit is that the list of touchpoints comes from tracing the call graph, never from guessing or from whatever grep happened to surface. Grep stays the right tool for text, configuration, and prose. It is the wrong tool for the question that matters before any change: what breaks if I change this.

How do we use a code graph to build Askpert?

We build Askpert with coding agents, and a code graph is how those agents read our repository. This is our own engineering practice rather than something the platform exposes to sellers, and it is the reason we trust an agent to plan a change across a codebase none of us holds entirely in our heads.

The rule is written into our workflow. Before an agent proposes an edit, it looks the symbol up in the graph and traces the caller and callee chain, and the resulting touchpoint list is what the plan is built on. Because the graph carries the edges, the agent sees not just that a function exists but everything that depends on it, so a change is planned against the full set of callers before any code is edited. That single habit converts a confident guess into a verifiable list, and the same habit is available to any team willing to index structure instead of searching text.

When is the graph structurally right but practically useless?

The honest failure mode is that a graph is an index, and an index is a cache. Ours served results drawn from stale copies of the repository that were still sitting on disk from abandoned work, so a search surfaced files from directories that no longer mattered. The retrieval was structurally correct and practically useless.

Any team adopting a code graph needs two answers that most write-ups skip. First, how fresh is the index, and how do you know? A cached graph over a moving repository quietly reasons about code that no longer ships. Second, what is the index allowed to see? If it indexes everything the agent's author has touched, it can pull context the author did not intend to expose. The graph is only as trustworthy as the answer to what reached it and when.

Why is the workflow itself a graph?

A serious agent process is not one prompt. It is a set of stages with edges between them: an exploration stage maps the code, a planning stage consumes that map, adversarial critics attack the plan, an implementation stage builds it, and a review stage checks the result. That is a directed graph, and drawing it that way exposes a property that is invisible when you treat it as a checklist.

Information gains authority as it travels along an edge. A finding produced by the exploration stage arrives at the planning stage as groundwork, gets written into the plan as an established fact, and by the time the critics see it, it is a premise rather than a claim. The critics then do exactly their job, which is to attack the plan's reasoning. A false premise sails through them untouched, because nothing in the pipeline is responsible for checking it.

Where does verification belong in the workflow graph?

We lost real work to a false premise that passed the critics this way. An exploration report stated with confidence that something was absent, that sentence was copied into the plan as fact, and a whole verification argument was built on top of it. The critics checked the plan's reasoning, found it sound, and the false premise stood. One command disproved it.

The fix is a property of the graph, not of any single stage. Name the edges where a claim changes status from one agent's reading to fact, and put verification on those edges specifically. The edge that matters most is the one from exploration to planning, where a finding becomes groundwork. Nothing about a well-written research report signals that it needs checking, so the check has to be deliberate, and it has to sit where the authority flips.

Does the graph idea generalize to any agent pipeline?

The graph idea generalizes because both senses answer the same question. A code graph makes you deliberate about which context reaches the model by giving it structure instead of strings. A workflow graph makes you deliberate about what authority a claim has when it arrives, by naming the edges where a reading becomes a fact. Both are a defense against retrieving the wrong context.

The practical takeaway is a pair of habits. When an agent plans a change in code, derive the touchpoints from the call graph, never from grep. When an agent pipeline moves a finding between stages, put a verification step on the edge where a claim stops being one agent's reading and becomes the plan's premise. Retrieval that is deliberate about context, and authority that is deliberate about verification, is what keeps an agent from shipping a confident regression.