Legacy Guide: Agentforce Reasoning, Subagents, Instructions, and Actions

This guide covers a legacy experience. It applies to the legacy Agentforce builder under Setup → Agents.

As of December 2025, a new agent building experience is available via the App Launcher. We recommend using the new experience, which gives you greater control over agent behavior and outcomes. Click here to switch to the new Agentforce Guide to Hybrid Reasoning, Script, Subagents, and Actions.

Interface and steps differ between that new experience and the legacy experience outlined below.

Additionally, key terminology changes are in progress. As of April 2026, these terms are changing to align with industry norms.

• Topics are now subagents.
• Topic Selector is now Agent Router
• Connected Agent is now Connected Subagent

Thanks for your patience as we update those terms across resources, including the graphics in this guide.

AI agents are revolutionizing organizations by increasing efficiency, reducing manual effort, and creating a more sophisticated and adaptive workplace.

This guide explores the core elements of Agentforce, the Salesforce platform for building AI agents. In this resource, you’ll find details on how Agentforce works, and the key capabilities and tradeoffs that technical practitioners need to know when building with Agentforce.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 Subagents, Instructions, and Actions
• Does Agentforce Need Data 360?
• Closing Remarks
• Resources

• Agents are different from other generative AI tools like chatbots, co-pilots and prompts because they can plan, reason and take action with or without human intervention.
• Prompt engineering is key to building agents. It’s the primary method for guiding an agent’s behavior and controlling outcomes through subagents, actions, and instructions, and it’s essential for designing effective prompt-template powered actions.
• Subagents, actions, and instructions drive the Reasoning Engine, making Agentforce work for you.
• Since Agentforce is part of the Agentforce 360 Platform, agents built with Agentforce can use the low-code and pro-code actions you’re already familiar with.
• Data 360 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.

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 it needs to reach its goal, identify what data is needed, and then take action, with or without human intervention. 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 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 organization 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 behavior and get sign off

Before we continue, it’s important to note that agents aren’t the only generative AI tool available on the Agentforce 360 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—honoring 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 summarize 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 via agent actions. 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 summarizing 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 judgment 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 rep 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

Let’s explore how Agentforce understands user requests and decides what actions to take. This section will walk you through the Reasoning Engine at the core of Agentforce’s decision-making process. Just like understanding the order of execution is key to understanding what’s happening when a record gets saved in Salesforce, knowing how the Reasoning Engine operates behind the scenes is key to how Agentforce works.

The 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 – subagents, instructions, and actions – as the levers you control to make agents work for you. When you adjust these elements, you’re 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 subagents and actions. You’re prompt engineering every time you build an agent in the legacy agent builder.

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

Subagents 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 specialized departments with specific expertise, actions that lead to action, and instructions. When a customer sends a message, your agent first determines which “department” (subagent) should handle the request, then follows that department’s guidelines and uses its tools to help the customer. Subagents 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 subagent, guiding action selection, setting conversation patterns, and providing business context. Clear and distinct subagents prevent overlap and ensure the Reasoning Engine correctly classifies customer requests. Instructions should be clear, specific, and actionable to guide the agent effectively.

Your agent uses actions 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 subagent 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. 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 subagents. 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 subagents, instructions, and actions to get work done. Here’s a step-by-step breakdown of what happens inside the 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 analyzes the user’s message to classify it under the most relevant subagent. For this classification step, the Reasoning Engine looks at subagent name and subagent classification description only. If no appropriate subagent matches, it uses a default classification.

The scope, instructions, and actions associated with the selected subagent 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 analyzes 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 subagent scope, instruction, and actions, and decides whether to apply 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 subagent. This step checks that the response:

• Is properly grounded in source information
• Adheres to the subagent’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 — subagents, 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. It’s like giving your agents the same dynamic visibility as conditional form fields – so they see exactly what they need, when they need it.

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

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

1. Improved Subagent Classification Accuracy

By removing irrelevant subagents from consideration based on conversation state, you reduce the “semantic noise” during the subagent classification process. This makes it easier for the LLM to select the correct subagent for a user query.

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

