This guide is for the Precursive AI Insights Builder role. To create Zen Agents, you need the Precursive AI Insights Builder permission set. Builders create and configure Agents and add existing Context Sources and Actions to them. Admins create Context Sources and Actions. See Creating and Configuring Context Sources and Creating and Configuring Actions.

Where instructions belong

Precursive AI has several places for instructions to the AI. Put each instruction in the right place to reduce the number of revisions you need:

• Instructions on the Zen Agent: the overall direction for the Agent, such as the kind of Insight you want and what it should focus on.
• Instructions on a Zen Agent Context Source: what to do with the data that this Context Source gathers, and what to look for in it.
• Salience Instructions: how to rate the salience of an Insight, from 0 to 100. Precursive AI uses salience to decide which Insights to email.
• Score Instructions: the criteria the AI uses to assign the custom score.
• Action Instructions and Instructions on a Zen Agent Action: what an Action does (set by admins on the Action), and how this Agent refines it (set by Builders on the Zen Agent Action).

Keep Agent instructions broad and Context Source instructions specific. The AI reads all of them, so write each instruction once.

Step 1: Create the Zen Agent

Each Zen Agent is a record that holds its instructions, the records it analyzes, when it runs, and who receives its Insights. To create one:

1. Open the App Launcher and search for Zen Agents.
2. Select New.
3. Fill in the fields of the New Zen Agent window, as described in the following tables. The tables group the fields by topic. Name, Source Object API Name, and Source Record Name Field API are required.
4. Select Save.

After you save, you can change the same fields on the Zen Agent record. The Overview tab holds the general settings and permissions, the Instructions tab holds the instructions, score, and salience, and the More menu opens the Record Source, Schedule, Email, and Feedback tabs.

Information and capabilities

These fields name the Agent and control whether it runs and what it produces.

Field	Description
Name	A name for the Agent, for example Project Status Agent or Opportunity Coaching.
Order	Where this Agent appears when several Agents email the same recipient, and in the Zen Agent menu of the component. Lower numbers appear first.
Active	Makes the Agent available to run. You can select it only when the linked entitlement is Active. If no entitlement is linked, Precursive AI shows this message: "An active entitlement must be assigned before this agent can be activated."
Entitlement	The entitlement that governs the Agent. It must be Active and within its validity dates. It must also allow Insights if you select Insights Enabled, and Actions if you select Actions Enabled.
Description	What the Agent does and when to use it.
Insights Enabled	Generates Insights with a summary, salience, and score. Select it for Agents that analyze and summarize records.
Actions Enabled	Lets the Agent run its linked Actions. The Actions related list on the Context & Actions tab appears only when it is selected. Select it when you are ready to link Actions.
Email Enabled	Emails Insights to recipients. It is cleared by default. When you select it, set at least one recipient source: Recipient User Lookup Field, Recipient Related User Lookup Field, Recipient Groups, or External Email Recipients.
Scheduling Enabled	Includes the Agent in scheduled runs. When you select it, Day of Week and Hour of Day are required. When it is cleared, users can still run the Agent from the component.
Show on Parent Records	Shows the Agent on parent records, with an overview of the latest Insight for each related record.

Record source and filter

These fields decide which records the Agent analyzes on each run.

Field	Description
Source Object API Name	The API name of the Salesforce object to analyze, for example Opportunity, Account, or Project__c.
Source Record Name Field API	The field to use as the heading for each result, for example Name.
Source Record Filter Criteria	An optional SOQL WHERE clause that filters which records the Agent processes, for example IsClosed = false AND StageName != 'Closed Lost'. The filter applies to scheduled runs, manual runs, Validate Filter, and the parent record overview.
Filter Recent Changes Only	Processes only records modified in the last 7 days, to avoid processing unchanged records.
Record Limit	The maximum number of records to process per run. Leave it empty to use the limit of the entitlement, which is its Max Requests Per Week, or 200 if that is empty. A value above the limit of the entitlement has no effect. Precursive AI marks records over the limit as failed.

Schedule

These fields set when the Agent runs. They apply only when Scheduling Enabled is selected. When Email Enabled is selected and recipients come from Recipient User Lookup Field, the day and hour are in the time zone of each recipient. Otherwise, they are in the org time zone.

