> 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/ai-agent.md). # Codatum Agent (Beta) {% hint style="warning" %} This feature is currently in beta. Specifications are subject to change without notice. {% endhint %} Codatum Agent is an AI agent for investigating data, performing analyses, and carrying out business operations across Codatum knowledge and external services through natural language. It references context from the catalog, Notebooks, the web, and connected services and selects the information and tools needed for the objective. Creating and editing Notebooks is one of the methods Codatum Agent can use to organize and share analysis and research results. ## Key features * Explore tables and columns * Create and run SQL * Analyze query results * Create and edit Notebooks * Add and edit SQL blocks and charts * Reference Notebooks, tables, and saved queries * Search the web and fetch web pages * Connect to external services with [Agent Connectors](/ai-assist/agent-connector.md) Available features depend on the user's permissions, the selected AI Profile, the operation mode, and the page currently being viewed. ## Availability and enablement Codatum Agent is available on plans that include the AI Agent feature. A workspace administrator can enable it under `Workspace Settings` > `Options` > `Codatum AI`. The model and permissions used by AI Agent are configured in an [AI Profile](/ai-assist/ai-profile.md). ## Display modes ### Side panel Open Codatum Agent from the AI Agent icon. When a Notebook is open, the current Notebook and page can be used as context. ### Full page Display Codatum Agent on a dedicated page. This mode is useful for data exploration that does not start from a particular Notebook or for reviewing a long conversation. You can continue the same chat session between the side panel and full-page views. ## Operation modes ### Ask mode Performs data analysis, including query execution, but does not create or edit Notebooks. Use this mode to investigate data without modifying a Notebook. ### Agent mode Includes all operations available in Ask mode and can also create and edit Notebooks, SQL blocks, and charts. Users without Notebook write permission are restricted to Ask mode. ## Context Codatum Agent can use the following information as context: * The page and Notebook currently being viewed * Tables, Notebooks, and saved queries specified with `@` in a message * SQL blocks and charts available in the current Notebook * Automatically loaded Agent Context * Supplemental text, Notebooks, and folders configured in the AI Profile Open context usage in the input area to review automatically loaded context and its usage. See [Agent Context](/ai-assist/agent-context.md) for loading conditions and the recommended structure. ## Permissions The operations available to Codatum Agent are limited to the intersection of the following conditions: 1. **User access** * The Agent can only use Notebooks, tables, and connections that the user is allowed to view or edit. 2. **Operation mode** * Ask mode cannot use tools that create or edit Notebooks. 3. **AI Profile permissions** * Notebook scope, connections, domains for web search and fetch, and Agent Connectors can be restricted. 4. **Tool approval** * Approval can be required before executing SQL or performing an operation in an external service. AI Profile permissions do not extend the user's own access. ## Tool execution and approval Approval may be required before executing SQL, calling an MCP tool, or sending an HTTP request through an Agent Connector. The following auto-approval settings are available: * SQL execution * Configure it for all connections or individual connections. * For BigQuery, set a maximum scan size based on dry-run results. * `MCP Tool Execution` * `Connector HTTP Request` {% hint style="warning" %} When auto-approval is enabled, queries and external service operations can run without an additional confirmation. Review the AI Profile permissions and the permissions granted at the destination before enabling it. {% endhint %} ## Agent screen and settings The Agent screen provides the following operations: * Start a new chat * View chat history * Review session start time and token usage * Switch between side-panel and full-page views * Send feedback to the Codatum team The settings menu in the input area provides the following options: * Ask mode or Agent mode * Preferred connection * Auto-approval for SQL, MCP tools, and Connector HTTP requests * Auto-loading of personal, Teamspace, and Notebook Agent Context * AI Profile * Response language * Enter key behavior When starting an unrelated analysis, begin a new chat to avoid using context on conversation history that is no longer needed. ## Usage Workspace administrators can review session counts, token usage, and other information under `Workspace Settings` > `Agent Usage`. Usage data is retained for 30 days. If conversation message logging is disabled in the AI Profile, usage statistics are recorded, but message content is not displayed. ## Data handling The external LLM services used by Codatum contractually guarantee that submitted data is not used to train their models. The following information may be sent to the selected LLM service so that the Agent can analyze data and perform operations: * Messages entered by the user * Notebook and page content * References specified with `@` * Table schemas and data * SQL query results * Agent Context Codatum developers record usage time, user and workspace identifiers, errors, approximate token usage, and processing time for service quality improvement. Prompt and response content, references added with `@`, SQL results, and raw data from data sources are not recorded. Before using Codatum Agent, review your organization's AI usage policy. ## Related pages * [Agent Context](/ai-assist/agent-context.md) * [Agent Connectors](/ai-assist/agent-connector.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/ai-agent.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.