At Dreamforce 2024, we unveiled Agentforce, the agentic layer of the Salesforce Platform. Agentforce enables developers to customize pre-built agents, or create and deploy new agents, that work seamlessly across Salesforce apps, Slack, websites, and third-party platforms and apps.

Traditional programming is limited when building intelligent systems. Instead of hard-coding every possible outcome to accomplish specific goals, Agentforce can orchestrate actions using the Atlas Reasoning Engine. As a developer, you build your actions using flows, Apex, or prompt templates, and you add instructions written in natural language to further guide the Atlas Reasoning Engine in orchestrating actions, thus improving its effectiveness.

In this blog post, we’ll explore how to write effective natural language instructions in Agentforce to create agents. We’ll explore various types of instructions, such as topic instructions, action instructions, and input and output instructions. Together, these instructions function as the bridge between your agent’s reasoning and its ability to take meaningful actions on behalf of users.

Developer workflow with Agentforce

Before diving into natural language instructions, it’s important to understand the core workflow for building agents with Agentforce. The diagram below highlights the structured approach and the steps to building agents with Agent Builder.

1. Define topics: Agentforce offers pre-built topics. Topics organize actions into categories that outline the agent’s capabilities and decision-making boundaries. For example, “Order Management” is a topic for actions like updating order status or creating return labels. You can create custom topics for your agent by writing classification descriptions and outlining the scope using natural language.
2. Create actions: Agentforce offers standard actions that are right out of the box. Developers can create custom actions using flows, Apex, or prompt templates. These custom actions are tools that agents use to complete their assigned tasks. You’ll need to provide natural language descriptions for the action and its inputs and outputs.
3. Assign actions to topics: In this step, you’ll link actions to relevant topics to ensure that your agent knows when and how to use them effectively.
4. Set topic instructions: Next, you’ll need to use clear, natural language instructions to guide the agent on how to handle user queries and execute actions.
5. Test: Next, you’ll validate your actions individually and test the agent’s reasoning to ensure it interprets instructions correctly and performs tasks reliably. Testing involves two distinct processes: validating actions logic and testing reasoning. The comparison table below shows how testing actions and reasoning differ from each other. Soon, we will also be sharing docs for an Agentforce Testing Center that will further help to test your agents at scale.
6. Refine: The final step is to refine action instructions and topic classification description, scope, and instructions until you get the acceptable outcome.

Comparison Table

How to write effective instructions for agent actions

To guide your agents effectively, you need clear, structured instructions that align with user queries and task execution. Let’s break this down into key areas.

Topics and instructions

Topics serve as structured containers for actions and instructions. They define the scope of tasks that the agent can handle, ensuring that it responds accurately and consistently. Salesforce provides standard topics, and it is recommended to start with them and edit those. You can also create custom topics from scratch.

Key fields in a topic configuration

• Classification: A concise description of what the topic does. This is used to classify and choose the topic for the user’s query.
  • Example classification description for the Order Management topic: “Manages customer inquiries about order status and return requests.”
• Scope: Defines the specific job that the agent performs, and jobs that agent should not perform.
  • Example: “Handle resending reservation confirmations, but do not create new reservations.”
• Instructions: Clear, actionable guidelines for the agent’s actions within the topic. Instructions are nondeterministic, so they shouldn’t include sensitive or deterministic business rules.
  • Use positive instruction for guidance. For example, “always” is clearer and more effective than “don’t,” since “don’t” requires the LLM to guess the actual correct behavior.
  • Combining multiple instructions within a single instruction box is more effective than separating them across different boxes.
  • For example, all of the instructions below can be in one instruction box as a numbered or bullet list.
    • “Always ask for the mobile device type (iOS or Android) before troubleshooting.”
    • “Never ask for an ID. Use the record name instead.”
    • “If the user doesn’t have an order number, escalate to a live agent.”

Topic classification description vs. scope

The user’s request is classified to a topic using the topic classification description. The agent only uses the topic scope once it is within the topic to provide more information about what can be done with a topic.

Action instructions

