Introducing the Agentforce Guide

AI agents have the potential to revolutionise organisations by increasing efficiency, reducing manual effort and creating a more sophisticated and adaptive workplace. That’s why we launched Agentforce, a platform for building AI agents. But with new technology comes new concepts and new implementation considerations.

This guide explores the core elements of Agentforce and it’s the first in a series of guides that will evolve alongside Agentforce itself. In this resource you’ll find details on how Agentforce works and the key capabilities and tradeoffs that architects and all technical practitioners, need to know when building with Agentforce.

What we'll cover:

• Key Takeaways
• Agentforce Fundamentals
• Prompts vs. Agents
• How Agentforce Reasons
• Best Practices for Using Filters vs. Instructions
• Best Practices for Topics, Instructions and Actions
• Does Agentforce Need Data Cloud?
• Closing Remarks
• Resources

• Agents are different from other generative AI tools like chatbots, co-pilots and prompts because they can plan, reason and use tools with or without human intervention.
• Prompt engineering is key to building agents. It’s the primary method for guiding an agent’s behaviour and controlling outcomes through topics, actions and instructions and it’s essential for designing effective prompt-template powered actions.
• Topics, actions and instructions are how you control the prompts that drive the reasoning engine. That’s why they’re a key element of making Agentforce work for you.
• Since Agentforce is part of the Salesforce Platform, agents built with Agentforce can use the low-code and pro-code tools you’re already familiar with.
• Data Cloud is an integral part of Agentforce. It powers indexing and chunking for retrieval augmented generation (RAG), agent analytics, bring your own model (BYOM) and digital wallet.
• Agents are amazing, but sometimes a Prompt Template will do.

Simply put, an agent is a type of software that uses generative AI to make decisions about what to do next and how to do it. An agent can understand a question (often called an utterance), autonomously reason to determine what actions to take to reach its goal, identify what data is needed and then take action, with or without human intervention. The best part? Agents use large language models (LLMs) instead of strict, pre-written rules. This makes agents more dynamic than rules-based automation, but it’s also a significant shift from traditional software that follows hard-coded instructions.

Key capabilities of AI agents

• Agents are dynamic and can adapt to different situations, environments and information.
• Agents can be autonomous (act without human intervention) or can be guided to involve a human in the loop.
• Agents are different from other generative AI tools because they can plan, reason and act.

At Salesforce, we have a specific way of defining what an agent is and what it’s not. For Salesforce, a feature is considered an agent only if it uses the Atlas Reasoning Engine. That’s because the reasoning engine is how Agentforce understands, decides and acts. Later on in this guide we’ll go pretty deep into the how the reasoning engine works, but if you can’t wait until then, check out the video below:

While agents don’t follow hard-coded logic like traditional software, Agentforce provides a number of components to add additional controls to how your agents reason. There are also a number of features that make Agentforce extensible. Here’s a quick look at these components:

Before we continue, it’s important to note that agents aren’t the only generative AI tool available to use on the Data Cloud. Prompt templates are another powerful tool for building applications that use generative AI. Prompt templates, built in Prompt Builder, allow you to define a set of structured, reusable instructions that guide a generative AI model to produce specific outputs. They can reference Salesforce data through predefined fields, data graphs and contextual data retrieval augmented generation (RAG). Prompt templates are also highly secure-all prompts are routed through Salesforce’s trust layer—honouring permissions, masking sensitive data and flagging toxic outputs.

Prompt templates are single-turn interactions with AI and are an ideal fit for one-off tasks that don’t require memory or multi-step reasoning. For example, a prompt template is ideal when you need to reword a sentence or summarise a case, because ongoing context isn’t needed. When designing solutions with prompt templates it’s important to remember that they are stateless (they don’t retain memory between turns) and that they do not make decisions or take actions. Prompt templates generate a response based on the input and logic you provide at design time.

Prompt templates can be used on their own in an embedded AI solution or you can add a Prompt template to an agent as an agent action. Using a prompt template on it’s own is ideal when:

• Business context is well understood and stable
• The desired output follows a predictable format, though the response itself is not deterministic
• There is no need to evaluate different paths or take autonomous actions
• Ongoing context or state, is not required
• Multi-step reasoning is not required

Prompt template use cases:

• Generating a structured record summary like summarising case notes
• Creating structured meeting notes
• Generating templated email responses
• Suggesting next best actions
• Identifying a sentiment analysis of a case

Keep in mind that while Prompt templates can dynamically fill in data and generate responses based on the dynamic inputs that get rendered at run time, they cannot reason through options or take action.