2. Contextually Appropriate Action Selection

Once a subagent is selected, filters further refine which actions within that subagent 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 Reasoning Engine supports filtering based on two types of variables: context variables and custom variables. This table shows the properties of each variable 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 personalizing 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 subagent and action level:

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

Here is a simple view of the Reasoning Engine that shows how subagent-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 Subagent, Payment Processing Subagent

This ensures that even if a user asks about their account or payments before authenticating, the agent will not allow these subagents 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 so that you can build agents that are both reliably accurate and contextually adaptive.

1. Filters operate deterministically: They use variable matching to include/exclude subagents 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 minimizes the search space, leading to better accuracy.

Another part of the 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 subagents, instructions, and actions work together with the Reasoning Engine when a customer asks an agent a question.

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

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

• The Reasoning Engine brings the “Change Delivery Time” or “Change Address” subagent to the focus prompt and includes the subagent’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 subagent 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 subagents, actions, and instructions engineer prompts that drive the Reasoning Engine, let’s take a look at some best practices for creating them.

Subagents 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 subagent are the subagent name, classification description, and scope.

• Think: “How would I categorize the ‘Jobs to Be Done’ by my agent?"”
• Use easily recognizable names
• Use short, descriptive names
• Start names with verbs, like provide, change, or cancel
• Make sure different subagent names don’t overlap in meaning
• Review existing subagents before creating new ones
• Limit subagents to 10-15 per agent; too many/overlapping subagents 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 subagent should handle
• Write in natural language, not technical terms
• Make it distinct from other subagent descriptions

If your agent consistently fails to select the correct subagent for user queries, subagent 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 subagent at design time so that an agent can help users reset their passwords. This is what the subagent, instructions, and actions might look like:

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

1. Customer says: “I forgot my login details.”
2. The Reasoning Engine matches this to the Password Reset subagent 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 offers 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 subagent. 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. Guide action selection: Instructions help your agent choose which action to use for specific situations.
2. Set conversation patterns: Instructions establish how your agent should interact with customers.
3. Provide business context: Instructions 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 use: 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 does not have access to their email, use the Security Question Verification action.”

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

When your agent handles a customer request, the Reasoning Engine:

1. Analyzes the customer’s message and the selected subagent
2. Reviews the available actions in that subagent
3. Decides which action(s) to use based on:
   - The action names, action descriptions, and action inputs
   - The subagent 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 minimize latency and improve performance, don't assign more than 15 actions to a subagent, and remember that actions can be reused across subagents.

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

Best practices 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 360 is an integral part of Agentforce because the Data 360 architecture is used for certain features in Agentforce like Agent Analytics and Digital Wallet. Data 360 infrastructure also powers indexing and unstructured data searches, as well as feedback logs and audit trails. Data 360 can also provide additional extensibility. 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 using the hyperscale infrastructure for petabyte-scale data, utilizing Data 360's architecture with Agentforce ensures that customers experience better AI outcomes today. This powerful architecture also 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 360? The following table details the Agentforce features Data 360 provisions by default, along with the optional features customers can enable to extend their implementation.

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

Find blogs, guides, demo videos, and more resources at Agentblazer.com and Agentforce.com

• Long-form guides:
  • Agentforce Guide to Achieving Reliable Agent Behavior: A Framework for 6 Levels of Determinism
  • The Guide to Operating an Agentic Enterprise
  • Agentforce and RAG: Best Practices for Better Agents
  • An Agentforce Guide to Context Engineering
    
    
• For CIOs:
  • A Practical Guide to Reliable AI Agents That Work
  • The Invisible Advantage - 8 key agentic enterprise design principles that have been tested and validated by named CIOs.

• Blog: Doomprompting Won’t Get You Predictable AI Agents, But a New Scripting Language Can
• Dev Blog: Control Agent Access and Decision-Making with Variables and Filters
  
  
• Trailhead: Agent Planning: Outline the Agent’s Work
  
  
• Help documentation:
  • Action Instructions
  • Subagent Instructions
  • Troubleshooting Agents