Field	Description
Day of Week	The day the Agent runs. Select one day.
Hour of Day	The hour (0–23) the Agent runs. For example, enter 8 for 8:00 AM.
Frequency	How often scheduled runs revisit the same record. Always, the default, lets every scheduled run include the record. Weekly, Every 2 Weeks, and Monthly skip records that received a completed Insight in the last 7, 14, or 30 days. Frequency has no effect on runs started from the component.

Email settings

These fields decide who receives the Insights by email. They apply only when Email Enabled is selected. Precursive AI emails Insights from scheduled runs only, and only Insights with a salience of 40 or higher. The one exception is Send preview email in the Preview Insight window. Precursive AI checks each recipient against the Agent and against the records and fields the Insight was built from, and sends them only the Insights they pass. Recipients also get access to those Insights in Salesforce when the run finishes.

Field	Description
Email Subject	The subject line of the email. To insert the name of the first Agent in the email, include {InsightName}.
Color	An accent color for the email, as a hex color code. Leave it empty to use the default color.
Recipient User Lookup Field	The field path from the source object to the recipient user, for example OwnerId for the record owner.
Recipient Related Object	The API name of a related object that links the source record to more recipients. For example, use OpportunityTeamMember to send to all team members instead of only the owner. When you set it, Recipient Relationship Field is required.
Recipient Related User Lookup Field	The field path from the related object to the recipient user, for example UserId.
Recipient Relationship Field	The field on the related object that references the source record, for example OpportunityId.
Recipient Related Filter	An optional SOQL WHERE clause that filters which related records become recipients, for example TeamMemberRole = 'Account Manager'.
Recipient Groups	The API names (DeveloperNames) of public groups or queues whose members receive the Insight, separated by commas. Only direct user members are included.
External Email Recipients	Email addresses of people without a Salesforce login who should receive the Insights. Precursive AI does not check external recipients against any Salesforce access, so they receive the Insight for every record the Agent processes. See Insight sharing and access control.

The Agent Permissions and Insight Permissions sections control who can see the Agent and its Insights. See Step 6.

Step 2: Add Context Sources

A Zen Agent Context Source tells the AI what data to gather, through a Context Source, and how to analyze it. Each Zen Agent needs at least one. Most Agents work best with two or three that build up a layered picture of the record.

Every Context Source on a Zen Agent must have the same Source Object API Name as the Agent. If you select a Context Source that does not match, Precursive AI does not save it and shows this message: "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, ask your admin to create it. See Creating and Configuring Context Sources. To add a Context Source to the Agent:

1. On the Zen Agent record, select the Context & Actions tab.
2. In the Context Sources related list, select New.
3. Fill in the fields of the New Zen Agent Context Source window, as described in the following table.

   

4. Select Save.
5. Repeat for each additional Context Source.

Zen Agent Context Source fields

Each Zen Agent Context Source links one Context Source to the instructions for analyzing its data. Fill in these fields:

Field	Description
Zen Agent	The Agent. Precursive AI fills it in when you start from the Agent record.
Context Source Name	A name for this use of the Context Source, for example Recent Activity Analysis.
Order	The order in which this Context Source runs. Lower numbers run first.
Context Source	The Context Source that gathers the data. The list shows every Context Source. Select one with the same source object as the Agent, because Precursive AI rejects any other when you save.
Instructions	How the AI analyzes the data this Context Source gathers. Be specific, for example: Summarize the key activities from the last 14 days and highlight any gaps in engagement or overdue follow-ups.

To write instructions that produce useful Insights:

• Say what the AI should look for, such as risks, opportunities, gaps, or trends.
• Specify the format when it matters, for example two to three bullet points.
• Tell the AI what matters instead of asking it to summarize the data.

Step 3: Configure scoring and salience

A score and salience instructions help users see which Insights need attention. You set both on the Instructions tab of the Zen Agent record. Configure the score first.

Score

A custom score is the most visible signal on an Insight. Users see it as a colored badge as soon as the component loads, so most Agents benefit from one. To configure a custom score, enter a Score Name and Score Instructions. The score instructions tell the AI which criteria to use when it assigns a score from 0 to 100.

Precursive AI uses fixed color bands for the badge:

• 70–100: green
• 40–69: amber
• Below 40: red

Green starts at 70, so design your scoring criteria with this in mind. Users see the rationale of the AI for each score when they hover over the badge.

Salience instructions

Salience Instructions tell the AI how to rate the salience of an Insight, from 0 to 100. Without them, the AI rates as high (80–100) critical changes and major risks or opportunities, and as medium (40–79) moderate changes and useful updates. Precursive AI emails only Insights from scheduled runs with a salience of 40 or higher. The threshold is fixed, so well-defined salience instructions mean recipients get an email only when something needs their attention. For example:

• 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

Admins define Actions, and Builders link them to Agents. When you link an Action to a Zen Agent, the AI considers that Action when it generates Insights for the records the Agent covers.

When Actions Enabled is selected, each active linked Action uses one more AI request per Insight. If you link three Actions, every Insight uses four requests: one for the Insight and one for each Action. Plan against the weekly request limit of your entitlement.

Every Action on a Zen Agent must have the same source object as the Agent. If you select an Action that does not match, Precursive AI does not save it and shows this message: "The Action's Source Object API Name (X) does not match the Zen Agent's Source Object API Name (Y). Please select an Action that is compatible with this Zen Agent."

The Actions related list appears only when Actions Enabled is selected on the Overview tab. To link an Action:

1. On the Zen Agent record, select the Context & Actions tab.
2. In the Actions related list, select New.
3. For Action Name, enter a name for this use of the Action.
4. For Action, select the Action to link.
5. For Execution Mode, keep the default, Supervised, or select Autonomous:
   • Supervised: the Action appears as a recommendation in the component, and the user decides whether to apply it.
   • Autonomous: the AI decides whether to run the Action based on the Insight. The Action runs automatically only when the confidence of the AI in the recommendation is at least 90%, the default threshold. The Action result records the confidence value and the rationale of the AI for audit.

   

6. If more than one Action is linked and the order matters, set Order.
7. To refine the behavior of the Action for this Agent, enter Instructions. The AI reads them together with the Action Instructions that the admin defined.
8. Select Save.

A new link is Active by default. Only active links run. You can link several Actions to one Zen Agent. The AI evaluates each Action separately when it generates an Insight.

Step 5: Link an entitlement

A Zen Agent needs an active entitlement before it can run. Without one, scheduled runs and runs started from the component fail, and you cannot select Active. Preview does not check the status of the entitlement, but it needs a linked entitlement and counts against its usage. To link an entitlement:

1. On the Zen Agent record, go to the Entitlement field.
2. Select the entitlement.
3. Select Save.

If no entitlements appear, contact your admin. Precursive provisions entitlements. For limits, statuses, and usage, see Precursive AI licensing and entitlements.

Step 6: Decide who can see the Agent

A new Agent is available to every internal user with a Precursive AI permission set. To roll it out to a pilot group first, or to keep it to the people who build it, restrict it. See Control who can see and edit a Zen Agent. To give a team its Insights in reports and list views, see Insight sharing and access control.

The Insight Permissions section controls who can see the Insights of the Agent:

• Insight Access: User Mode, the default, shows an Insight only to people who can access every record and field it was built from. Only users with the Precursive AI Admin, Precursive AI Allow System Mode, or Precursive AI Manage System Mode permission set can change it. See Let anyone see an Insight with System Mode.
• System Mode Viewers: the people who see every Insight from the Agent when Insight Access is System Mode.
• Default Share Groups: the API names (DeveloperNames) of public groups, separated by commas. Precursive AI shares each Insight with their members as it completes, if they can see every record it was built from.

Step 7: Preview and test

Before you schedule the Agent, test it with Validate Filter and Preview at the top of the Zen Agent record.

Validate Filter shows which records match the filter criteria of the Agent. The results appear on three tabs:

• Summary: the filter criteria, whether only recent changes are included, and the record limit.
• Matching records: a searchable table of the records the Agent processes. The tab is named after the source object, for example Matching Opportunities.
• SOQL Query: the exact query, with a copy button.

Preview opens the Preview Insight window, which generates a sample Insight without affecting scheduled runs. The window has these options:

• Preview using filter criteria: selected by default, so the preview uses the records that match the filter criteria. To preview one record instead, clear it, and then choose the record in Select a record to test with.
• Send preview email: sends the result to the email address you enter, so you can review the formatting of the email. Precursive AI sends it only if the salience of the Insight is 40 or higher.
• Advanced Options: compares the output of different entitlements with Model Variant Test. When you select it, Precursive AI clears Preview using filter criteria and Send preview email, because the test uses one record.

Select Run Preview to generate the Insight. Preview uses the model of the linked entitlement and counts against its usage. Adjust the Context Sources or instructions based on the result, and then preview again.

When the output meets your needs, confirm that Active is selected, and then select Scheduling Enabled and set Day of Week and Hour of Day. The Agent runs at the next scheduled time.