> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build your first ontology

> Create an ontology, deploy it to Tilde Cloud, and link it to an agent so the agent can read customer data and take actions under your policies.

In this guide you build a small customer ontology, deploy it, and give an agent its reads and actions as tools. It takes about ten minutes.

You need:

* A Tilde Cloud organisation, and an agent registered in it. See [Anatomy of an agent](https://trytilde.ai/docs/anatomy-of-an-agent.md).
* The `tilde` CLI, and Git.

## 1. Create the project

In **Ontology**, select **Create project**, and name it `support`. Open it, select **Environments**, then **Create environment**, and name it `production`. On the environment, select **Issue deploy token**, and copy the token.

## 2. Write the ontology

Create a repository with three files.

```bash theme={"system"}
mkdir support && cd support && git init
mkdir ontology
```

```toml tilde.toml theme={"system"}
name = "support"
```

```json ontology/package.json theme={"system"}
{
  "name": "support-ontology",
  "private": true,
  "type": "module",
  "dependencies": {
    "@bufbuild/protobuf": "^2.10.0",
    "@cedar-policy/cedar-wasm": "^4.13.0",
    "@connectrpc/connect": "^2.1.0",
    "@connectrpc/connect-web": "^2.1.0",
    "zod": "^4.1.0"
  }
}
```

`@tilde/ontology` is not listed: Tilde provides it when it builds the project, so you never install it yourself. List only the packages your own code imports.

The ontology ships two customers as reference data, so you need no connection yet. It has one object type, two reads, one action, and the policies that let people and agents use them.

```ts ontology/ontology.ts theme={"system"}
import { z } from "zod";
import { action, cedar, lake, model, object, ontology, policy, prop, query, read, readField, sql, stream, t, transactionalView } from "@tilde/ontology";

// Data: customer records, loaded on every deploy.
const customerRecords = stream("customers", {
  schema: z.object({ id: z.string(), name: z.string(), plan: z.enum(["free", "pro"]) }),
  key: "id",
  reference: [
    { id: "acme", name: "Acme Ltd", plan: "pro" },
    { id: "globex", name: "Globex", plan: "free" },
  ],
});

// A model: one row per customer.
const customers = model({
  name: "customers",
  schema: "cells",
  materialized: "cell",
  uniqueKey: "customer_id",
  columns: { customer_id: t.string(), name: t.string(), plan: t.string() },
  sql: ({ src, changes, isIncremental }) =>
    sql`SELECT payload->>'id' AS customer_id, payload->>'name' AS name, payload->>'plan' AS plan
        FROM ${isIncremental ? changes(customerRecords) : src(customerRecords)}`,
});

// The object: source-owned name and plan, ontology-owned notes.
const Customer = object("Customer", {
  id: "customer",
  key: "customerId",
  source: customers,
  properties: {
    customerId: t.string().map(sql`customer_id`),
    name: t.string().map(sql`name`),
    plan: t.enum("free", "pro").map(sql`plan`),
    notes: t.string().optional().owned(),
  },
});

const CustomerView = transactionalView("Customer", {
  key: "customer_id",
  tables: { customers },
  dependsOn: { objects: [Customer] },
});

const listCustomers = read("listCustomers", {
  description: "List every customer with its id, name, and plan.",
  kind: "read",
  input: z.object({}),
  output: z.array(z.object({ customerId: z.string(), name: z.string(), plan: z.string() })),
  reads: [Customer],
  handler: ({ ctx }) => ctx.lake.query(`SELECT "customerId", name, plan FROM Customer ORDER BY name`),
});

const customerOverview = read("customerOverview", {
  description: "One customer's plan and notes.",
  view: CustomerView,
  kind: "txRead",
  input: z.object({}),
  output: z.object({ name: z.string(), plan: z.string(), notes: prop(Customer.notes) }),
  reads: [Customer],
  handler: ({ view }) => {
    const c = view.get(Customer, view.key)!;
    return { name: c.name, plan: c.plan, notes: c.notes ?? null };
  },
});

const setNotes = action("setNotes", {
  description: "Replace the notes on a customer.",
  view: CustomerView,
  kind: "txWrite",
  input: z.object({ notes: z.string() }),
  output: z.null(),
  edits: [Customer.notes],
  reads: [Customer],
  handler: ({ input, view, ctx }) => {
    ctx.update(Customer, view.key, { notes: input.notes });
    return null;
  },
});

const peopleAndAgents = cedar`principal.type == "user" || principal.type == "agent"`;

export default ontology({
  streams: [customerRecords],
  objects: [Customer],
  views: [CustomerView],
  reads: [listCustomers, customerOverview],
  actions: [setNotes],
  policies: [
    policy("use-customers", cedar`permit(principal, action, resource is ${CustomerView}) when { ${peopleAndAgents} };`),
    policy("list-customers", cedar`permit(principal, action == ${listCustomers}, resource == ${lake}) when { ${peopleAndAgents} };`),
    policy("query", cedar`permit(principal, action == ${query}, resource) when { ${peopleAndAgents} };`),
    policy("fields", cedar`permit(principal, action == ${readField}, resource) when { ${peopleAndAgents} };`),
  ],
});
```

## 3. Deploy it

Commit, and deploy with the token from step 1.

```bash theme={"system"}
git add -A && git commit -m "Support ontology"

export TILDE_URL="https://<your-tilde-cloud-url>"
export TILDE_DEPLOY_TOKEN="<deploy token>"
tilde ontology deploy --environment production
```

Tilde installs the dependencies, validates the ontology and its policies, and rolls it out. Errors name the file and line. Check that the data arrived:

```bash theme={"system"}
tilde ontology status --environment production
```

## 4. Give the agent the ontology

**1. Connect the environment**

In **Tools**, select **Connections**, then **Tilde Catalog**, and choose **Tilde Ontology**. Select **Add account**, and enter the `production` environment's ID.

**2. Add the tools**

Open your agent in the Agent Registry, select **Tools**, then **Add tool**, and choose the connection. Switch on `listCustomers`, `customerOverview`, and `setNotes`.

**3. Allow them**

In the agent's **Capabilities** tab, add the three tools to `tools.invoke`.

## 5. Try it

Ask the agent:

```text theme={"system"}
What plan is Acme on? Add a note that they asked about SSO.
```

The agent calls `listCustomers` to find Acme's id, `customerOverview` with `{"key": "acme", "input": {}}`, and then `setNotes` with `{"key": "acme", "input": {"notes": "Asked about SSO."}}`. Each call is decided by your policies, for the agent and for the person it serves. Review the calls in the agent's [Sessions](https://trytilde.ai/docs/sessions.md) tab.

## Next steps

> [card] [Bring in real data](https://trytilde.ai/docs/ontology/sources-and-models.md)
>
> Replace the reference data with a pipeline and a connection.

> [card] [Tighten the policies](https://trytilde.ai/docs/ontology/policies.md)
>
> Limit agents, mask fields, and require approvals.

> [card] [Call third parties](https://trytilde.ai/docs/ontology/views-and-actions.md#call-third-parties)
>
> Have actions update the systems you already use.

> [card] [Add a space](https://trytilde.ai/docs/ontology/spaces.md)
>
> Show the same reads and actions to people in Live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.