Agents are software systems that autonomously decide what to do, in what order and how to do it, based on evolving context. Agents go beyond a single prompt as they can plan, reason, call external actions (like API calls or database lookups) and react based on outcomes. They can choose different paths or responses depending on what they learn mid-process. Agents are best when:

• The environment or context can change dynamically
• Multiple decisions or branches are possible based on data
• AI needs to replace or assist human judgement in making a choice or taking action

AI agent use cases:

• Triaging and routeing incoming support cases
• Resolving booking issues by checking external systems and policies
• Managing multi-step workflows with feedback loops
• Drafting a case response email based on the detail of customer’s problem with possible solutions and relevant knowledge articles from your customer facing website
• Scheduling an appointment based on service rep availability and customer preference
• Detecting events, for example a software update issue and proactively generating a troubleshooting task (or even attempting to resolve the issue remotely by triggering an action that invokes an API call!)

Looking to understand how Agentforce understands user requests and decides what actions to take?This section will walk you through the core of its decision-making process: the Atlas Reasoning Engine. Just like understanding the Order of Execution is key to understanding what’s happening when a record gets saved in Salesforce, knowing how the Atlas Reasoning Engine operates behind the scenes empowers you to understand how Agentforce works.

The Atlas Reasoning Engine uses a series of prompts, code, LLM calls and a set of three key building blocks to help agents understand and respond effectively. Think of the following three elements (topics, instructions and actions) as the levers that you control to make agents work for you. When you adjust these elements, you are engineering the prompts that reasoning engine uses to understand, decide and act. That’s right: Agentforce uses prompts in the reasoning engine to classify topics and actions. Which means, you’re prompt engineering every time you build an agent in Agent Builder!

Before we dive in deeper into the Atlas Reasoning Engine, let’s take a closer look at topics, instructions and actions, three important pieces of metadata that you define each time you build an agent with Agentforce.

Topics are the foundation of your agent’s capabilities, defining what it can do and the types of customer requests it can handle. Think of them as specialised departments with specific expertise, tools (Actions) and guidelines (Instructions). When a customer sends a message, your agent first determines which “department” (Topic) should handle the request, then follows that department’s guidelines and uses its tools to help the customer. Topics also have a scope that defines what an agent can and cannot do within that specific topic area.

Instructions are the guidelines that direct how conversations are handled within a topic, guiding action selection, setting conversation patterns and providing business context. Clear and distinct topics prevent overlap and ensure the reasoning engine correctly classifies customer requests. Instructions should be clear, specific and actionable to guide the agent effectively.

Actions serve as the tools your agent uses to get information or perform tasks. When defining actions, it’s crucial to understand how the reasoning engine processes them. The engine reviews available actions based on their names, descriptions and inputs, as well as the topic instructions and conversation context. Agentforce comes with a number of standard agent actions, and you can create customised agent actions to further extend your implementation. However, you should always check to see if a standard action can be used before creating a customised action. Below is a list of the customised agent actions available and when you should use them:

You might be wondering exactly how an agent uses topics, instructions and actions to get work done. Here’s a step-by-step breakdown of what happens inside the Atlas Reasoning Engine whenever an agent is invoked.

The process begins when a message or query is received from a user or when an agent is invoked from an event, data change or API call.

The reasoning engine analyses the user’s message to classify it under the most relevant Topic. For this classification step, the reasoning engine looks at topic name and topic classification description only. If no appropriate topic matches, it defaults to an “off-topic” classification.

The Scope, Instructions and Actions associated with the selected Topic are injected into the prompt along with the original user message and conversation history (on average, the last six turns of the conversation). This prompt is then sent to the LLM to decide what the agent should do next based on the user message.

The agent analyses the combined input (user message, instructions, potential actions) and decides the next step:

• Run an Action: If specific information is needed or a task must be performed.
• Respond to User: If it has enough information or is looking for information, the agent can send a reply.

• The agent invokes the chosen Action.
• The output or result from the executed Action is captured.
• Action Output Processing: The Action’s output is sent back to the LLM, combined again with the original context (instructions, actions, conversation history).

• The agent re-evaluates the situation based on the new information (action output) and the ongoing conversation context.
• The output is sent along with the focus Topic Scope, Instruction + Actions and decides whether to run another Action or formulate a response.
• This loop continues until the agent determines it has all necessary information and is ready to respond directly to the user.

Before sending the final response, the agent performs one last check to ensure its proposed response is grounded in and adheres to the provided Instructions for the Topic. This step is checking that the response:

• Is properly grounded in source information
• Adheres to the topic’s instructions and scope
• Does not include hallucinated or unverified information
• Is free from potential prompt injection risks

