Agentforce Setup
Agentforce is the Salesforce-native channel of the aprity Org Expert. Once set up, users ask questions about your org from the Agentforce panel in Lightning Experience and receive answers grounded in your latest aprity scan, with their sources.
Overview
The aprity managed package ships two Apex invocable actions:
- aprity - Answer Documentation Question -- returns a grounded answer, with citations, from the aprity backend.
- aprity - Record Help Feedback -- records a thumbs up / thumbs down vote on a previous answer.
The package does not ship an agent, subagent, plugin or planner metadata, so it installs on any org whatever its Agentforce licensing. You create your own agent and attach the aprity actions to it, following the five steps below. The same guide, with live prerequisite checks, is available in the aprity app: open the aprity tab, then Agentforce in the Assist section of the side menu.
Salesforce now calls agent Topics "Subagents". Older Salesforce documentation and some org screens may still say "Topic": it is the same concept.
Prerequisites
The Agentforce page of the aprity app checks the first two automatically (use Refresh to re-run the checks):
- Agentforce feature enabled on your aprity plan. The Agentforce channel is available on the Intelligence and Trial plans. The Agentforce menu entry is hidden when your plan does not include it.
- At least one completed aprity scan. The agent answers from your latest completed scan. Without one, it has nothing to answer from.
- The aprity managed package installed -- it contains the two actions and the aprity Agent User permission set.
- Agentforce enabled in your Salesforce org, so that you can create and activate agents in Agentforce Studio.
Step 1: Create the agent
-
From the App Launcher, open Agentforce Studio, then go to Build > Agents.
-
Click New Agent.
-
In the Or, start with a template section, locate Agentforce Employee Agent (internal assistant), click Details, then Select Template.
-
Set the Agent Name to aprity -- the Developer Name fills in automatically -- then click Let's Go.
-
In Agentforce Builder, open the agent Settings and set the description:
AI assistant for Salesforce. Answers questions about the org's objects, validation rules, triggers, flows and business processes, and helps end users find how to accomplish their tasks with what is configured in the org — using documentation generated by aprity.
-
The template ships with default subagents and actions: remove the ones you don't need.
The agent must be deactivated before you can change anything in Agentforce Builder.
Step 2: Add the documentation subagent
-
In Agentforce Builder, click New Subagent.
-
Set the subagent label: Documentation aprity.
-
Set the Classification Description (when to use this subagent):
The user asks a question about their Salesforce org — objects, fields, validation rules, triggers, flows, business processes, dependencies, technical documentation — OR asks how to accomplish a task in the org (where to record something, how to create it, which fields to fill).
-
Set the Scope:
Answer questions about the Salesforce org configuration and functionality, and about what the org provides for the user's business tasks, using documentation indexed by aprity. Do not fabricate information.
-
Add these Instructions:
- Use "aprity - Answer Documentation Question" to get a grounded answer from the aprity backend
- "How do I…" user-task questions go to the same action: the answer explains what the org provides for the need. Never answer them from general Salesforce knowledge
- When the user explicitly says the answer was helpful or unhelpful, call "aprity - Record Help Feedback" with the returned queryId and the vote — exactly "up" or "down" in lowercase. Never prompt the user for feedback
- Base answers ONLY on sources returned. Never fabricate information
- Cite your sources (citations returned by the action)
- If no source answers the question, clearly state it
- Reply in the user's language
-
Click Save.
Step 3: Add the actions to the subagent
In the Documentation aprity subagent, click New Action twice to add the two aprity actions. Each action has a two-page wizard.
Action 1 -- aprity - Answer Documentation Question (required)
Page 1: Connect an existing action
| Field | Value |
|---|---|
| Reference Action Type | Apex |
| Reference Action Category | Invocable Method |
| Reference Action | aprity - Answer Documentation Question |
Agent Action Label and API Name are filled in automatically. Click Next.
Page 2: Configure
| Field | Value |
|---|---|
| Agent Action Description | Returns a grounded answer from aprity documentation |
| Show loading text | Checked |
| Loading Text | Querying aprity documentation... |
Inputs:
| Input | Description | Require input | Collect from user |
|---|---|---|---|
| Question | The user's question about Salesforce org configuration | Yes | Yes |
| Language | Response language code (e.g. fr, en). Defaults to user's language | No | No |
| Record Id | Optional record Id for record-context questions | No | No |
| Object API Name | Optional SObject API name matching Record Id | No | No |
| Scan Id | Specific scan ID to query. Leave empty to use the latest scan | No | No |
| Max Citations | Maximum number of citations to include (default: 3) | No | No |
Outputs:
| Output | Description | Show in conversation |
|---|---|---|
| Answer Text | The generated answer to display to the user | Yes |
| Query Id | Unique id for this Q&A pair — pass it to aprity - Record Help Feedback to record a vote | No |
| Answer Mode | How the answer was produced: GROUNDED, PARTIAL, or NO_ANSWER | No |
| Has Answer | True if a valid answer was returned | No |
| Confidence | Confidence score between 0 and 1 | No |
| Used Objects | Salesforce objects referenced in the answer (one per line) | No |
| Used Scan Id | The scan ID used to generate the answer | No |
| Citations Json | JSON array of source citations with titles and excerpts | No |
| Follow Up Questions | Suggested follow-up questions (one per line) | Yes |
Click Finish.
Action 2 -- aprity - Record Help Feedback (optional but recommended)
Page 1: Connect an existing action
| Field | Value |
|---|---|
| Reference Action Type | Apex |
| Reference Action Category | Invocable Method |
| Reference Action | aprity - Record Help Feedback |
Click Next.
Page 2: Configure
| Field | Value |
|---|---|
| Agent Action Description | Records a thumbs up / down vote on the previous aprity answer |
Inputs:
| Input | Description | Require input | Collect from user |
|---|---|---|---|
| Query Id | Value returned by aprity - Answer Documentation Question | Yes | No |
| Vote | Either "up" or "down" (lowercase) | Yes | No |
Outputs:
| Output | Description | Show in conversation |
|---|---|---|
| Success | True if the vote was recorded | No |
| Message | Human-readable status | No |
Click Finish.
Optional -- Rich answer card
The package also ships the aprityAnswer lightning type and its aprity Answer Card renderer. With it, the answer displays as a formatted card (formatted text, source badges, follow-up questions, thumbs up / down) instead of plain text. It is supported in the Agentforce panel (Lightning Experience) and Enhanced Chat v2.
- In Action 1's configuration, set the Rich Rendering input to the constant value True (Require input unchecked, Collect from user unchecked). The answer then keeps its Markdown formatting.
- On the Answer Card output, set Output Rendering to aprityAnswer and check Show in conversation. An "Unsupported Data Type" note may appear next to Map to Variable: it is harmless.
- Uncheck Show in conversation on Answer Text and Follow Up Questions -- the card already displays them.
- The card's vote buttons call aprity directly: users who vote need the aprity Agent User permission set (see Step 5).
Salesforce requires the Answer Card output to stay visible to the planner for rendering, which roughly doubles the answer's token footprint in Einstein credits. Citations link to your aprity portal when a portal is published for the scan.
Step 4: Activate and test
- Click Activate in Agentforce Builder.
- Test in the Conversation Preview panel of Agentforce Builder, or open the Testing Center from Agentforce Studio for batch tests.
- Try these sample questions:
- What are the validation rules on Account?
- How does the opportunity creation process work?
- What triggers exist on Contact?
- Explain the Case object
- Verify that the answers include the citations returned by the action.
Step 5: Deploy to users
- Assign the aprity Agent User permission set (included in the aprity package) to every user who will use the agent. It grants access to the two aprity actions.
- Grant access to the agent itself: in Setup, open Permission Sets and create a permission set (for example aprity Agent Access), or open an existing one.
- In that permission set, go to Apps > Agent Access, click Edit, and add the aprity agent to the Enabled Agents list.
- Click Manage Assignments and assign the permission set to your users.
- Users open the agent from the Agentforce icon in the top-right corner of Lightning Experience. Employee agents are also available in the Salesforce mobile app and in Slack.
The agent runs in the context of each user: answers are scoped by the user's own access, and feedback votes are recorded per user.
Keeping answers current
The agent answers from the latest completed scan, not from the live org. Run a new analysis after significant changes to your org so that answers follow them (see Scan Frequency).
Questions asked through Agentforce count against your organization's Org Expert budget (see Org Expert).
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
| The Agentforce menu entry is missing | Your plan does not include Agentforce | Agentforce is available on Intelligence and Trial. See Plan Comparison. |
| aprity actions not listed in the action wizard | Managed package not installed | Install the aprity managed package. |
| The agent gives empty answers | No completed scan yet | Run a scan so the agent has data to answer from. |
| The agent does not respond | Agent not activated | Complete Step 4 (Activate) in Agentforce Builder. |
| Users do not see the agent | Agent access not granted | Add the agent under Apps > Agent Access in a permission set assigned to them (Step 5). |
| Action calls fail for some users | aprity Agent User permission set missing | Assign the aprity Agent User permission set to those users. |
| Answers are outdated | Stale scan | Run a new scan. |
For anything else, contact contact@aprity.ai.