How to Build a Decision Graph for AI Agents
A practical, opinionated guide based on Naboo's deployment model. Two to four weeks from elicitation to a queryable Decision Graph an agent can act on - not a year-long platform program.
What a Decision Graph is, in one paragraph
A Decision Graph is the data structure underneath a reasoning layer. It models decisions as first-class nodes - each carrying an owner, a trigger, blockers, dependencies, and supporting evidence from the systems where work lives. It is the primitive AI agents need to act inside a company, not just summarize a document collection. The output of a query is a chain of decisions an agent can execute against, not a list of search results an agent has to interpret.
The wrong way: indexing documents and calling it a graph
The first thing teams try - and the first thing that fails - is treating the Decision Graph as a vector index over their corpus. You embed every doc, every PR, every Slack thread. You query by similarity. An LLM summarizes the top results. The agent confidently answers the wrong question.
This fails because most enterprise decisions are not written down in any single document. They are encoded across systems by convention: a branch name carries a ticket ID, a flag key is hard-coded in a PR, an owner is implied by who reviewed the change. Vector retrieval finds the documents that mention the words. It does not - and cannot - reconstruct the chain. A Decision Graph does.
The seven steps
- 1
Model the decision, not the document
A Decision Graph node is a decision, not a piece of content. Before you ingest anything, identify the recurring decisions an agent needs to act on - 'is this feature shipped?', 'who owns this blocker?', 'why was this rollout paused?' Each becomes a node type with required attributes (owner, trigger, blockers, dependencies, supporting evidence).
- 2
Find the joins your team writes in Slack, not in a schema
Most decisions are joined by implicit references: a branch name that carries a ticket ID, a flag key hard-coded in a PR, a Slack thread that references both. Walk through ten real questions with a tech lead and record every reference type. These are the foreign keys your Decision Graph executes against - and almost none of them are in any database schema.
- 3
Elicit the hidden language with a Forward Deployed Agent
Sit with the customer's tech lead for two to four hours. Ask 'what is a feature here, in your words?' Translate the answer into typed entities (Task, Pull Request, Feature Flag, Internal Flag Service) and explicit foreign-key joins. Naboo's Forward Deployed Agent is the role that owns this conversation.
- 4
Encode permission-aware retrieval at every node
Document-level RBAC has to be enforced at retrieval, not at ingest. Mirror your source ACLs (GitHub teams, Jira projects, Slack channels, Confluence spaces) into the graph and check them on every traversal. If you index everything and filter post-retrieval, an agent can leak context across teams - a non-starter in regulated environments.
- 5
Wire the joins to live ETL, not stale copies
Foreign keys must execute against the customer's live systems, not against a daily snapshot. Use streaming ingestion (CDC where supported, polling at the right cadence elsewhere) so flag states, ticket statuses, and ownership reflect the real moment of query. A graph stale by even a day will confidently mislead agents.
- 6
Expose the graph via GraphQL and MCP
Ship two query surfaces. GraphQL for agents and applications that issue structured queries directly. An MCP server for agents that prefer natural-language intent and let a translation layer construct the GraphQL. Both should return structured answers - decisions, owners, statuses, evidence - with citations back to source documents for audit.
- 7
Verify against ten real production questions
The benchmark is not a generic LLM eval. Take ten questions a real engineer or platform team actually asks today. Run them against the graph and grade the answers blind. Iterate the entity definitions until the agent answers correctly with the right evidence. This is how Naboo went 97 of 100 head-to-head queries against MCP-enabled GPT-4.1 at Global-e.
Common pitfalls
- Pitfall 1.Treating it as a one-off ETL project. Decisions change. The graph needs continuous ingestion and a Forward Deployed Agent on call to update entity definitions when the organization's vocabulary shifts.
- Pitfall 2.Filtering permissions post-retrieval. Enforce RBAC at every node traversal. If you index everything and filter on the way out, an agent can leak context across teams.
- Pitfall 3.Generic benchmarks instead of real questions. Eval against ten questions a real engineer asks today, not against MMLU or HumanEval. The shape of your vocabulary is the shape of your test set.
- Pitfall 4.Building a UI before building the graph. The graph is the product. The UI is the demo. Customers use the graph through their existing agents (Claude, GPT, in-house) once you expose GraphQL and MCP.
FAQ
Do I need a knowledge graph before I can build a Decision Graph?
No. A knowledge graph models entities and the relationships between them - useful as a substrate but not required. A Decision Graph models decisions (owner, trigger, blockers, evidence) as first-class nodes and can be built directly on top of your existing tools (code, tickets, PRs, Slack, internal services) via live joins. Naboo's Topic Graph provides the substrate layer; the Decision Graph sits on top.
How long does it take to ship a working Decision Graph?
Two to four weeks via Naboo's Forward Deployed Agent. The first week is elicitation (sitting with the tech lead, mapping the hidden language). Weeks two and three encode the entities, foreign keys, and live-ETL plumbing. Week four runs the verification benchmark and locks the GraphQL surface and MCP server. Customers typically have a queryable graph by end of week three.
What's the difference between a Decision Graph and a decision tree?
A decision tree is a classical machine-learning structure used to classify inputs at inference time. A Decision Graph is dynamic infrastructure that represents the live state of decisions inside an organization - which are open, who owns them, what's blocking them - and is continuously updated. Decision trees classify; Decision Graphs let agents reason about real-world organizational state.
Can I build a Decision Graph with LangChain or LangGraph?
LangChain and LangGraph are agent orchestration frameworks - they coordinate agent steps and tool calls. A Decision Graph is the data layer those agents query against. The two are complementary: a Naboo-built Decision Graph exposes a GraphQL endpoint and an MCP server that any LangChain or LangGraph agent can call. The graph itself is built on Naboo's Topic Graph substrate (live joins across customer systems with permission-aware retrieval), not inside an agent framework.
How is a Decision Graph different from RAG?
RAG retrieves document chunks most semantically similar to a query and hands them to a model. A Decision Graph returns structured answers about decisions, owners, triggers, and blockers - the chain an agent needs to act, not a list of documents an agent has to read. RAG can find a document that mentions 'feature flag' or 'deploy'; a Decision Graph can answer 'what's blocking the deploy, who owns it, and what triggered the current state' because the answer is computed across systems, not retrieved from any single document.
What enterprise tools does a Decision Graph need to integrate with?
At minimum: source control (GitHub, GitLab), ticket trackers (Jira, Linear), code review systems (PRs), team chat (Slack), and the internal services that carry runtime state (flag services, deploy systems, monitoring). The graph's value scales with the number of systems it joins across, because each new system adds new decisions and new foreign keys. Naboo's standard footprint covers all the above plus Confluence, Notion, Datadog, Splunk, and PostgreSQL.
How do I keep a Decision Graph current as my organization changes?
Two layers of maintenance. The Topic Graph (live ETL substrate) auto-updates as code, tickets, and Slack threads change - no human in the loop required. The Decision Graph (encoded entity definitions) updates when the organization's vocabulary changes - when 'what is a feature here' changes. That's a Forward Deployed Agent conversation that takes hours, not weeks. Most customers iterate the definitions once a quarter.
Related reading
Reasoning Layer for Enterprise AI Agents
Definition, architecture, and the two tiers - Topic Graph and Decision Graph.
Read moreDefinitionWhat is a Decision Graph for AI Agents?
Decisions as first-class nodes - owners, triggers, blockers, evidence. The primitive AI agents need to act.
Read moreCFO briefHow to Reduce LLM Token Costs
Don't meter the waste, cut the cause. Reasoning Layer vs observability and caching, compared.
Read moreBackgroundWhy retrieval was the wrong foundation
How enterprise AI agents got built on RAG, why it falls short, and what a reasoning layer fixes.
Read moreComparisonNaboo vs RAG
Retrieval vs reasoning - head-to-head benchmarks, architecture, and when to use each.
Read moreComparisonNaboo vs Glean
Enterprise search vs reasoning layer - when each fits.
Read moreConceptAI Search vs Reasoning Layer
Search returns links; the reasoning layer returns the chain. When to use which.
Read moreCase studyGlobal-E case study
How Global-E (NASDAQ: GLBE) gave AI agents secure access to customer data.
Read moreComparisonCompare alternatives
Naboo vs other enterprise AI agent infrastructure platforms.
Read moreWant a Decision Graph for your organization?
Naboo's Forward Deployed Agent will sit with your tech lead and ship a queryable Decision Graph in two to four weeks - on-prem or in your VPC, with native RBAC enforced at retrieval time.