The final, validated response is sent to the user. If the grounding step fails, the agent will retry and attempt to produce a grounded response. If it’s not able to produce a grounded response, it will send a standard message to inform the user it can’t help with the request.

Understanding this workflow helps explain why each component of your agent — topics, instructions and actions — must be carefully designed to work with this reasoning process. But it doesn’t stop there.

To provide additional control and add deterministic logic to your agentic workflow, Agentforce uses Conditional Filtering. This is like having dynamic visibility rules for form fields, but for your agents when reasoning.

Conditional filters act as gatekeepers that determine whether a topic or action should be considered during the reasoning process. Unlike instructions that guide the LLM’s decisions, filters operate at a system level to completely remove or include topics and actions based on specific conditions.

Conditional filtering enhances the agent’s performance in two critical ways:

By removing irrelevant topics from consideration based on conversation state, you reduce the “semantic noise” during the topic classification process. This narrows the decision space for the LLM, making it easier to select the correct topic for a given user query.

For example, if a user hasn’t yet authenticated, filters can hide all topics related to account-specific actions. This prevents the agent from misclassifying general queries into sensitive topics that would ultimately lead to authentication errors or inappropriate responses.

2. Contextually Appropriate Action Selection

Once a topic is selected, filters further refine which actions within that topic are available based on the current conversation state:

• If required variables aren’t populated (e.g., order number), actions that depend on those variables can be hidden
• If certain actions should only be available based on user attributes or entitlements, filters can enforce those rules

How Conditional Filtering Works

The Atlas Reasoning Engine supports filtering based on two types of variables: context variables and customised variables. Here’s a quick overview of the properties of each type:

These are variables derived from the messaging session and can include:

• Standard fields from the Messaging Session object
• Customised fields added to the Messaging Session object
• Pre-chat form data
• Information from previous messaging sessions

Context variables are particularly useful for personalising interactions based on known customer information without requiring the agent to ask for it conversationally. When designing a solution with context variables, it’s important to be aware that they are set at session initiation and are immutable during that session.

Customised variables store information returned from actions. These can be used for:

• Tracking conversation state (e.g., authentication status)
• Storing action outputs that need to persist into action inputs
• Creating dependencies between actions, enabling actions to be available only if a certain condition is met

Filters can be applied at both the topic and action level:

• Topic-level filters: Control whether the entire topic is available for classification
• Action-level filters: Control availability of specific actions within a topic, even if the topic itself is selected

Here is a simple view of the Atlas Reasoning Engine that shows how topic-level and action-level filters fit into the reasoning flow.

The most common use case for filtering is controlling access to sensitive operations:

Filter: "Requires Authentication"

Condition: authenticationStatus = "verified"

Applied to: Account Management Topic, Payment Processing Topic

This ensures that even if a user asks about their account or payments before authenticating, the agent will not classify those requests to the sensitive topics.

Filters can also help process steps run in the correct order:

Filter: "Order Number Required"

Condition: orderNumber != null

Applied to: Check Order Status Action, Modify Order Action

This ensures order-related actions are only available after an order number has been collected and stored in a variable.

It’s important to understand the distinction between filtering and instructions:

1. Filters operate deterministically: They use variable matching to include/exclude topics and actions.
2. Instructions are interpreted by the LLM: They rely on the LLM’s understanding and are non-deterministic.
3. Filters modify the available decision space: They completely remove options from consideration, which minimises the search space, leading to better accuracy.

Instructions guide decisions within the available space: They influence how the LLM chooses among available options.

Another part of the Atlas Reasoning Engine is citations. You can use citations to validate the sources used by the LLM to generate a response. Below you can see where citations fit into the reasoning engine flow.

This diagram also highlights the composable architecture of the reasoning engine. Escalation, citations and guardrails are modular components used by the reasoning engine when building an agent using the Agentforce for Service template. Today, the modular components used by the reasoning engine are set on a template-by-template basis. We’re working to make these components even more like lego pieces that can be swapped in and out of an agent, potentially even by customers in the future.

We’ve covered a lot already. Now let’s take a step back and walk through a complete example of how topics, instructions and actions work together with the reasoning engine when a customer asks an agent a question.

Customer Message: “I ordered a red pullover yesterday but I need to change the delivery address.”

• The engine compares the message to all topic names and classification descriptions
• It selects the “Order Management” topic because its classification description mentions “changing orders”

• The reasoning engine brings the “Order Management” topic to the focus prompt and includes the topic’s scope, instructions and available actions along with the conversation history + user message
• The scope indicates that the agent can modify orders but cannot cancel orders after they’ve been processed
• The instructions include guidance on handling order modifications

