--- title: "Run the Modeler Agent" slug: "configure-and-run-the-modeler-agent" description: "Transform your enterprise planning with the Modeler Agent, turning natural language requests into production-ready models while ensuring data governance." tags: ["Modeler Agent", "Enterprise Planning", "Data Integration"] updated: 2026-10-19T08:39:21Z published: 2026-10-19T08:39:21Z canonical: "kb.pigment.com/configure-and-run-the-modeler-agent" --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.pigment.com/llms.txt > Use this file to discover all available pages before exploring further. # Run the Modeler Agent With the Modeler Agent, teams can describe the outcome they want in natural language, and the Agent translates this into production-ready models. It's purpose-built for enterprise planning and understands business context: Metrics, formulas, data relationships, and governance constraints. > [!TIP] > 🎓 Pigment Academy > > Check out the courses available in the [Learning Path for the Modeler Agent](https://academy.pigment.com/path/the-modeler-agent)! ## Before you begin > [!WARNING] > ⚠️ Important > > The Modeler Agent makes permanent changes to your model. These changes are recorded in [Application History](/v1/docs/track-application-update-history) and are attributed to the Member who ran the Agent. ### How the Modeler Agent can help you You can chat with the Modeler Agent about any modeling and design need you may have. It can handle various kinds of tasks, such as: - simple tasks: *“Import a .csv file into a new Metric called week12_sales”, ”Calculate FTE by month”, “Help me write a formula”, “Explain what this Block is doing”*. - performance improvement: *“rank Blocks by average/total execution time”*. - Workspace-level complex tasks, where the user presents a business objective: *“Create a Data Hub containing the Dimensions I need for a headcount use case. Then create a headcount planning app, with Metrics using Dimensions from the Data Hub."* ### Access rights and permissions Members need the `Access AI Agents` and `Configure Blocks` permissions to interact with the Modeler Agent. For general information on permissions, see [About Roles, Permissions, and Access Rights](/v1/docs/roles-permissions-access-rights), and for specific information on Pigment AI permissions, see [Set up Pigment AI](/v1/docs/pigment-ai#set-up-pigment-ai). Access rights for Blocks created by the Modeler Agent are determined by the Member participating in the chat. For example, if a Member with access rights only for UK data requests a Block, it only includes UK data. Access rights are not re-checked when other Members view the output. > [!NOTE] > ℹ️ Note > > For those using [Test & Deploy](/v1/docs/test-deploy), the Modeler Agent is available with the following conditions: > > - in [managed Applications](/v1/docs/introduction-test-deploy#managed-applications), in **Ask** mode only. See [below](/v1/docs/configure-and-run-the-modeler-agent#how-to-work-with-the-modeler-agent) for more information on the modes. > - in unmanaged Applications, all modes are available. > - on [the homepage of Workspaces](/v1/docs/pigment-workspace-navigation#pigment-agents) with at least one unmanaged Application, all modes are available. However, if you select the **Build** or **Plan & Build** modes on the Workspace homepage and request changes to a managed Application, you see an error message. ## How to work with the Modeler Agent To make your request to the Agent: 1. [Open the](/v1/docs/pigment-agents#find-the-agents) AI sidebar, and select **Modeler** from the tiles. If it is not there, ensure it is [activated](/v1/docs/pigment-agents#activate-and-manage-the-agents) and you have the relevant permissions (see above). 2. Tell the Modeler Agent what you want it to do in natural language. You can also import XLSX files and CSVs, paste text, upload images and record voice notes containing your requirements. For more information, see [Upload files to the Agents](/v1/docs/pigment-agents#upload-files-to-the-agents). 3. Answer any questions the Agent raises. 4. Choose between the operating modes below. If the Modeler needs to switch modes to fulfil your request, it asks you explicitly before switching: 1. For tasks requiring multiple action items, waypoints and approvals, opt for **Plan** **& Build** mode. The Modeler Agent produces a structured action plan for validation and requires your go-ahead at the waypoints in real time as it executes the plan. 2. Choose **Build** mode for tasks such as: 1. CRUD (create, read, update, delete) operations on Dimension and Transaction Lists, Metrics, and Properties, including from CSV imports 2. formula generation, including functions, Dimension alignment and modifiers 3. Calendar setup and management 3. To ask questions without it changing the model, choose **Ask** mode. The Agent can help you understand the model, propose solutions for modeling problems, and create operational to-do lists for you to implement. > [!NOTE] > ℹ️ **Note** > > - The mode last used in existing Chats persist when you reopen them. > - New conversations start with whatever mode you picked last. 4. Select **Auto-accept actions** to allow the Modeler to proceed without validation at key waypoints. Deletions are an exception: you must always validate deletions even if Auto-accept is selected. 5. For Plan & Build and Build modes, review and refine the plan in chat before execution: 1. *“Modify point #2 of the action plan: do not create a new dimension, reuse the existing one"* 2. *“Add a variance % column in the first view"* 3. *“Explain why this metric might be inefficient and how it could be improved"* 6. (*Optional*) You can download the plan as a markdown file. For this, open the plan and select **Download as Markdown**. 7. The Agent may request further approval of certain actions. Select **Accept** by each action or, to bulk accept, select **Accept all** in the chat input field. 8. (*Optional*) Interrupt the Agent while it prepares an answer if necessary. Select the **Stop answer** button, the blue box in the Chat input field. 9. (*Optional*) The Agent may invite you to review the output of a new or updated formula before implementation. Select ***f*** **Preview** in the Agent conversation to open the [Formula Playground](/v1/docs/analyze-optimize-formulas-formula-playground), where the formula is pre-loaded. Choose one of the following actions: 1. **Accept** or **Reject** the formula. You are returned to the Agent conversation. 2. Edit and re-run the formula in the Playground. To return to the Agent conversation, select **Save** or **Discard changes**. 10. Ask the Agent to create Boards to show your new model. It knows to follow certain design and structure best practices but you can: 1. Have the Agent suggest new Boards based on your work. 2. Say which Views you want to include. 3. Ask it to create new KPIs if they are needed. 4. Request a themed navigation Board that connects to all the Boards in your Application. > [!NOTE] > ℹ️ Note > > The first time the Modeler Agent receives an Application-related question from any Member using the Application, it runs a one-time set-up that can take a few minutes. The time taken depends on the number of Blocks in the Application. This set-up only runs once per Application, not per Member. ## Key capabilities You can ask the Modeler Agent for the latest details on what it can do. Below are some of its key capabilities. ### Action planning - Turn modeler intent into Pigment logic - Edit plans conversationally before execution ### Modeling - Create/edit all Block types (Dimension and Transaction Lists, Metrics, Properties) - Manage Calendars (fiscal years, time Dimensions) - Generate formulas with complex Dimension alignments, modifiers, and text manipulation - Create Views and Boards - Set up iterative calculations within a Block and between Blocks ### Data integration - Import CSVs to create/update Dimension and Transaction Lists - Auto-suggest Metrics from uploaded data - Read and create Metric-to-Metric import configs ### Documentation and education - Explain model dependencies and how groups of Blocks work - Generate documentation pages about Applications or Boards ### Board design and structure - Suggest appropriate Boards proactively - Apply best design and structure practice ### Model auditing - Navigate complex dependencies across the model - Search Views - Explain impact of structural changes - Identify unused Blocks and performance risks - Retrieve answers from Applications’ history on who changed what and when ## Best practice - For those using Test & Deploy, ensure you use the Modeler Agent only in the Dev environment. - Ensure that you take precautions before making significant modeling changes with the Modeler Agent. For more information on recovering Applications and restoring from backup, see: - [Restore a Block from Backup](/v1/docs/restore-block-from-backup) - [Recover an Application from Backup](/v1/docs/recover-an-application-from-backup) ## Related - [Pigment AI](/pigment-ai.md) - [About Roles, Permissions and Access Rights](/roles-permissions-access-rights.md)