Action instructions tell agents what a specific action does and when to trigger it. Well-written instructions ensure that actions are consistent, accurate, and meaningful. Some tips for writing action instructions include:

Be clear and concise

Use one to three straightforward sentences that describe the action’s purpose, goal, and scope.

• Before: “Updates a status field.”
• After: “Updates the Task record’s status to ‘Completed.’ If no Task is found, creates a new one with the specified status.”

Use unique action names

Avoid naming actions similarly, as this can confuse the agent. Use varied but related verbs.

• Instead of: “Get Project Details” and “Get Task Details”
• Use: “Locate Project Details” and “Retrieve Task Information”

Specify dependent actions

If the action requires other actions to run first, be sure to state it. This ensures that the agent executes tasks in the right order.

• Example: “Run IdentifyCustomerAccount before RetrieveBillingHistory to provide the Account ID.”

Instructions for inputs and outputs

Clearly define the data that your action requires (inputs) and the results that it produces (outputs). Precise definitions help the agent handle parameters and return meaningful responses.

• Input: Specify the required data and data types for the input.
• Example: “accountId – The 18-digit unique Account record ID, provided by prior actions or user input.”

• Output: Describe what the action returns.
• Example: balance: “The numeric value representing the current account balance.”
• Example: taskSummary: “A brief description of the completed task, such as ‘Resolved payment issue.’”

Test and refine

After writing instructions:

• Test the agent using Agent Builder and Plan Tracer (shown in screenshot below) to evaluate how the agent interprets your instructions.
• Iterate and refine natural language based on results until the agent consistently meets expectations across user inputs.

Best practices for writing action and topic instructions

• Action and variable instructions are similar to topic instructions, but they are limited to a specific action. Best practice: nest as much action-specific guidance as possible directly into the action configuration. This reduces the complexity of instructions sent to the large language model.
• Validation, especially for the input format, should primarily be handled within actions (using flows/Apex). This is more consistent than relying on topic instructions for formatting control.
• Build sensitive or deterministic business rules into the logic of an action itself, not the topic instructions.
• Agentforce closely follows instructions that specify it “must,” “never,” or “always” perform certain functions, which can lead to unintended issues. It may get “stuck” trying to fulfill a “must” or “always” instruction or interpret a “never” instruction too broadly. Use such instructions sparingly, and prioritize removing them when troubleshooting to identify the root cause.
• Start with minimal topic instructions. If the instructions get too complex and you have a non working agent, try stripping topic instructions or consider moving the complex non deterministic part to a prompt template action type.
• Apply the principle of progressive disclosure for topic description, scope, and instructions. This means presenting only the most essential options upfront and progressively providing more details or advanced features as users interact with the interface.
• If an agent is unable to understand a specific business term, define the term clearly and consistently use it.

Quick checklist for effective action and topic instructions

• Is the action name unique and descriptive?
• Are the action instructions clear, concise, and actionable?
• Have you added information about dependent actions in the action instructions?
• Have you precisely defined all inputs and outputs?
• Have you tested and refined the action and topic instructions in Agent Builder?
• Do you provide diverse example utterances for the agent? (Only applicable for the Agentforce default agent and not Agentforce Service Agent or other agents at this point)

By following these best practices, you can ensure that your Agentforce agents operate smoothly, respond accurately, and provide a seamless user experience. Remember: better instructions lead to smarter agents.

Conclusion

Agentforce offers a new paradigm for developers. Instead of writing code with traditional programming constructs, you guide the LLM’s reasoning through clear, high-level instructions. These instructions tell the reasoning engine how to think through tasks, chain actions, and respond to dynamic conditions. By shifting your focus from “how to code” to “how to guide,” you unlock the true power of Agentforce.

Resources

• Best Practices for Agent Action Instructions
• Best Practices for Writing Topic Instructions

About the author

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with a decade of experience building enterprise-scale products on the Salesforce Platform. Mohith is currently among the lead contributors on Salesforce Stack Exchange, a developer forum where Salesforce Developers can ask questions and share knowledge. You can follow him on LinkedIn.