• Based on the topic instructions and action descriptions, the engine determines it needs to:
  • First identify the order (using “Find Order by Description” action)
  • Then update the delivery address (using “Update Order Delivery” action)

• The engine asks the customer for their email to find the order
• Once the order is located, it collects the new delivery address
• It runs the “Update Order Delivery” action with the order ID and new address
• It confirms the address change with the customer

Now that you understand how the reasoning engine works and why topics, actions and instructions are so important, let’s take a look at some best practices for creating them.

Topics are the foundation of your agent’s capabilities. They define what your agent knows how to do and what kinds of customer requests it can handle. The three elements of a topic are the topic name, classification description and scope.

• Think: “How would I categorise the ‘Jobs to Be Done’ by my agent?"”
• Use names customers would recognise and understand
• Keep names short (2-3 words maximum) but descriptive
• Make sure different topic names don’t overlap in meaning
• Before creating a new topic, consider if an existing topic can be used.
• Limit topics to 10-15 per agent, too many/overlapping topics increases the probability the agent will be inconsistent or inaccurate

• Include the different ways customers might ask for this type of help
• List specific keywords and phrases customers typically use
• Cover the full range of questions this topic should handle
• Write in natural language, not technical terms
• Make it distinct from other topics’ descriptions

If you find the Agent is consistently failing to select the correct Topic for user queries, the Topic Names and Descriptions are the first place you should investigate and refine.

• Write this as if you’re explaining a job to a new employee: “Your job is to... You cannot…”
  • Be explicit about both permissions and limitations
• Use clear, unambiguous language about boundaries

Let’s see how to configure a topic at design time so that an agent can help users reset their passwords. This is what the topics, instructions and actions might look like:

Then at runtime, when a customer is interacting with our agent from a company’s website, here is what happens:

1. Customer says: “I forgot my log in details.”
2. The reasoning engine matches this to the Password Reset topic because the Classification Description mentions “forgotten passwords, log in problems, account access issues.”
3. The Scope tells the agent it can help with password resets but cannot access account information or make account changes.
4. The agent follows the Instructions to first verify the customer’s identity, then offer to send a password reset link.
5. The agent uses the Send Password Reset Email action to complete the task.

Instructions are the guidelines that tell your agent how to handle conversations within a topic. Instructions help the agent make decisions about what actions to take and how to respond.

Instructions play several crucial roles in your agent’s decision-making process:

1. Guiding action selection: They help your agent choose which action to use for specific situations.
2. Setting conversation patterns: They establish how your agent should interact with customers.
3. Providing business context: They help your agent understand your company’s processes and terminology.

Without clear instructions, your agent might select the wrong actions, misunderstand customer requests or provide inconsistent responses. But remember that instructions are merged into a prompt and sent to the LLM and are therefore non-deterministic. They do not replace the need for coded business rules within the action.

Begin with just 1-3 key instructions. Add more only as needed after testing. Remember that each instruction should be clear, specific and actionable.

When the reasoning engine processes a customer request, it uses your instructions to:

1. Decide which actions to run: Instructions help the engine determine which action is most appropriate for a specific situation.
2. Determine the sequence of steps: Instructions can guide the engine on whether certain steps should be run before others. For more determinism, you can use action variables and conditional filters.
3. Format the response: Instructions shape how information is presented back to the customer.
4. Handle exceptions: Instructions tell the engine what to do when standard processes don’t apply. (For example, if an edge case occurs, offer to escalate to an agent.)

The more clear and specific your instructions are, the more consistently your agent will perform.

When building your agent, it’s crucial to understand when to use instructions vs. actions to implement functionality. Use Actions for critical business logic that must be consistently enforced, such as complex calculations, sensitive information processing and multi-step operations that require specific sequencing. In contrast, use Instructions for guiding conversation flow, helping the agent select appropriate actions based on context, defining response formatting and tone and establishing clarification strategies when information is ambiguous.

• Bad example: “Never issue refunds for orders older than 30 days” (as an instruction)
• Better approach: Build this logic into the Refund Order action itself with a date input and do the validation on the action

Refund Order Action Example:

