> For the complete documentation index, see [llms.txt](https://docs.codatum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codatum.com/ai-assist/agent-context.md). # Agent Context Agent Context is background information automatically provided to Codatum Agent. It can contain metric definitions, Notebooks to reference, and analysis considerations so that users do not need to repeat the same information in every message. {% hint style="info" %} Agent Context does not change access permissions. The information and operations available to Codatum Agent remain limited by the permissions of the user and the [AI Profile](/ai-assist/ai-profile.md). {% endhint %} ## Context types Codatum Agent automatically loads the following types of context: | Type | Configuration | When it is loaded | | ---------- | -------------------------------------------------------------------------- | ----------------------------------------- | | Personal | `.agent` folder directly under the private folder | Whenever Codatum Agent is used | | Teamspace | `.agent` folder directly under a Teamspace | When viewing a Notebook in that Teamspace | | Notebook | `.agent` page in a Notebook | When viewing that Notebook | | AI Profile | Supplemental text, context Notebooks, and context folders in an AI Profile | When using that AI Profile | For `.agent` folders under a private folder or Teamspace, all Notebooks in the folder and its subfolders are loaded. When a folder is configured in an AI Profile, all Notebooks in that folder and its subfolders are also loaded. ## `.agent` folders Open the add menu at the root of a private folder or Teamspace and select `New Agent Context folder`. This creates a `.agent` folder and an `Agent Context Index` Notebook. The generated Notebook contains a template based on the recommended structure below. A `.agent` folder can be created in the following locations: * Directly under a private folder * Directly under a Teamspace It cannot be created directly under the workspace folder or inside a regular subfolder. Notebooks in a `.agent` folder can contain text, SQL blocks, and saved results. SQL blocks can provide the Agent with standard queries or instructions for calculating metrics. ## Notebook `.agent` pages Create a page named `.agent` in a Notebook to load its content whenever that Notebook is open. Use a `.agent` page for assumptions and considerations specific to a Notebook. Use a `.agent` folder for information shared across a user or Teamspace. ## AI Profile context An AI Profile can contain the following context: * Supplemental text * Context Notebooks * Context folders To reference a context Notebook or folder, the user must have permission to view it. A user cannot use an AI Profile if it contains a Notebook that the user cannot access. You can manage editors and viewers by placing shared context Notebooks and folders in a dedicated Teamspace. ## Auto-loading settings The settings menu in the Agent input area allows users to enable or disable automatic loading for the following Agent Context types: * Personal * Teamspace * Notebook Context configured in the selected AI Profile is loaded as part of that profile. Open context usage in the input area to review the Notebooks and pages that are currently selected for automatic loading. ## Always-loaded and on-demand context There is no setting that enables lazy loading. Separate information that should always be loaded from information that should only be referenced when needed by choosing where to place the Notebooks and whether to attach them to an AI Profile. | Loading behavior | Configuration | Result | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Always load personal context | Place Notebooks in a `.agent` folder directly under the private folder and enable `Personal` auto-loading | All Notebooks in the folder and its subfolders are loaded whenever Codatum Agent runs | | Load Teamspace context | Place Notebooks in a `.agent` folder directly under a Teamspace and enable `Teamspace` auto-loading | All Notebooks in the folder and its subfolders are loaded when a Notebook in that Teamspace is open | | Load Notebook-specific context | Create a `.agent` page in a Notebook and enable `Notebook` auto-loading | The `.agent` page is loaded when that Notebook is open | | Always load context for an AI Profile | Configure plain text, context Notebooks, or context folders in the AI Profile | The context is loaded whenever the AI Profile is used. A configured folder also includes Notebooks in its subfolders | | Reference details only when needed | Place only the index in one of the locations above, store detailed Notebooks in regular folders, and link to the target pages from the index | The index is loaded automatically, while detailed Notebooks are referenced through their links based on the question | Disabling `Personal`, `Teamspace`, or `Notebook` auto-loading prevents that context from being loaded automatically. Disabling auto-loading does not convert the context to lazy loading. These settings also do not apply to context configured in an AI Profile. For the Agent to reference detailed Notebooks on demand, the user must be able to view them and the AI Profile's Notebook access must be set to `All accessible notebooks`. When it is set to `Current notebook only`, the Agent cannot reference detailed information stored outside the current Notebook. ## Recommended structure We recommend placing only an index Notebook in a `.agent` folder instead of storing all detailed knowledge there. Notebooks in a `.agent` folder are automatically loaded during Agent execution. Placing extensive specifications or past analyses in the folder consumes context for information unrelated to the current question and makes it harder to identify the relevant source. Store detailed information in regular Notebooks and folders. In the index Notebook, describe: * What information is available * When each source should be referenced * A page link to the canonical Notebook * The location of the Notebook * Keywords that can be used to find it * What to do when the information cannot be found or a decision cannot be made With this structure, Codatum Agent initially loads only the index and follows the relevant page links when detailed information is needed. {% hint style="warning" %} Always include a link to the target page, not only the Notebook name. With only a Notebook name or location, Codatum Agent cannot directly identify a page outside the `.agent` folder and must rely on search results. Open the target page in Codatum, copy its URL, and insert it as a link in the index. {% endhint %} ### Example index Notebook ```markdown # Agent Context Index ## Shared rules * Use the "KPI Definitions" Notebook as the canonical source for metric definitions * If a definition cannot be found, ask the user instead of making an assumption * Confirm the target period and time zone before creating SQL ## Knowledge Map ### Sales and orders * Source: [Sales and Order Metrics](https://app.codatum.com/workspace/WORKSPACE_ID/notebook/NOTEBOOK_ID/PAGE_ID) * Location: "Data Knowledge" Teamspace * Use for: Analyses related to sales, orders, and cancellations * Search keywords: sales, order, cancellation, GMV ### Customers * Source: [Customer Definitions](https://app.codatum.com/workspace/WORKSPACE_ID/notebook/NOTEBOOK_ID/PAGE_ID) * Location: "Data Knowledge" Teamspace * Use for: Analyses related to new customers, existing customers, and retention * Search keywords: customer, new, existing, retention ``` Replace `WORKSPACE_ID`, `NOTEBOOK_ID`, and `PAGE_ID` in the example with the URL of the actual target page. Include the Teamspace or folder name in addition to the link so that users and the Agent can understand the purpose and ownership of the source. ## Structures to avoid Avoid the following structures: * Placing all detailed specifications and past analyses in a `.agent` folder * Duplicating the same metric definition across multiple contexts * Providing only summaries without identifying the canonical source * Including rules whose update date or scope is unknown * Attempting to control access or tool execution through context instructions Configure access and tool availability through Notebook and Teamspace permissions and AI Profile permissions. ## Related pages * [Codatum Agent](/ai-assist/ai-agent.md) * [AI Profile](/ai-assist/ai-profile.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.codatum.com/ai-assist/agent-context.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.