To create Zen Agents, you need the Precursive AI Insights Builder permission set assigned by your administrator. Builders can create and configure agents and link existing Context Sources and Actions to them. Builders cannot create Context Sources or Actions themselves - those are created by admins - see Creating and Configuring Context Sources and Creating and Configuring Actions.

A Note on Where Instructions Live

Precursive AI gives you several places to write instructions for the AI. Knowing where each one belongs will save you a lot of iteration:

• Agent-level Prompt Instructions - the overall direction for the agent. What kind of insight do you want overall? What should it focus on?
• Rule-level Prompt Instructions - what to do with the data gathered by this specific Context Source. Be specific about what to look for in this slice of data.
• Salience Prompt - rules for when to rate an insight as high, medium, or low salience (used to filter what is worth emailing).
• Custom Score Prompt - the criteria the AI uses to assign the custom score.
• Action Instructions (admin) and Agent Action Instructions (builder) - what an action should do, and how this specific agent should refine that behaviour.

Keep agent-level instructions broad and rule-level instructions specific. The AI sees all of them, so don't repeat yourself.

Step 1: Create the Zen Agent

1. Go to the App Launcher in Salesforce
2. Search for Zen Agents
3. Click New
4. Fill in the fields across each tab (see below)
5. Click Save

General Settings

Record Source

Schedule

Email Settings

Step 2: Add Rules

Rules tell the AI what data to gather (via a Context Source) and how to analyse it. Each Zen Agent should have at least one Rule, and most agents benefit from two to three Rules that build up a layered picture of the record.

Important: all Rules on a Zen Agent must use Context Sources whose Source Object API Name matches the agent's Source Object API Name. If you select an incompatible Context Source, the save will fail with: "The Context Source's Source Object API Name (X) does not match the Zen Agent's Source Object API Name (Y). Please select a Context Source that is compatible with this Zen Agent."

If you need a Context Source that does not exist yet, your admin will need to create it. See Creating and Configuring Context Sources (/s/article/Creating-and-Configuring-Context-Sources).

1. From the Zen Agent record, navigate to the Rules related list
2. Click New
3. Fill in the Rule fields (see below)
4. Click Save
5. Repeat for additional Rules

Rule Fields

Tips for writing effective Prompt Instructions:

• Be specific about what you want the AI to look for - risks, opportunities, gaps, trends
• Specify the format if needed, for example "Provide 2 to 3 bullet points"
• Avoid vague instructions like "summarise this" - tell the AI what matters

Step 3: Configure Scoring and Salience

Score

A custom score is the most visible signal on an insight - users see it as a colour-coded badge as soon as the component loads. Most agents benefit from one. Configure the score before salience.

To configure a custom score, add a score name and a scoring prompt to the Zen Agent record. The scoring prompt tells the AI what criteria to use when assigning a score from 0 to 100.

The colour bands shown to end users are hardcoded:

• 70-100: Green
• 40-69: Amber
• Below 40: Red

So 100 is always green, but green starts at 70 - design your scoring criteria with this in mind. The AI's rationale for the score it assigns is shown when users hover over the badge.

Salience Instructions

The salience prompt tells the AI when to rate an insight as high, medium, or low salience. Salience is used internally to filter out low-value insights from scheduled email delivery - only insights above a certain threshold are emailed to recipients. A well-defined salience prompt means recipients only receive emails when there is genuinely something worth their attention.

The salience prompt is configured on the Zen Agent record. Examples of effective salience prompts:

• "Rate as high salience if there are unresolved risks, no activity in the past 14 days, or an upcoming milestone within 7 days"
• "Rate as high salience only if the support case mentions a need for professional services"
• "Rate as high salience if the opportunity has been in the current stage for more than 30 days without any contact logged"

Step 4: Link Actions to the Zen Agent

Actions are defined by admins and made available for builders to link to agents. Linking an action to a Zen Agent means the AI will consider that action when generating insights for records covered by the agent.

Each linked action consumes an additional AI request per insight. If you link three actions, every insight that runs will use four requests total (one for the insight itself, plus one per action evaluation). Plan against your entitlement's weekly request limit accordingly.

1. From the Zen Agent record, navigate to the Agent Actions related list
2. Click New
3. Select the Action to link
4. Set the Execution Mode:
   1. Supervised - the action is surfaced as a recommendation in the component. The user decides whether to trigger it.
   2. Autonomous - the AI decides whether to run the action based on the insight content. The action runs automatically only when the AI's confidence in the recommendation is at least 90%. Both the confidence value and the AI's rationale for it are captured on the action result record for audit.
5. Optionally set a Run Order if multiple actions are linked and sequence matters
6. Optionally add an Action Instruction override to refine the action's behaviour for this specific agent. Your override is provided to the AI alongside the admin-defined Action Instructions - both are visible to the AI, with your override providing agent-specific guidance on top of the base behaviour
7. Click Save

You can link multiple Actions to a single Zen Agent. Each action is evaluated independently during insight generation.

Step 5: Link an Entitlement

A Zen Agent must have an active entitlement linked before it can run. Without an active entitlement, scheduled runs and on-demand refreshes will fail. The Preview action below still works without an entitlement, so you can build and validate before provisioning.

1. On the Zen Agent record, locate the Entitlement field
2. Select the appropriate entitlement from the available options
3. Save the record

If no entitlements appear, contact your administrator. Entitlements are provisioned from Precursive and managed by admins.

Review Precursive AI Licensing and Entitlements for more information.

Step 6: Preview and Test

Before enabling scheduled runs, test your agent using the Preview and Validate Filter actions on the Zen Agent record.

Validate Filter shows which records currently match the agent's filter criteria. The results are presented across three tabs: a Summary of your configuration, a Matching Records table showing each record name, recipient, and ID (searchable), and a SOQL Query tab showing the exact query being used with a copy button. Use this to confirm your filter is working as expected before activating.

Preview generates a sample insight for a specific record without sending emails or affecting scheduled runs. You can choose to preview against a single record you select, or against records matching the agent's filter criteria. An optional "Send preview email" toggle lets you receive the output by email to review formatting. Preview bypasses entitlement checks, so you can iterate on your agent before an entitlement is in place. Adjust Rules or Prompt Instructions based on what you see, then preview again.

When you are satisfied with the output, enable the Scheduled toggle and confirm the entitlement is linked. The agent will begin running on the next scheduled execution.