public with sharing class RefundOrderHandler {

public class RefundResult {

@AuraEnabled public Boolean canReturn;

@AuraEnabled public String message;

}

@AuraEnabled

public static RefundResult processRefund(ID orderId, Date orderDate) {

RefundResult result = new RefundResult();

if (orderDate == null || orderId == null) {

result.canReturn = false;

result.message = 'Invalid input: Order ID and Order Date are required.';

return result;

}

Date today = Date.today();

Integer daysSinceOrder = today.daysBetween(orderDate);

if (daysSinceOrder > 30) {

result.canReturn = false;

result.message = 'Order cannot be returned. More than 30 days have passed.';

} else {

result.canReturn = true;

result.message = 'Order can be returned. Sending return slip.';

sendReturnEmail(orderId);

}

return result;

}

• Define your terms: Don’t assume the agent knows what industry terms mean.
  • Example: “Promo codes are used for discounts during checkout, while registration codes are used to register products for warranty.”
• Be specific about sequences: If steps should happen in a certain order, state it clearly and include them in one instruction box.
  • Example: “First verify the customer’s identity using the Verify Customer action, then provide account information.”
• Use consistent terminology: Use the same terms throughout all your instructions.
  • Bad example: "Check the client’s info" in one instruction and "verify the customer’s details" in another
  • Good example: Use "customer" consistently and refer to actions by their exact names
• Be wary of absolutes: Words like “always” and “never” are taken very literally.
  • Absolutes can have a significant impact on how your agent interacts. Make sure you are intentional about how they are used in instructions.
• Pair actions with situations: Clearly specify which actions to use in which circumstances.
  • Example: “Use the Track Order action when customers ask about package location or delivery dates.”
• Provide decision criteria: Help your agent make choices between similar options.
  • Example: “If the customer has access to their email, use the Email Password Reset action. If the user hasn't got access to their email, use the Security Question Verification action.”

Actions are the tools your agent uses to get information or perform tasks.

When your agent handles a customer request, the reasoning engine:

1. Reviews the available actions in that topic
2. Decides which action(s) to use based on:
3. The action names, action description and action inputs
   
   - The topic instructions that reference actions
   - The context of the conversation

4. Runs the selected action with appropriate inputs

5. Uses the action’s output to formulate a response or determine next steps

For this process to work effectively, your actions need clear, descriptive names and instructions that help the reasoning engine understand when and how to use them. To minimise latency and improve performance, do not assign more than 15 actions to a topic and remember that actions can be replicated across topics!

Each action in your agent has three important parts that need to be configured: action name, action instructions and action input instructions.

• Use plain language that matches how customers would describe the action.
• Since the Action API Name is sent to the reasoning engine ensure that the API Name is clear and describes the functionality.

Best Practices for Action Instructions:

• Write 1-3 sentences explaining exactly what the action does
• Specify when this action should be used (types of customer requests)
• List what information the action needs to run successfully
• Mention any special conditions or edge cases the action handles
• Include example customer phrases that should trigger this action

Key Tips for Action Input Instructions:

• Clearly describe what the input is and its purpose
• Specify the expected format (length, characters, structure)
• Include validation criteria or formatting requirements

This is a question we hear from our customers often. The short answer, yes. Data Cloud is an integral part of Agentforce because the Data Cloud architecture is leveraged for certain features in Agentforce like agent analytics and digital wallet. Additionally, Data Cloud infrastructure powers indexing and searching for unstructured data, as well as feedback logging & audit trail. Data Cloud can also provide additional extensibility to Agentforce Customers can also choose to enable features like Bring Your Own Lake (BYOL) and Bring Your Own Large Language Model (BYO-LLM) to use data and models built on platforms outside of Salesforce with agents built on Agentforce.

From accessing data from other data lakes through data federation, to utilising the hyperscale infrastructure for petabyte-scale data, utilising Data Cloud's architecture with Agentforce ensures that customers experience better AI outcomes today and ensures long-term viability for successful agent adoption, no matter how big or complex the underlying datasets that power those agents may be.

Curious what specific Agentforce features are powered by Data Cloud? Below you’ll find a summary of the Agentforce features supported by Data Cloud by default and the optional Data Cloud features that can be turned on by customers looking to extend their implementation.

We’ve covered the key elements that make Agentforce work, including the Atlas Reasoning Engine and how to use topics, instructions and actions. Understanding these components is key to using Agentforce effectively. Remember to use this guide as you begin to implement Agentforce to improve your Agentforce outcomes. We encourage you to check out the provided resources to learn more.

Action Instructions:
https://help.salesforce.com/s/articleview?id=ai.copilot_actions_instructions.htm&type=5

Topic Instructions:
https://help.salesforce.com/s/articleview?id=ai.copilot_topics_instructions.htm&type=5

Troubleshooting Agents:
https://help.salesforce.com/s/articleview?id=ai.copilot_troubleshoot.htm&type=5

Agentforce Variables:
https://developer.salesforce.com/blogs/2025/04/agentforce-variables-a-new-way-to-structure-agent-memory

https://developer.salesforce.com/blogs/2025/04/control-agent-access-and-decision-making-with-variables-and-filters