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 trade-offs 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.

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:

Strategic planning is a critical part of deploying an AI agent. If your organisation doesn't have a strategy in place, we suggest taking the AI Strategy badge on Trailhead . From here on out, we assume you're already familiar with the process of defining your AI vision, forming an AI council, establishing AI governance, identifying AI use cases, and building a roadmap.

Building an agent requires time and resources. Careful planning will help you get it right the first time. Before you begin building any agent, define a use case and create a process map for each agent you plan to build. The Agent Planning badge on Trailhead covers process mapping in the "Outline the Agent's Work " unit. Outline the ideal user experience, as well as how the system will respond to user input and handle potential errors or issues.

The resulting diagram will help ensure you understand the flow. It will help you generate instructions and know where to use actions, variables, and filters. Benefits of this agent planning approach include the following:

• Engage business users and agree on scope
• Define Actions, instructions, and guardrails
• Generate clear, specific instructions
• Debug during testing and evaluation
• Evaluate end-to-end scenarios
• Demonstrate compliance and audit trail
• Explain expected agent behaviour and get sign off

Before we continue, it's important to note that agents aren't the only generative AI tool available on the Salesforce Platform. 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 its 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 whilst 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 routing 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 details of customer's problem with possible solutions and relevant knowledge articles from your customer-facing website
• Scheduling an appointment based on service representative availability and customer preference
• Detecting events, such as software update issues, and proactively generating troubleshooting tasks or attempting remote resolution by triggering an action to invoke 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 as 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 the 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 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 custom agent actions to further extend your implementation. However, you should always check to see if a standard action can be used before creating a custom action. Design actions with reusability in mind, as they can be used across multiple topics. Below is a list of the custom 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 alongside the original user message and conversation history, typically the last six turns. The resulting prompt is sent to the LLM to determine what the agent should do next.

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, and Actions, and decides whether to run another Action or formulate a response.
• This loop continues until the agent determines it has all the 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 checks 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:

1. Improved Topic Classification Accuracy

By removing irrelevant topics from consideration based on conversation state, you reduce the “semantic noise” during the topic classification process. This makes it easier for the LLM to select the correct topic for a 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 custom 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
• Custom 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.

Custom 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 are based on the values of context and custom variables. 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 allow these topics to be called.

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, meaning their outcomes can vary based on the model's understanding and interpretation.
3. Filters restrict agent decisions: They completely remove options from consideration, which minimises the search space, leading to better accuracy.

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. The diagram below shows 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 jumper yesterday but I need to change the delivery address.”

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

• The reasoning engine brings the “Change Delivery Time” or “Change Address” topic to the focus prompt and includes the topic's scope, instructions, and available actions along with the conversation history and 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 shipping address (using “Update Order Shipping” action)

• The engine asks the customer for their email to find the order
• Once the order is located, it collects the new shipping address
• It runs the “Update Order Shipping” 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 easily recognisable names
• Use short, descriptive names
• Start names with verbs, like provide, change, or cancel
• Make sure different topic names don't overlap in meaning
• Review existing topics before creating new ones
• 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 users 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 login details.”
2. The reasoning engine matches this to the Password Reset topic because the Classification Description mentions “forgotten passwords, login 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 user 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.

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, whilst 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 does not have 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. Analyses the customer's message and the selected topic
2. Reviews the available actions in that topic
3. Decides which action(s) to use based on:
   - 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 reused 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.

Agent Planning: Outline the Agent's Work
https://trailhead.salesforce.com/content/learn/modules/agentforce-agent-planning/outline-the-agents-work

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