Agent context

You can prepare context that the AI agent loads automatically, using notebooks. For how to use it in chat, see AI agent.

Agent context doesn't change access permissions. The information it can reference and the operations it can perform are limited to the permission scope of the user and the AI profile in use.

Agent context folder

Create a folder named .agent directly under your personal folder or the root of a teamspace. You can select New Agent Context folder from the folder menu in the left sidebar.

Location	Auto-load
.agent directly under your personal folder	Always loaded when on (the Personal user setting)
.agent directly under a teamspace	Loaded while you have a notebook from that teamspace open (the Teamspace user setting)
.agent directly under the workspace	Not auto-loaded. Loaded only if specified as context on an AI profile
.agent anywhere else	Not auto-loaded

For a .agent folder directly under a personal folder or a teamspace, every notebook within it—including those in subfolders—is loaded. This includes SQL blocks as well as text.

Agent context page

If you add a page named .agent within a notebook, its content is loaded while that notebook is open (the Notebook page user setting). You can use it to pass things like how to calculate a metric, including through SQL blocks.

Use a .agent page for assumptions specific to a notebook, and a .agent folder for information shared across a person or team.

AI profile context

The notebooks, folders, and plain text linked to the AI profile selected for the session also become context. If you specify a folder, notebooks in its subfolders are included too.

Referencing a context notebook or folder requires the user to have view permission for it. An AI profile that includes a notebook you can't view can't be used.

Auto-load settings

From Settings > User Preferences > Auto-load Agent Context in the chat input field, you can turn each type on or off.

Item	Default	Target
Personal	On	.agent directly under your personal folder
Teamspace	On	.agent directly under the teamspace the current notebook belongs to
Notebook page	On	The .agent page within the current notebook

Context configured on an AI profile isn't covered by these switches. It's always loaded as part of the settings of whichever AI profile is currently selected.

You can check which notebooks and pages are currently being auto-loaded from Context usage in the chat input field.

Always-loaded vs. loaded on demand

You can separate information that's always loaded from information referenced only when needed, based on where you place notebooks and how you link them to an AI profile.

Loading approach	Setting	Behavior
Always load personal context	Place notebooks in .agent directly under your personal folder, and turn on Personal	Loads every notebook in the folder and its subfolders whenever the AI agent runs
Load teamspace context	Place notebooks in .agent directly under a teamspace, and turn on Teamspace	Loaded while you have a notebook from that teamspace open
Load notebook-specific context	Create a .agent page in a notebook, and turn on Notebook page	Loads the .agent page while that notebook is open
Always load through an AI profile	Set it as the AI profile's plain text, context notebook, or context folder	Loaded every time that AI profile is used
Reference only when needed	Keep only an index notebook under .agent, and put details in a regular folder with a page link to it	The index is auto-loaded, and details are referenced through the link only when a question calls for it

For the agent to reference a detail notebook when needed, the user must be able to view it, and the AI profile's Notebook access must be set to All accessible notebooks. With Current notebook only, details placed outside the current notebook can't be referenced.

Index notebook

Notebooks in a .agent folder are auto-loaded. Placing a large volume of detailed specifications or past analyses there uses up context on information unrelated to the question at hand.

You can put details in regular notebooks and folders, and keep an index notebook under .agent. An index should include the following.

• What information is available
• What kinds of questions it's relevant to
• A link to the page of the notebook that's the source of truth
• Where the notebook is stored
• Keywords useful for searching
• How to handle cases where information can't be found or a judgment can't be made

WARNING

For each reference, set a link to the target page, not just the notebook name. A notebook name or storage location alone doesn't let the AI agent locate a page outside the .agent folder directly. Open the target page, copy its URL, and insert it into the index as a link.

Here's an example structure. Replace WORKSPACE_ID / NOTEBOOK_ID / PAGE_ID with the actual URL.

# Agent Context Index

## Common rules

* Treat the "KPI Definitions" notebook as the source of truth for metric definitions
* If a definition can't be found, don't guess—ask the user
* Confirm the target period and time zone before writing SQL

## Knowledge Map

### Sales and orders

* Reference: [Sales and order metrics](https://app.codatum.com/workspace/WORKSPACE_ID/notebook/NOTEBOOK_ID/PAGE_ID)
* Location: "Data Knowledge" teamspace
* When to use: analysis of sales, orders, and cancellations
* Search keywords: sales, orders, cancellations, GMV

Configurations to avoid

Avoid the following configurations.

• Putting every detailed specification or past analysis into a .agent folder
• Duplicating the same metric definition across multiple contexts
• Writing only a summary without indicating the source of truth or a reference
• Writing rules with no clear update date or scope of application
• Trying to control access permissions or tool execution scope through context

Configure access scope and available tools through notebook and teamspace permissions, and through AI profile tool permissions.