Use a knowledge base

Connect knowledge bases to agents and apps, choose read or read and write access, set agent exposure, and see how agents read the files at run time

A published knowledge base does nothing until something reads it. You connect it to agents, which read it on every run, and to apps, whose AI builder uses it as reference material.

Connect a knowledge base to an agent

You can connect from either side; both create the same connection.

From the knowledge base

Open the knowledge base, then the Agents tab. Under Connected agents, pick an agent, choose its Access, and click Connect an agent.

This tab is also where you change an agent’s access later, or click Disconnect.

From the agent

Open the agent, then the Data access tab. Under Connected contexts, pick a knowledge base and click Connect context. You can also do this in the Agent Builder’s configuration pane, under Knowledge bases.

A knowledge base connected from the agent side starts with Read access. To grant write access, change it on the knowledge base’s Agents tab.

Changes apply from the agent’s next turn.

Connecting requires the Admin or Builder role. From the agent side, you can only connect knowledge bases you are allowed to edit.

Choose the access mode

Each connection has an access mode (ContextAccessMode). For read and write access, it also has a write policy.

Access (UI)	Access mode	What the agent can do
Read	READ	Read the published files. This is the default.
Read & write	READ_WRITE, write policy AUTO	Read, and update files in the knowledge base on its own. Each write is a new version.
Read & write (ask first)	READ_WRITE, write policy ASK	Read, and propose writes that a person approves in an approval card before they happen.

Read & write (ask first) only works where a person can see the approval card: web chat. On every other route — chat apps such as Slack, webhooks, automations — the agent cannot write to that knowledge base at all for that run. Use Read & write for agents that run unattended.

A knowledge base an agent can write to is that agent’s memory. See Memory for how agents write and how to review what they wrote.

Set the agent’s exposure

An agent’s Exposure (contextExposure) decides which knowledge bases it sees at all. It is set on the agent’s Data access tab, under Connected contexts.

Exposure (UI)	Value	What the agent’s sandbox holds
Connected only	ATTACHED	Exactly the knowledge bases connected to this agent, and nothing else. Raw workspace files are not mounted; the agent reads them on demand with its workspace_data tools, if those are enabled.
Whole workspace	ALL	Every published knowledge base in the workspace plus the raw workspace files, whatever is connected. The connection list is a label, not a boundary.

• Every new agent uses Connected only. An agent with nothing connected starts every run with no shared context.
• Whole workspace exists only on agents that had it before exposure control was introduced. Once such an agent is switched to Connected only, it cannot be switched back.
• An agent with a data scope is always Connected only.
• Exposure never grants write access. Only a Read & write connection does.

How the agent sees the files

At the start of each run, DataGen mounts the knowledge bases the agent may read into its sandbox, read-only, one directory per knowledge base:

/mnt/context/contexts/
├── <slug-a>/        # knowledge base A, latest published version
│   ├── README.md
│   └── ...
└── <slug-b>/        # knowledge base B
    └── ...

The agent’s system prompt lists each mounted knowledge base by path and name, so you do not need to tell it where to look. You can still point it at a specific file in its instructions:

## Reference material

Answer policy questions from the knowledge base at
/mnt/context/contexts/<slug>/. Start with its README.md, and cite the file
you used in every answer.

What to expect at run time:

• Always the live version. A publish, a rollback or an agent write shows up on the agent’s next turn.
• Read-only. Nothing an agent writes under /mnt/context/ is kept. An agent with Read & write access changes a knowledge base only through its write_context tool, and its own mounted copy does not show the change until the mount refreshes.
• Treat agent-written files with care. Agents are told that files in a knowledge base may have been written by other agents, and to check the version history when something looks wrong.

When an agent can read several knowledge bases, the Description of each one is what it uses to choose. Keep descriptions short and specific.

Connect a knowledge base to an app

Apps use knowledge bases at build time only. Open the app, then the Tools & knowledge tab, and connect knowledge bases under Knowledge. You can also connect them in the App Builder’s configuration pane, under Knowledge bases.

• The App Builder’s sandbox mounts the connected knowledge bases read-only under /mnt/context/contexts/, as background for writing the app.
• The published app never sees them. If the running app needs the information, have the builder write it into the app’s own files.
• App connections have no access mode and no exposure setting: the builder reads exactly what is connected.

See Build an app.

Next

Memory

Let agents record what they learn in a knowledge base, and review what they wrote.

Skills

Give agents reusable procedures with reviewed skills.