A context graph is a growing record of how an AI agent’s decisions were made and what happened afterward. It matters because it turns production agent traces into evidence you can query, evaluate against, and use to improve the agent.
For example, suppose a support agent proposes a full refund for a duplicate charge. A human reviewer approves a partial refund instead, and the customer accepts with no follow-up ticket in 30 days. The context graph records that decision, and across many similar decisions it shows where the written policy and real decisions differ.
Each record in a context graph is a decision trace. A decision trace captures five things: the trigger, the context considered, the proposal, the resolution, and the outcome.
Build better agents with Arize
Trace, evaluate, and learn. Build agents that work with Arize AX and start tracing your runs today.
Prefer open source? Try Arize Phoenix for self-hosted, open source agent observability.
Why context graphs matter for agents
A single trace helps you debug one run. A context graph helps you see patterns across thousands of decisions.
Context graphs are useful for:
- Finding override patterns: See which agent proposals humans change, and in which situations.
- Building evaluation cases: Turn recurring failures and overrides into labeled examples drawn from real work.
- Improving policy: Spot cases the written policy does not cover, based on how reviewers actually decide.
- Auditing decisions: Trace any pattern back to the individual decisions that support it.
Because the evidence comes from production, it reflects your actual traffic rather than a synthetic guess.
How a context graph is built
Start with one decision. An agent recommends a discount, routes a ticket, or approves a tool call. The decision trace records five parts:
- Trigger: What caused the decision.
- Context: What information was available, such as retrieved documents, account history, or policy text.
- Proposal: What the agent suggested.
- Resolution: How the proposal was handled, such as accepted, edited, overridden by a human, or rejected.
- Outcome: What happened as a result.
One trace on its own is a log line. Thousands of traces become a graph when they are linked by shared customers, policies, tools, reviewers, and outcomes.
Links come from evidence
No one has to design a complete schema up front. The links come from what the traces show.
For instance, one override may come from the same reviewer who handled three similar cases. Or one policy clause may appear in the context of every disputed decision last month. Each of those shared elements becomes a link.
Arize describes this build-up in how context graphs turn agent traces into durable business assets. The improvement loop is shown in the self-improving agent with a context graph.
The graph stays inspectable
The underlying record is always the decision trace. Any pattern you find can be traced back to the individual decisions behind it.
This works the same way a single trace supports debugging one run.
Where the records are stored
One common implementation, and the one Arize uses, stores decision traces in open formats in the data lake. That lets you query them alongside the rest of your trace data.
Worked example: a refund decision
A support agent proposes refunding a customer. The decision trace records:
trigger: customer reports a duplicate charge
context: billing history, refund policy v4, two prior tickets
proposal: refund the full amount
resolution: human reviewer approves a partial refund instead
outcome: customer accepts; no follow-up ticket in 30 days
One trace like this tells you little. Over many traces, a pattern appears.
Suppose the agent’s partial refund proposals are routinely changed by one reviewer in a specific billing situation. The policy text does not cover that situation. The pattern is now concrete material you can act on.
You can use it in three ways:
- Update the policy: Write the reviewer’s rule into the policy text.
- Add an evaluation case: Test whether the agent handles that situation correctly.
- Teach the agent: Feed the pattern back so the agent proposes the right action next time.
That last use is the idea behind self-improving agents and the wider agent feedback loop.
How to query and use a context graph
You do not query a context graph the way you query a fact store. Useful questions focus on decisions:
- Overrides: Which proposals from this agent version were overridden, and by whom?
- Bad outcomes: What context was present in decisions that ended badly?
- Recurring triggers: Which resolutions led to good outcomes when the same trigger came up again?
Each answer should resolve back to real traces you can read.
That inspectability is also what makes the graph useful for evaluation. Recurring override patterns become labeled examples. Recurring bad outcomes become regression cases.
Limitations
A context graph is only as good as the traces behind it.
- Logged reasoning does not prove causality: A trace shows what context was present and what was proposed. It does not prove that a particular document caused the decision.
- Coverage depends on instrumentation: Decisions you do not trace, and outcomes you never record, leave gaps the graph cannot fill.
- Outcomes can arrive late or be unclear: A ticket with no follow-up may mean success, or it may mean the customer gave up. Outcome labels need the same care as any evaluation label.
- Storage does not fix weak traces: No graph database is required. The value comes from complete decision traces stored openly, not from the storage engine.
Context graph vs. knowledge graph
This is the most common confusion.
A knowledge graph stores curated facts and relationships about entities, such as customers, products, and policies. It is usually designed against a schema.
A context graph stores what was decided, by whom or what, on what evidence, and what happened next. Its structure grows from the traces themselves.
Arize’s separate entry on adaptive knowledge graph memory covers a specific memory architecture. It is not the same thing as a context graph.
Context graph vs. RAG index
A retrieval-augmented generation (RAG) index stores content chunks for retrieval at query time. A context graph can supply evidence to retrieval, but it records decisions, not documents.
For more on RAG, see retrieval-augmented generation.
Context graph vs. system of record
A system of record is the authoritative source for business state, such as a billing platform. A context graph sits alongside it and records decision evidence.
It does not replace the system that holds the account balance.
Arize explains why this record grows in value in using context graphs to build a data moat. The open implementation work lives in the Arize context-graphs project.
Frequently asked questions
Is a context graph the same as a knowledge graph?
No. A knowledge graph stores curated facts about entities. A context graph stores decision traces, and its structure emerges as those traces accumulate and link to each other.
Do I need a graph database to build a context graph?
No. You can store decision traces in open formats in your data lake alongside your other trace data. What matters is capturing complete traces with resolutions and outcomes.
How does a context graph help with evaluation?
It points you to real production cases worth testing. Repeated human overrides, recurring failure contexts, and resolutions that worked all become evaluation examples and regression tests.
Does a context graph replace RAG or my systems of record?
No. It does not store your document corpus for retrieval, and it does not hold authoritative business state. It records how decisions were made and how they turned out.
Putting a context graph to work
Start by making sure each agent decision is traced with all five parts. The resolution and outcome are easy to leave out, and the graph is weak without them.
Pick one high-volume decision, such as refunds or ticket routing, and review its overrides first. Tools such as Arize AX can capture the traces that feed a context graph and let you query them with the rest of your data.
