--- title: "Run the Modeler Agent" slug: "configure-and-run-the-modeler-agent" updated: 2026-06-12T16:44:14Z published: 2026-06-12T16:44:14Z --- > ## 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: - co-building, where the Modeler Agent serves as an expert partner under human supervision. - simple tasks, like *“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”*. - complex tasks, where the user presents a business objective, and the Modeler Agent clarifies ambiguities if necessary: *“I want to use my OPEX transaction data to retrieve actuals and apply a global growth % assumption to calculate future months".* ### 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 not available in [managed Production environments](/v1/docs/introduction-test-deploy#managed-applications). ## How to work with the Modeler Agent To make your request to the Agent: 1. In your Application, open the 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 paste text, upload CSV files and record voice notes containing your requirements. 3. Answer any multiple-choice questions the Agent raises. 4. Select **Plan & Build** to choose between the following operating modes: 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. 4. Select **Auto-accept actions**to allow the Modeler to proceed without validation at key waypoints. 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. 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. 7. (*Optional*) Interrupt the Agent while it prepares an answer if necessary. Select the **Stop answer** button, the blue box in the Chat input field. 8. (*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**. 9. 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 ### Basic 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 ### Data integration - Import CSVs to create/update Dimension and Transaction Lists - Auto-suggest Metrics from uploaded data ### 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 - 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)