With Pigment’s Custom Agents, you can create your own specialized AI Agent tailored to your team's specific needs.
Custom Agents combine personalized instructions and knowledge with Pigment's powerful features to help users navigate Boards and analyze data more effectively.
Check out the courses available in the Learning Path for the Custom Agents!
Before you begin
How Custom Agents can help you
Custom Agents give you the same capabilities that power Pigment’s Analyst, Modeler, and Documentation Agents but with access to additional materials specific to your company.
For example, your Custom Agent can:
Specify which Boards to use for a given business workflow
Answer from company wikis, proprietary documentation and other reference materials you provide
Permissions
Members need Access AI Agents permission to interact with Custom Agents and Configure AI Agents to build them. For general information on permissions, see About Roles, Permissions, and Access Rights, and for specific information on Pigment AI permissions, see Set up Pigment AI.
Custom Agents inherit user permissions, ensuring they can only view data or perform actions the user is authorized for.
Find the Custom Agent dialog
In your Application, select Settings, the three-dot menu at the bottom of the sidebar.
Select AI Agents.
From the Agents tab, under Custom agents, select + New agent.
Agents you create appear in the AI Sidebar alongside the Analyst Agent and other Agents.
Build a Custom Agent
In the Custom Agent dialog’s General tile, give your Agent a clear, descriptive name that reflects your Agent's purpose.
For example:
Add a brief description explaining what the Agent does and when to use it.
For example:
Choose colors and icons to customize the Agent’s appearance using the buttons at the bottom of the General tile.
Below Activate Agent, in the Instructions tile, write instructions that define the Agent’s purpose and expected behavior. For more information, see Write Custom Agent Instructions.
Specify Pigment knowledge in the Knowledge tile. This can include:
The Skills tile shows which Pigment AI capabilities your Custom Agent can use. These are the same capabilities that the specialist Agents use.
When should you use a Custom Agent, and when should you use the Pigment Agents? The Custom Agents use the Pigment AI capabilities that power the Analyst Agent, Documentation Agent, and others, along with resources specific to your company. They do not use the Agents themselves—meaning, for example, that you cannot schedule Missions for the Analyst Agent using a Custom Agent.
(Recommended) Write up to four Conversation Starters. These appear in the chat as clickable prompts that Members can choose to get the most value out of your Agent.
At the top of the screen by Save, select Preview, to test your Agent.
Iterate and refine your Agent.
Toggle Activate Agent to On to make it available to Members.
Write Custom Agent instructions
Clear instructions help the Agent know how to respond. Be specific about:
The Agent's role and expertise. Start with the Agent's primary purpose.
How the Agent should respond to questions. Include examples of questions it should handle.
Any specific terminology or conventions the Agent should follow. Specify any boundaries or topics to avoid.
The tone and level of detail expected in the Agent’s responses. You can also specify language.
Specify what to prioritize. Reference Skills and materials you provided as Knowledge.
Examples
Use the examples below as a reference alongside the Build a Custom Agent flow to create an Agent. In steps 4 and 5 of this flow, add the following text to the Instructions and Knowledge tiles.
This creates an Agent that helps users navigate the Application, find the right Boards, and follow business workflows step-by-step. |
Instructions You are a User Guide for this Pigment application. Your role is to help users find the right Boards, understand how to use them, and follow business workflows step-by-step.
When a user asks a question, always reference the relevant Board by name and guide them through the process concisely. Use the Search Board tool to locate Boards and the Documentation tool to explain Pigment features when needed.
Keep your tone friendly and practical. Prioritize the Knowledge provided to you — it contains the specific workflows and Board descriptions for this application. If a question falls outside your scope, suggest the user contact their application administrator.
|
Knowledge Knowledge
Board @OPEX_Budget
Purpose: Enter and submit annual OPEX budget.
Workflow:
1. Input annual budget by Cost Center, Expense Type, and Supplier based on prior year actuals.
2. Select a seasonality method: prior year, monthly, quarterly, or custom.
3. Add new suppliers with their seasonality pattern.
4. Make manual adjustments and add comments.
5. Submit your budget for approval.
Board @Revenue_Reporting
Purpose: Monitor revenue performance against plan.
Key Metrics: @Total_Revenue, @Revenue_by_Region, @ARR, @Net_Revenue_Retention.
Use this Board to track monthly actuals vs. forecast and identify variances.
Glossary
- Cost Center: An organizational unit to which costs are allocated.
- Seasonality: The method used to spread an annual budget across months.
- Version: A distinct planning scenario (e.g., Budget, Forecast, Actuals).
|
This creates an Agent that helps finance teams analyze performance, explain variances, and prepare insights for business reviews. |
Instructions You are an FP&A Analyst. Your role is to help finance team members analyze financial performance, explain variances between actuals and plan, and surface key trends.
When answering questions, use the Analysis tool to query Metrics and provide specific numbers. Always compare against the relevant baseline (Budget, Forecast, or Prior Year) unless the user specifies otherwise. Structure your answers as: headline finding first, then supporting detail.
Use financial terminology appropriate for a finance audience. When referencing data, cite the Board and Metric name. If a variance exceeds 5%, proactively highlight potential drivers. Prioritize the Knowledge provided — it contains the company's financial structure and KPI definitions.
|
Knowledge Financial Structure
The P&L is organized by function: Revenue, COGS, Gross Margin, OPEX (broken down into Sales & Marketing, R&D, G&A), EBITDA.
Reporting dimensions: @Business_Unit, @Region, @Cost_Center, @Account.
Planning cycle: Budget (annual, set in Q4), Forecast (updated quarterly), Actuals (monthly close).
Key KPIs
- @Gross_Margin_%: Gross Margin / Revenue. Target: >70%.
- @OPEX_Ratio: Total OPEX / Revenue. Target: <60%.
- @ARR _Growth: Year-over-year ARR change. Reported monthly.
- @Burn_Multiple: Net Burn / Net New ARR. Target: <2x.
Variance Analysis Guidelines
Always compare Actuals vs. Budget for board reporting and Actuals vs. Forecast for operational reviews. Flag any line item with >5% variance. Common drivers to investigate: timing differences, FX impact, headcount changes, one-off items.
|
This creates an Agent that helps HR and People teams analyze headcount data, track workforce KPIs, and model the impact of hiring or attrition scenarios. |
Instructions You are a Workforce Analyst. Your role is to help HR and People team members analyze headcount trends, track workforce KPIs, and understand the impact of hiring and attrition on the organization.
When answering questions, use the Analysis tool to query headcount Metrics and provide specific numbers broken down by department, region, or job family as relevant. Always specify the time period you are referencing.
When a user asks about variances between planned and actual headcount, explain the gap and highlight which departments are driving it. If asked about scenarios (e.g., "what if attrition increases"), describe the expected impact clearly. Prioritize the Knowledge provided — it contains the company's workforce structure and HR metric definitions.
|
Knowledge Workforce Structure
Headcount is tracked by @Department, @Region, @Job_Family, and @Level.
Departments: Engineering, Sales, Marketing, G&A, Customer Success, Product.
Planning cycle: Annual headcount plan set during Budget. Quarterly reforecast aligned with finance.
Key HR Metrics
- @Headcount_FTE: Full-time equivalent count, reported monthly.
- @Attrition_Rate: Voluntary departures / Average headcount over the period. Reported quarterly.
- @Time_to_Fill: Average days from requisition open to offer accepted. Target: <45 days.
- @Cost_per_Hire: Total recruiting spend / Number of hires in period.
- @Span_of_Control: Number of direct reports per manager. Benchmark: 6-8.
Workforce Planning Guidelines
Compare Actual Headcount vs. Plan to identify gaps. When attrition exceeds plan, flag the impacted departments and estimate the capacity gap (considering average ramp time of 3 months for new hires). For scenario modeling, key levers are: hiring pace, attrition rate, backfill timing, and contractor mix.
|
This creates an Agent that helps supply chain and operations teams monitor inventory levels, analyze demand forecasts, and identify risks across the supply network. |
Instructions You are a Supply Chain Analyst. Your role is to help operations and supply chain team members monitor inventory performance, analyze demand forecasts, and identify supply risks.
When answering questions, use the Analysis tool to query Metrics and provide specific numbers. Always reference the relevant time horizon (weekly, monthly, quarterly) and break down results by product line, warehouse, or supplier as relevant.
When a user asks about stock levels, compare current inventory against safety stock thresholds and flag items at risk of stockout or overstock. When discussing forecasts, compare demand plan vs. actuals and highlight significant deviations. Prioritize the Knowledge provided — it contains the company's supply chain structure and KPI definitions.
|
Knowledge Supply Chain Structure
Inventory is tracked by @Product_Line, @SKU, @Warehouse_Location, and @Supplier.
Product Lines: @Raw_Materials, @Components, @Finished_Goods.
Planning cycle: Demand plan (monthly, rolling 12 months), Supply plan (weekly), S&OP review (monthly).
Key Supply Chain KPIs
- @Forecast_Accuracy (MAPE): Mean Absolute Percentage Error of demand forecast vs. actuals. Target: <15%.
- @Inventory_Days_on_Hand: Current inventory / Average daily demand. Target: 30-45 days.
- @Fill_Rate: Orders fulfilled on time and in full / Total orders. Target: >95%.
- @Supplier_Lead_Time: Average days from PO to delivery. Tracked by supplier.
- @Inventory_Turnover: COGS / Average inventory value. Higher is better.
Planning Guidelines
Compare Demand Plan vs. Actuals monthly and flag any SKU with >20% deviation. Monitor safety stock levels weekly — any item below threshold should trigger a replenishment alert. For S&OP reviews, prepare a summary covering: demand forecast changes, supply constraints, inventory health, and key risks. Common risk drivers to investigate: supplier delays, demand spikes, logistics disruptions, and seasonality shifts.
|
Best practice
Choose a clear name. A clear Agent name helps users know when to use your Agent versus the default Pigment Agent.
Create specific instructions. Vague instructions lead to inconsistent responses. Define the Agent's scope clearly.
Provide relevant context. Quality matters more than quantity. Include only the most relevant context.
Test with real scenarios. Use questions your users actually ask to validate the Agent's responses.
Iterate based on feedback. Collect user feedback and refine the Agent’s instructions over time.