Agents Need an Ontology, Not More Context

Ask an agent about a customer and, in most setups, it does not know what a customer is. It knows a few chunks of text that mention one, a row in a CRM export, and maybe a ticket thread. It stitches those together and hopes they describe the same thing. Most of the time they do. The times they do not are the ones that end up in front of a manager.

The fix is not more context. It is a model of the business the agent can reason over: this is a Customer, this is an Order, this is how they relate, and this is what you are allowed to do with them. That model has a name. It is an ontology.

An old idea with a new job

Ontology comes from philosophy, where it is the study of what exists and how things relate. Computer science borrowed it decades ago. The semantic web described the world in RDF and OWL. Search engines built knowledge graphs so that a query about a person returns the person, not a page that mentions them. Domain-Driven Design taught a generation of engineers to start with the domain model before writing a line of infrastructure.

None of that is new. What is new is who consumes the model. For twenty years the ontology served applications and analysts. Now it serves agents, and agents need more than nouns. They need objects, relations, actions and permissions in one place, wired to the systems where the work actually happens. A diagram on a wiki does not do that. A runtime does.

Where the ontology sits

Timbal is one platform across three layers: data, intelligence and interfaces. Pull them apart and you get the stack below. Everything under the ontology knows where data lives. Everything above it decides what to do with it. The ontology is the contract between the two: the lower layers fill objects, the upper layers act on them.

Most of these layers already run in production for our customers. The ontology is the one that turns them from a set of capabilities into a model of a specific business. The rest of this post walks through it from the bottom up.

Objects start at the source

Timbal connects to more than 100 systems natively, from SAP and Salesforce to Slack and Jira, plus any MCP server. For databases inside a customer’s network, a connector runs on their side and the connection string never leaves it.

Before anyone writes a model, the connector can describe every source table: columns and types, nullability, primary keys, foreign keys, check constraints, and the comments someone left in the schema years ago. That is a first draft of the ontology, written by the systems themselves. Foreign keys are relations the source has already declared. Primary keys tell you what identity means in each system.

Syncs keep the platform’s copy fresh. They pull incrementally on a cursor column such as updated_at, merge on the primary key so an upstream change overwrites in place instead of duplicating, and run on whatever interval the use case needs. Ad-hoc queries against the source are read-only by default. Writing requires the connection’s local policy to allow it, on the customer’s side.

Then come the objects themselves: typed Python models, the same Pydantic models Timbal already uses for structured output and tool parameters. Each object declares its fields, the systems it is assembled from, and the actions that exist on it.

Five to ten objects carry most businesses. A distributor runs on Customer, Order, Shipment, Invoice and Product. A bank runs on Client, Account, Case and Document. We start there and resist the urge to model everything on day one.

Relations live where the data lives

Timbal’s data engine keeps documents and structured records in one place and queries them with one SQL plan. Vector, full-text and hybrid search are table functions, so they join like any other table. That matters more than it sounds.

“Which enterprise customers have contracts that mention early termination?” is usually a retrieval step followed by a guess about which customer each chunk belongs to. Here it is one query: SELECT c.legal_name, d.title FROM hybrid_search('contracts', $1, $2, 20) d JOIN "Customers" c ON c.id = d.customer_id WHERE c.segment = 'enterprise'. The search finds the clauses. The relation says whose they are. The agent gets objects, not fragments.

Most relations fit comfortably in the relational side of the engine. When they become many and deep, such as ownership chains, bills of materials or supplier networks, they can move to a graph. The question the agent asks stays the same.

Actions are typed, gated and written back

Reading is half the job. The other half is doing something, and that is where most agent projects get nervous. In Timbal an action is a tool. Its function signature becomes its schema, and its parameters are validated before anything runs. Which tools exist at all depends on who is asking: a ToolSet resolves them at runtime from the user’s role, so a sales agent never sees a finance action, let alone calls one.

Then come the gates. ACE checks that the call fits the playbook for this agent. Guardrails inspect the arguments and can escalate to a person. Approval gates are declarative: requires_approval=lambda amount, **_: amount > 500 on the credit note tool means that above that amount, no handler code runs until someone decides. The reviewer can approve, deny, or approve with a corrected value, and the decision is recorded with who made it and when. If a gate says no, the agent is told why and can take another path instead of crashing.

Only then does the write-back reach the system of record. Every step is a span in the trace: input, output, timing, and the approval itself. When someone asks why a credit note went out, the answer is a record, not a reconstruction.

Permissions belong to the data, not the prompt

“Do not show salaries to the support agent” is not an instruction you want to leave to a model. In Timbal, access rules live on the knowledge base. A policy filters rows and masks columns, redacting, hashing or truncating them, and is bound to roles. Policies carry compliance tags such as pci.pan and purpose tags, an audit level, and an optional break-glass that lets a session bypass the rule only through a logged escalation.

Each knowledge base runs in one of three governance modes: off, shadow or enforce. Shadow evaluates every rule and records what it would have filtered without filtering anything, so you can see the effect on real queries before you switch it on. The result is that the same Customer object looks different to support and to finance, and an agent cannot leak what it never received.

The hard part is keeping it true

Defining an ontology is a workshop. Keeping it true is a discipline. Three problems show up in every company we work with.

Entity resolution. “ACME S.L.” in SAP, “Acme” in Salesforce and “ACME Valencia” in Zendesk are the same customer, and the system has to know it, with evidence it can show and a way for a person to correct it.

We resolve with deterministic keys first: tax IDs, domains, registry numbers. Where keys are missing, hybrid search proposes candidates and a judge scores them. Below a threshold, the run pauses and asks a person, using the same human-in-the-loop machinery as approvals. Merging two records is itself an action, merge_into(), with its own gate, and every match and every correction is traced.

Drift. Systems change. Fields get renamed, a new country brings a new ERP, a team starts using a custom field nobody told you about. Mappings and objects are code, versioned in git and deployed per environment to a specific revision. Evals run as a deploy gate, so a mapping change that breaks known answers does not ship. Custom metrics defined on traces, such as the share of unresolved matches per day, can raise alarms in Slack or email before anyone notices wrong answers.

Governance. Someone has to own the definition of an Order, decide who can add an action, and sign off before an agent is allowed to write. Roles and grants come from the platform’s IAM and your identity provider. New rules, for data or for behavior, run in shadow first and are enforced once the traces look right.

Where to start

Do not model the company. Pick one use case that hurts, the handful of objects it touches and the two or three actions it needs. Map them, gate them and put them into production. The next use case reuses the objects and adds a few of its own. The ontology grows out of production, not out of a workshop, and our engineers build the first one with your team, not for it.

Why it matters now

Most agents break in production for a boring reason: they do not share the business’s idea of what things are. An ontology gives them that idea. Connectors keep it fed, the data engine keeps it queryable, and the runtime keeps every action inside the lines. Put together, agents stop being clever readers of documents and start being reliable operators of the business.

If your agents keep confusing two customers, or you want them to do more than answer questions, talk to us.