Best Practices for Agent Action Instructions
Action instructions tell an agent what your action does and when to use it. When you create a custom action, carefully plan and test your instructions to ensure that your action performs as expected.
Required Editions
| Available in: Lightning Experience |
| Available in: Enterprise, Performance, Unlimited, and Developer Editions. Required add-on licenses vary by agent type. |
The names and instructions for agent actions and their inputs and outputs determine when and how an action is used. AI agents use a large language model (LLM) and the reasoning engine to search through all subagents and actions assigned to an agent and select one or more to execute in the conversation, based on the user’s question or request. The more effective the instructions, the more predictably the action performs.
Effective instructions vary by action and use case. For best results, test your action in Agentforce Builder and iterate until your action meets your requirements.
Instructions for Actions
Action instructions describe what your action does and when to use it in a conversation. The most important element of action instructions is a concise natural language description of what your action does, usually one to three sentences written as an instruction to the LLM. The description can include the goal or task of the action, any use cases for the action, and the objects or records it uses or modifies. In general, the more relevant detail you include in your instructions, the easier it is for the LLM to differentiate between actions.
| Example Agent Action | Less Effective Description | More Effective Description |
|---|---|---|
| Update Contact Phone Number | Updates a phone number. | Updates the user’s phone number associated with their contact record. If no matching contact exists, creates a new contact record. |
| Query Records | Provides the ability to use natural language to query information about Salesforce CRM records. | Finds and retrieves Salesforce CRM records based on user input and specific conditions, such as field values. This action automatically identifies the correct records and object type. |
| Track Order | Action to get tracking information for an order. | Returns tracking information for a customer order based on the tracking number and destination ZIP code. |
In many cases, the natural language description is all that’s required for an agent to use your action as expected. However, some actions require more details after testing. Here are some options for refining your action description.
| What to Include | When to Use | Examples |
|---|---|---|
| One to three utterances, or example customer inputs | Include examples of customer messages that you expect to trigger your action to help the LLM match a given customer input to your action. If you include multiple utterances, minimize overlap.
|
|
| Dependent actions | Some actions use other actions, often system actions, to get required information. If a required action is missing from a plan or actions aren’t being called in the right order, you can specify them by API name. | The action IdentifyRecordByName must be called directly prior to this action to get a single record ID as input. If the IdentifyRecordByName action is part of the plan, it must run before GetRecordFieldsAndValues. |
| Examples of how you want the action to function | Examples don’t generalize well, but they can be helpful when an agent makes a consistent mistake. In general, LLMs understand examples of what to do better than examples of what not to do, but you can test with either. |
This action should be called only when a more specific summarization action isn’t available. |
Instructions for Inputs and Outputs
Instructions for inputs and outputs describe how to format and use the parameter. In the instructions for an input, specify what information is required to complete the action. In the instructions for an output, specify the result of the action and what an agent returns to the user.
LLMs don’t have a complete understanding of context, including the Salesforce context. In other words, an LLM doesn’t always know the number of characters in a Salesforce record ID or the names of Salesforce objects. Concise but detailed instructions help an agent retrieve necessary information and return relevant results. The best way to determine the right level of detail is to test and iterate on your instructions.
When writing instructions for an input or an output, consider:
- The data type of the information: “an 18-character ID,” “a rich-text answer to the user’s question.”
- Any specific fields or values: “contains the contact ID and expected delivery date”.
- How the information is retrieved or generated: “For a new email, retrieve the ID from the user's input. For a revised email, retrieve the ID from the conversation history.”
- Any special rules about how you expect the action to be used: “Don’t generate SQL or SOQL.”, “Required only when the user wants to revise an earlier draft.”, “The API name is used to identify Salesforce record field-value pairs from the user request.”
Here are some examples of effective instructions for inputs and outputs.
| Input or Output Parameter | Instructions |
|---|---|
| recordId | The single ID of the Salesforce CRM record to create the summary for. For example: recordId, record_id, recordIds[0], accountId. |
| objectApiName | The API name of the Salesforce object (such as Account or Opportunity) associated with the record the user wants to find. The name can be obtained from the context and doesn’t require the IdentifyObjectByName action. |
| summary | The rich text summary created for the specified record. |
| searchResults | A list of the matching Salesforce CRM record IDs in descending order of relevance. |
| generatedEmail | A JSON object that contains the recipient ID, subject line, and body of the email. |
