Agentforce actions
Let an Agentforce agent answer a question such as whether an Account is ready for handoff with real Record Health Check results. Record Health Check installs two Agentforce actions that run a Check Set or one Check for one record and return its status. The actions only read data: they never change the record or publish Platform Events.
Choose the native actions
Section titled “Choose the native actions”The package provides two native Agentforce actions:
| Agentforce action | Apex class | Use |
|---|---|---|
| Run Record Health Check for Agentforce | RecordHealthCheckRunCheckAgentAction | Evaluate one exact Check for one record |
| Run Record Health Check Set for Agentforce | RecordHealthCheckRunSetAgentAction | Evaluate the complete active Check Set for one record |
Use the Check Set action for a general record-health question. Use the Check action only when the agent must answer one named data-quality question.
The actions evaluate with the configured Agentforce principal’s Salesforce access. This differs from an MCP call made through a dedicated integration user. Prefer these native actions when the result must reflect the agent principal’s object, field, record-sharing, restriction-rule, and scoping-rule access.
Before configuration
Section titled “Before configuration”- Confirm the org has Agentforce enabled, the required Salesforce licenses are assigned, and the intended agent opens in Agentforce Builder. Builder labels can change by Salesforce release, so use the current action-search UI rather than relying on one screenshot.
- Install a package version that contains the Agentforce actions and confirm Record Health Check appears in Setup → Installed Packages.
- Identify the agent’s running principal from the agent configuration, then assign that principal
Record Health Check User
(
rhc__Record_Health_Check_User) or equivalent least-privilege access. - If the agent has no existing data Permission Set, create an org-owned Permission Set that grants only the approved objects and fields, then assign it to the same principal.
- Confirm that record sharing lets the principal read the intended records.
- Copy each Check or Check Set exact
QualifiedApiName, as described in Find the Qualified API Name. Do not add or removerhc__. - Test the configuration with the same principal used by the active agent.
The User Permission Set grants run access but not diagnostics authorization. Do not assign the Admin or Diagnostics Viewer Permission Set only to make an agent action run.
Basic Agentforce configuration pattern
Section titled “Basic Agentforce configuration pattern”In Agentforce Builder, create a focused subagent or topic for record-health questions. Add one or both Apex invocable actions as required by the use case.
Use instructions with these rules:
- Call the Check Set action whenever the user asks for the actual overall health, readiness, completeness, or quality of a record under a configured Check Set.
- Call the single Check action only for a specifically named Check.
- Supply exactly one record ID and one exact qualified API name.
- Never infer a health result from conversation context or from Salesforce fields already available to the model.
- Never call both native and MCP versions for the same request unless deterministic comparison is the explicit use case.
- Interpret output according to the status table below.
- Use the four optional bounded diagnosis fields only as safe guidance for a completed evaluation; never invent or request raw administrator diagnostics.
Example: Give an agent an Account health tool
Section titled “Example: Give an agent an Account health tool”This walkthrough uses these example choices:
| Decision | Example choice |
|---|---|
| Agent | Account Readiness Assistant |
| Target object | Account |
| Check Set | An administrator-created Set named My_ |
| Normal action | Run Record Health Check Set for Agentforce |
| Optional focused action | Run Record Health Check for Agentforce |
| Result publication | None; native actions always use NONE |
Replace My_Account_Checks with the exact Check Set Qualified API Name from your org. It is an
example name, not metadata installed by Record Health Check.
Native agent actions never publish Record Health Check result Platform Events. success = false
means the tool request failed and the agent must not claim a health conclusion. success = true
with FAIL means evaluation completed and found an unmet requirement. ERROR means evaluation
returned a system problem, not a passing or business-failure answer.
Step 1: Prepare two test Accounts
Section titled “Step 1: Prepare two test Accounts”- Choose a sandbox or other non-production org where Agentforce is enabled.
- Confirm that the installed Record Health Check version contains the two native actions listed above.
- Create or choose one Account that should pass
My_Account_Checks. - Create or choose a second Account that should fail at least one Check.
- Copy each Account ID from its Salesforce URL.
- Copy the Check Set’s exact
QualifiedApiName. The Lightning App Builder picker shows it in parentheses after the label, and a SOQL query onrhc__Record_Health_Check_Set__mdtreturns it; see Find the Qualified API Name. - If you will configure the single-Check action, copy that Check’s exact
QualifiedApiNametoo, from a SOQL query onrhc__Record_Health_Check__mdt. - Write down the expected status for both test Accounts before testing the agent.
Expected result: you have one known-positive case, one known-negative case, and exact configuration names. Do not test adoption using an unknown record whose correct result is unclear.
Step 2: Identify the Agentforce principal
Section titled “Step 2: Identify the Agentforce principal”The principal is the Salesforce user whose access applies when the native action runs. For an employee agent that people use inside Salesforce, it is the signed-in user. For a service agent that answers customers, it is the agent user assigned to the agent.
- In Agentforce Studio or the agent’s Setup page, open the agent you will configure.
- Identify the user whose access applies: the signed-in users for an employee agent, or the assigned agent user for a service agent.
- Open that user from Setup → Users → Users.
- Record the username in the test plan.
- Confirm that it is not a broad administrator account used only because setup was easier.
Expected result: the team can name the exact Salesforce user whose object, field, and record access will govern every health result.
Step 3: Assign Record Health Check access
Section titled “Step 3: Assign Record Health Check access”- From Setup, enter
Permission Setsin Quick Find, then select Permission Sets. - Open Record Health Check User.
- Select Manage Assignments.
- Select Add Assignments.
- Select the Agentforce principal from Step 2.
- Complete the assignment.
- Return to the user’s Permission Set assignments and confirm that Record Health Check User is present.
That packaged Permission Set includes both Agentforce action Apex classes and the Record Health Check Run Custom Permission. It deliberately excludes diagnostic details.
Rejection test: in a controlled test org, remove the assignment and run the action. Confirm that
the response reports a safe authorization error and does not report PASS or FAIL. Restore the
assignment before continuing.
Step 4: Grant the data access required by the Checks
Section titled “Step 4: Grant the data access required by the Checks”- List every object and field used by
My_Account_Checksand its active Checks. - Include related and parent objects used by formulas or queries.
- Open the Permission Set used for this agent’s business-data access.
- Under Object Settings, grant Read for each required object.
- Grant read access for each required field.
- Confirm that sharing gives the Agentforce principal access to the two test Accounts.
- Review applicable restriction rules and scoping rules.
- Do not grant edit or delete access merely to run these actions. The actions do not update the checked record.
Rejection test: remove read access to one required field, run the affected Check, and confirm
that the response does not claim a reliable PASS. Restore the field access after the test.
Step 5: Create a focused subagent or topic
Section titled “Step 5: Create a focused subagent or topic”Agentforce Builder labels vary between the topic-based and newer subagent-based experiences. Use a focused topic or subagent that owns record-health questions rather than adding the actions to an unrelated general-purpose area.
- Open the agent in Agentforce Builder.
- Create a topic or subagent for record-health questions.
- Enter a clear name such as
Account Record Health. - Describe its scope: it answers whether one Account satisfies a named Record Health Check or Check Set.
- Add instructions that require a real action result before claiming health.
- Add instructions that exclude requests to change records, expose diagnostics, or invent a result.
- Save the topic or subagent.
Example instructions:
Use the Record Health Check Set action when the user asks for the overall health,readiness, completeness, or quality of one Account under My_Account_Checks.
Use the single Record Health Check action only when the user asks for one specificallynamed Check. Never infer health from conversation text or fields already shown to you.
Report PASS and FAIL as completed health results. Treat SKIPPED as not applicable or notrun. Never translate UNABLE_TO_EVALUATE or ERROR into PASS. Do not claim a result if theaction reports success=false.Replace the example Check Set name in the instructions with the exact name used by the action.
Step 6: Add the Check Set action
Section titled “Step 6: Add the Check Set action”- In the record-health topic or subagent, select the option to add or create an action.
- Choose Apex as the reference action type.
- Choose Invocable Method as the reference action category when that field appears.
- Select Run Record Health Check Set for Agentforce as the reference action.
- Give the agent action a clear name such as
Evaluate Account Check Set. - Describe when to use it: evaluate one record under one exact Record Health Check Set when the user asks for overall health, readiness, completeness, or quality.
- Keep Record ID as a required input. It must be the ID of the record being evaluated.
- Keep Check Set Qualified API Name as a required input.
- Configure the exact value
My_Account_Checkswhen the action design permits a fixed input. If the value remains model-supplied, state the one approved exact name in the action instructions. - Leave Correlation ID optional. Do not ask the model to place record data or user text in it.
- Make the structured outputs available to the reasoning engine.
- Save the action.
Expected result: the action references the packaged Check Set invocable method and accepts one record ID plus one exact Check Set name.
Step 7: Add the optional single-Check action
Section titled “Step 7: Add the optional single-Check action”Skip this step unless users genuinely ask about one specifically named Check.
- Add another Apex Invocable Method action to the same focused topic or subagent.
- Select Run Record Health Check for Agentforce.
- Give it a name that distinguishes one Check from the complete Check Set.
- Describe exactly which named questions justify this narrower action.
- Keep Record ID and Check Qualified API Name required.
- Fix or constrain the Check Qualified API Name when possible.
- State that the agent must not call both actions for the same request unless the user explicitly asks for a deterministic comparison.
- Save the action.
Adding fewer actions makes selection easier to understand and test. The Check Set action is enough for most record-health adoption scenarios.
Step 8: Verify action inputs and outputs
Section titled “Step 8: Verify action inputs and outputs”Open each action and confirm:
| Item | Required configuration |
|---|---|
| Record ID | One Salesforce record ID; never a list |
| Qualified API Name | Exact Check or Check Set Qualified API Name |
| Correlation ID | Optional safe operational identifier, at most 120 characters |
| Contract Version | Available to reasoning; current actions return 1. |
| Success | Checked before the agent claims any health conclusion |
| Status | Interpreted with the five-state table below |
| Counts | Check Set action exposes passed, failed, skipped, unable, and system-error counts |
| Bounded diagnosis | Optional diagnostic ID, category, summary, and recommended action for a completed evaluation |
| Error fields | Used for a safe explanation, not rewritten as a health result |
The single-Check action also returns a reason code. The Check Set action returns counts instead of individual Check values or messages.
Step 9: Test selection and results in Agentforce Builder
Section titled “Step 9: Test selection and results in Agentforce Builder”- Open Preview or the current Builder testing panel.
- Use the same agent principal that production will use.
- Ask for the known passing Account’s overall health.
- Inspect the interaction details.
- Confirm that the Check Set action ran once with the correct Account ID and Qualified API Name.
- Confirm that the final answer says the Check Set passed.
- Ask the same question for the known failing Account.
- Confirm that the final answer describes
FAILas a completed business finding, not a technical action failure. - Ask an unrelated question and confirm that neither action runs.
- If configured, ask a specifically named Check question and confirm that only the single-Check action runs.
An administrator’s successful preview does not prove the agent user’s access. Confirm the principal shown in the interaction or audit details.
Step 10: Run the negative tests
Section titled “Step 10: Run the negative tests”Test each case separately so that the failed gate is clear. The expected output is what the action returns; the final answer must describe it without claiming a health result the output does not contain.
| Case | Expected action output |
|---|---|
A malformed Qualified API Name, such as My Account Checks | Success false, Error Type VALIDATION, Error Message Check Set Qualified API Name has an invalid format. |
| An unknown but correctly formatted Qualified API Name | Success false, Error Type EXECUTION, Error Message The Check Set request could not be evaluated. The name is not echoed |
| A record the principal cannot read | Success true, Status UNABLE_; the single-Check action returns Reason Code RECORD_ |
| A Check that requires a field the principal cannot read | Success true, Status UNABLE_, Reason Code CANNOT_, Diagnostic Category ACCESS |
| A principal without Record Health Check User | Success false, Error Type AUTHORIZATION, Error Message You do not have permission to run Record Health Checks. |
| A Check that does not apply to the record | Success true, Status SKIPPED |
A Check that returns UNABLE_ | Success true, Status UNABLE_, with the four diagnosis fields |
| A controlled evaluator failure, such as a custom Apex Check that throws | Success true, Status ERROR, Diagnostic Category such as APEX_ |
| Prompt-like instructions stored in a record field or Check message | A normal result. The action returns no field values or messages, so the text never reaches the agent through the action |
| A request that names two records | One action call per record. If Agentforce sends both in one call, each output has Error Type LIMIT and Error Message AGENT_ |
For the single-Check action, the validation message names Check Qualified API Name instead.
For every case, inspect the selected action, exact inputs, structured output, and final answer. The
agent must not disclose inaccessible data, follow prompt-like record content as instructions, or
translate an inconclusive result into PASS.
Step 11: Commit, activate, and monitor
Section titled “Step 11: Commit, activate, and monitor”- Save all topic, subagent, instruction, and action changes.
- Run the complete positive and negative test matrix again.
- Commit or save the agent version using the version controls shown in your Builder experience.
- Activate the tested version.
- Connect only the intended channels and users.
- Review early production interactions for unexpected tool selection and status interpretation.
- Record the agent version, package version, principal, action names, Check names, test evidence, and approver.
- After changing a Check, Check Set, permission, sharing rule, action, or instruction, repeat the affected tests.
- To contain a native-action incident, remove the actions from the agent or deactivate the agent version. Do not uninstall the package or delete Check metadata as the first response.
Salesforce publishes a detailed current example of creating an Invocable Method action in Agentforce Builder. Use it when the current Builder labels differ from this guide.
Interpret action output
Section titled “Interpret action output”Both actions use contract version 1.0 and return success, operation, status, and a correlation
ID. Operation is RUN_CHECK for the single-Check action and RUN_CHECK_SET for the Check Set
action. The Check action can return a reason code. The Check Set action returns explicit counts and
one overall Status, chosen in this order:
ERRORwhen any Check returnedERROR.- Otherwise
UNABLE_TO_EVALUATEwhen any Check returnedUNABLE_TO_EVALUATE. - Otherwise
FAILwhen any Check returnedFAIL. - Otherwise
PASSwhen any Check returnedPASS. - Otherwise
SKIPPED: every Check was skipped, or the Check Set has no active Checks.
A completed evaluation can also return bounded diagnosticId, diagnosticCategory,
diagnosticSummary, and recommendedAction values. They appear when a Check returns
UNABLE_TO_EVALUATE or ERROR; for the Check Set action they describe the first such Check. These
fields are disclosure-safe guidance, not raw administrator diagnostics. The
Agent tool contract explains
every Diagnostic Category value.
Correlation ID returns the caller’s value when it is valid: 1–120 letters, numbers, periods,
underscores, colons, or hyphens. A completed evaluation also uses it as the Run ID. Without a value,
a completed evaluation returns its generated Run ID, and an error returns a generated value that
starts with agent-.
When Success is false, Error Type is one of these values and Status is blank:
| Error Type | Cause |
|---|---|
AUTHORIZATION | The principal lacks the Record Health Check Run Custom Permission |
VALIDATION | Record ID or the Qualified API Name is missing, the name is longer than 255 characters or has an invalid format, or Correlation ID is invalid |
LIMIT | Agentforce sent more than one request in one call |
EXECUTION | Evaluation could not start or complete: for example, the Check or Check Set does not exist or is inactive, or the record belongs to another object. The error is logged as AGENT_ or AGENT_ |
| Output | Agent behavior |
|---|---|
success=false | Report the safe adapter error. Do not claim any health status. |
PASS | State that the selected Check or Check Set passed. |
FAIL | State that evaluation completed and found a business condition requiring attention. |
SKIPPED | State that the Check did not apply or did not run. |
UNABLE_ | State that no reliable conclusion was reached. Never translate it to PASS. |
ERROR | State that a system or evaluator problem prevented a reliable result. Never translate it to PASS. |
The actions do not return Found or Expected values, display messages, action URLs, raw serialized results, queries, formulas, stack traces, record values, or administrator-only diagnostics. Report only the bounded diagnosis supplied by the action; do not infer additional technical detail.
The exact Salesforce output labels are:
| Output | Single Check | Check Set | Meaning |
|---|---|---|---|
| Contract Version | Yes | Yes | Version of the action response contract |
| Correlation ID | Yes | Yes | Caller-supplied or generated safe correlation value |
| Success | Yes | Yes | Whether the action returned a completed adapter response |
| Operation | Yes | Yes | Check or Check Set operation that ran |
| Status | Yes | Yes | Five-state health result |
| Reason Code | Yes | No | Stable reason for the single Check result |
| Passed Count | No | Yes | Checks that passed |
| Failed Count | No | Yes | Checks that found a business problem |
| Skipped Count | No | Yes | Checks that did not apply or run |
| Unable Count | No | Yes | Checks that could not reach a reliable conclusion |
| System Error Count | No | Yes | Checks stopped by a system or evaluator error |
| Error Type | Yes | Yes | Stable adapter error category |
| Error Message | Yes | Yes | Safe error explanation |
| Diagnostic ID | Yes | Yes | Safe incident identifier when available |
| Diagnostic Category | Yes | Yes | Bounded diagnostic category |
| Diagnostic Summary | Yes | Yes | Value-free diagnostic explanation |
| Recommended Action | Yes | Yes | Safe next troubleshooting step |
Limits and side effects
Section titled “Limits and side effects”Each action call accepts exactly one request for one record. More than one input returns aligned
LIMIT responses with AGENT_SINGLE_RECORD_REQUIRED.
The model cannot select event publication. Native Agentforce actions always use NONE, so invoking
an action does not publish Record Health Check result events. The evaluation remains read-only and
does not update the checked record.
Test before activation
Section titled “Test before activation”Before activating an agent version, and after every change to a Check, Check Set, permission, sharing rule, action, or instruction, repeat Step 9 and Step 10 with the intended principal. Add a Check Set whose Checks return a mixture of statuses, and confirm that the overall Status follows the order in Interpret action output. An administrator’s successful test does not prove that the production Agentforce principal has the intended access.