The Agentforce Guide to Context Engineering
Learn how Agentforce uses hybrid reasoning, subagents, actions, and more for reliable, enterprise-grade agents.
Learn how Agentforce uses hybrid reasoning, subagents, actions, and more for reliable, enterprise-grade agents.
This guide supports the latest Agentforce Builder available through the App Launcher . Refer to the Legacy Guide if you maintain agents via Setup.
AI agents are revolutionising organisations 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. Practitioners use context engineering to provide Agentforce agents with the specific information, actions, and instructions needed to achieve goals. We’ll examine how Agentforce Script uses hybrid reasoning to blend generative AI with deterministic control.
We know that developers build agents in many different environments. We support this flexibility to choose your preferred model and environment for the job.
Whether you build in Claude Code, Labs, Agentforce Studio, or elsewhere, it’s helpful to understand how Agentforce manages the logic and connections behind the scenes.
Context engineering is the successor to prompt engineering. It involves designing a system of subagents, instructions, rules, and actions to provide an agent with the exact information and boundaries it needs to be successful, rather than trying to craft the perfect words in an attempt to coax an LLM to give you exactly the right responses.
What we'll cover:
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.
Key capabilities of AI agents
While agents use large language models (LLMs) to handle natural language and intent, Agentforce also uses Agentforce Script to follow specific business logic. This hybrid reasoning model makes agents more dynamic than traditional automation while remaining as reliable as hard-coded software.
Hybrid reasoning is Agentforce’s approach to combining probabilistic LLM-based reasoning with deterministic, rules-based execution in the same engine.
This gives agents the flexibility of generative AI while maintaining the predictability, control, and auditability that enterprises require.
Deterministic automation and agentic AI don’t have to be an either/or choice. With Agentforce, they work together.
Agentforce Studio
Agentforce Studio is our unified workspace for the entire agent lifecycle.
Agentforce Studio brings together every action you need to build, test, and manage agent behaviour. Three key components of Agentforce Studio help you manage the agent development lifecycle:
Agentforce Studio is your one-stop-shop to continuously improve your agents. With this suite of tools, you can build, test, deploy, monitor, and optimise your agents in a unified way.
Agentforce Studio bridges the gap between technical and non-technical users. Katherine Mains of Conagra Brands describes this as “the ‘Goldilocks Zone’ of design; advanced enough for our architects, yet intuitive enough for our admins to dive right in.”
Answers customers FAQs from your knowledge base and handles creation and management of support cases and escalations to a service rep when needed
Answers sales and pricing questions and qualifies leads from a website while transferring to other agents when required
Agentforce is the framework that provides the predictability your business needs to move past simple FAQs and into high-value work. Hybrid reasoning and Agentforce Script blend control and creativity. Intelligent Context powers agents with the right data at the right time. Agentforce Studio provides a unified workspace to manage the entire system.
Data 360 provides a number of features that make Agentforce extensible. Here’s a quick look at these components:
| Component | When to Use | Skills Required |
|---|---|---|
| Agent Invocable Actions | To invoke an agent from Flow or Apex | Low-code |
| Agent API | To invoke an agent from outside Salesforce | Pro-code |
| Agent Variables | To add additional controls to how your agent reasons through subagent and action selection | Low-code |
| Agentforce SDK | To build an agent from scratch using Python code via a programmatic interface to Salesforce’s Agentforce infrastructure | Pro-code |
| Model Builder | Customise a generative AI model or create a predictive model | Low-code |
Let’s take a closer look at Agentforce Script, the blueprint for an agent’s reasoning process.
Agentforce Script is our Agentforce-specific scripting language that serves as the text-based foundation for building and governing agents. It functions as a unified language that expresses the entire behaviour of an agent. This single file brings together configuration, business logic, actions, and reasoning instructions. Rather than treating natural language and code as separate elements, practitioners use this blueprint to manage the entire agent architecture in one place.
Agentforce Script saves your agent details in a flat, readable text file for easier review and governance.
In agentic actions that use only generative AI , users rely on lengthy natural language prompts, which can lead to inconsistent and unpredictable task outcomes. Agentforce Script changes this. Hybrid reasoning with Script blends natural language with deterministic, rule-based instructions.
Leaders see immediate results with this level of control. Scott Van Dusen, Partner & COO at Equitable Trust, notes that Agentforce Script is incredibly powerful. He finds the ability to manipulate flows and actions much more robust than LLM-only methods. “I’m having a lot more success controlling it,” says Van Dusen.
Grant Roberson, the Agentforce admin at Datasite said Script is “light years better” than prompt-engineered agents.
“I used to have paragraphs of repetitive instructions everywhere to try and force behaviour, ” Roberson said. “With Script, it’s easy to remove that noise and replace it with conditional logic that lets you trust your agents to do exactly as you want them to.”
Script moves you away from prompt crafting towards scalable orchestration. Because it uses a structured, text-based format, your team can version, review, and govern agent behaviour just like traditional code.
Agentforce Script organises agent capabilities through declarative syntax. It treats instructions, actions, and subagents as modular components. This structure gives the Reasoning Engine a clear map of resources while setting boundaries to keep the agent within its intended scope. These scripts move workflows from probabilistic reasoning to guaranteed results by reducing LLM calls and preventing logic errors.
The following is a list of structural best practices organised by modular design principles to help you build a maintainable and predictable agent.
The following is a list of data management techniques organised by session handling to help you reduce latency and improve personalisation.
The following is a list of configuration standards organised by execution logic to help you maintain strict compliance and reliability.
The following is a list of implementation guidelines organised by tool selection to help you choose the right automation path for your use case.
Agentforce Script for handling messy or unpredictable human input.
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 via agent actions. Using a prompt template on its own is ideal when:
Prompt template use cases:
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:
AI agent use cases:
Knowing how the Reasoning Engine operates behind the scenes is key to successful agent implementation. In earlier days of AI agents, we practitioners talked a lot about prompt engineering: the art of ‘coaxing’ an LLM to behave. Now, we’ve graduated to context engineering.
Context engineering is a more holistic practice, going well beyond just writing a good prompt. With Agentforce hybrid reasoning, you design a system that balances autonomous LLM reasoning with rules-based logic for deterministic control.
Context engineering is the successor to prompt engineering . It involves designing a system of subagents, instructions, rules, and actions to provide an agent with the exact information and boundaries it needs to be successful, rather than trying to craft the perfect words in an attempt to coax an LLM to give you exactly the right responses.
The Three Levers of Context Engineering
Practitioners use Agentforce Script as the unified language to express subagents, instructions, actions, and rules in a single language and file.
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 specialised 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 uses that subagent’s tailored guidelines and tools to help the customer.
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.
| Component | When to Use | Skills Required | Additional Licence Required? |
|---|---|---|---|
| Prompt Template | To invoke an LLM to generate a response. Prompt template actions are one way an agent uses RAG. | Low-code | Yes |
| Flow | To run low-code rules-based automation and record retrieval | Low-code | No |
| Apex code | To run pro-code rules-based automation and record retrieval | Pro-code | No |
| MuleSoft API | To retrieve data from legacy systems and other external applications in a complex enterprise environment | Pro-code | Yes |
| External Service | To retrieve data from REST APIs that support OpenAPI specs | Low-code | Yes |
| Predictive Model | To use predictive AI with your agent | Low-code | Yes |
The Reasoning Engine uses subagents, instructions, actions, and rules to get work done. Since Agentforce Script serves as the full definition of the agent, it eliminates the black box of probabilistic routing. In short, the Reasoning Engine will:
Here’s a step-by-step breakdown of what happens inside the Reasoning Engine whenever an agent is invoked.
Note: This Reasoning Engine Flow diagram uses the term “topics” for what we now call subagents. We’ll update the diagram soon.
| Activity | Steps | Description |
|---|---|---|
| Agent Invocation | 1 | Agent is invoked. |
| Classify Subagent | 2-3 | The engine analyses the customer’s message and matches it to the most appropriate subagent based on the subagent name and description. Agentforce Script transforms the Agent Router into a fully configurable element, eliminating the “black box” of probabilistic LLM routing. By treating navigation as a programmable subagent, you gain absolute transparency and control, allowing you to align the agent’s decision-making logic precisely with your specific business requirements and architectural standards. |
| Execute Subagent’s Agentforce Script and Build Instructions / Resolve Instructions & Available Actions | 4-5 | Execute scripted actions as dictated by instructions. These are actions that should be executed once a subagent is chosen, before the system proceeds to evaluate the non-deterministic instructions or the rest of the conversational context. |
Prompt and Conversation History Sent to LLM | 6 | Once all scripted actions are executed, a prompt with the subagent scope, instructions, and available actions along with the conversation history are sent to LLM. Note: Instructions are covered in level 2, Agentic Control. |
| LLM Decides to Respond or Run an Action | 7 | Using all this information, the engine determines whether to: • Run an action to retrieve or update information • Ask the customer for more details • Respond directly with an answer If the LLM decides to respond, step 12 is executed. |
| Action Execution | 8-9 | If an action is needed, the engine runs it and collects the results. |
| Run After-Action Logic | 10 | Only applicable with Agentforce Script: With Agentforce Script, actions can have deterministic transitions to other actions or subagent. Those will always be executed after the action is executed. |
| Action Output Returned + Action Loop | 11 | The engine evaluates the new information and decides again what to do next — whether to run another action, ask for more information, or respond. |
| Grounding Check - LLM Responds to Client | 12 | Before sending a final response, the engine checks that the response: • Is based on accurate information from actions or instructions • Follows the guidelines provided in the subagent’s instructions • Stays within the boundaries set by the subagent’s scope Note: It’s possible with Agentforce Script to add a step to format the final answer. The grounded response is sent to the customer. |
For an even deeper dive, see Agentforce Guide to Achieving Reliable Agent Behaviour: A Framework for 6 Levels of Determinism
Reliable agents require thoughtful design. Practitioners shape them through a combination of filters, scripted logic, and citations that together control what the agent sees, what it does, and how it accounts for its answers.
Practitioners must understand the distinction between filtering and instructions to build accurate agents. Filters control what the LLM sees and what it can do on each turn of a conversation, and they work at multiple levels. Filters can be applied to subagents, actions, and retrievers, giving practitioners fine-grained control over which subagents are available, what those subagents can do, and what content the model retrieves at each step.
Think of a bank’s virtual assistant. When a customer asks about their mortgage, a subagent scoped to home lending kicks in. Its filter ensures the LLM only sees mortgage documents, not credit card data or investment records. But within that same conversation, the action that pulls the customer’s current rate uses its own tighter filter, restricted to that customer’s account. The customer gets a precise answer, and irrelevant data never enters the picture.
Filters can be set as static (preconfigured at setup) or dynamic (passed at runtime from conversation context or prompt inputs). With Enhanced Retriever Pre-Filters, practitioners can now apply up to 10 dynamic filters per retriever, combine them with AND/OR logic, and use LIKE operators for pattern matching. This reduces retrieval noise and keeps the context window focussed on the most relevant content. In software development workflows, for example, practitioners can apply action-specific context filters to give an agent flexibility in interpreting user prompts while keeping it strict about the current state of the codebase.
Agentforce Script provides the highest level of deterministic control by encoding specific sequences and rules for the agent to follow. This approach prevents the prompt doom loop, where instructions become too long or confusing for the LLM to follow accurately.
While filters and Agentforce Script provide system-level control, practitioners must also provide a way to verify accuracy. Citations give users a clear audit trail for every response, connecting the internal context the agent used to the answer it surfaced.
Successful context engineering requires the seamless integration of subagents, instructions, script, and actions. These four elements work together to keep an agent within the boundaries of optimal relevance and accuracy. Subagents define specialised expertise. Instructions provide conversational guidance and tone. Agentforce Script adds a layer of deterministic control to enforce business rules. Actions allow the agent to execute actions and access real-time data. This combined strategy ensures your agent remains both helpful and highly reliable.
| Bad Example | Good Example | Why It's Better |
|---|---|---|
| Handle order questions and issues. | Your job is to answer questions related to order status or repair policies. | This description helps the Reasoning Engine identify the correct expert for classification. |
| Help with login problems. | Your job is to help customers who cannot log in by resetting passwords or looking up usernames. | This explicitly defines the activities for the classification engine. |
| Component | Contents |
|---|---|
| Subagent Name | Password Reset |
| Description | This explicitly defines the activities for the classification engine. |
| Agentforce Script (Control) | Require identity verification before any reset action runs. Check if the user has a valid session. Use script logic to provide a fallback to security questions if primary verification methods are unavailable. |
| Instructions (Behaviour) | Ask which verification method the customer prefers. Use a professional tone. Explain that a secure reset link will arrive via email after verification succeeds |
Instructions guide the agent on how to handle conversations within a subagent. They help the agent make decisions about action selection and response patterns. Because instructions are non-deterministic, they do not replace the need for coded business rules within Agentforce Script or an action.
| Bad Example | Good Example | Why It's Better |
|---|---|---|
| Get the customer's order details. | If a customer enquires about their order status, offer all lookup options including email address or order ID. | Provides specific guidance and uses language similar to the action name. |
| Help with device issues | Before using the Knowledge action, clarify the device type (iOS or Android). | Gives clear instruction on what information to gather first. |
| Use knowledge for product questions. | Identify the specific product first. Then use the Knowledge action with the exact product name. | Provides a clear sequence of steps for the action. |
| Check if customers need help. | After providing the shipping status, always ask if the customer needs anything else related to their order. | Specific about when and how to follow up. |
Successful context engineering requires knowing where to place your logic.
Best practices for writing effective instructions
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, utilising 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.
| Agentforce Feature Powered by Data 360 | Description | Provisioning |
|---|---|---|
| Data Library Automation | Automates creation of search indices and retrievers to support agent actions like Answer Questions with Knowledge | Provisioned by Default |
| Agent Analytics | Streams usage data to Data 360 for Reports and Dashboards | Provisioned by Default |
| Retrieval Augmented Generation (RAG) | Enables users to augment their prompts with data from Salesforce and Data 360, retrieved at inference time | Provisioned by Default |
| Audit Trail & Feedback Logging | Generative AI audit data | Optional |
| Bring Your Own Large Language Model (BYO-LLM) | Allows users to use their own LLM | Optional |
| External Data Sources (non-CRM) | Enables users to ground AI-generated responses with external sources | Optional |
| Unstructured Data | Enables users to ground AI-generated responses in unstructured data | Optional |
| Real Time Data Graphs | Enables near real-time grounding of AI-generated responses using normalised data from multiple Data 360 sources | Optional |
We’ve covered the key elements that make Agentforce work, including the Reasoning Engine, and how to use Script, 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
Agentforce is Salesforce’s platform for building agents that go beyond simple chat interactions. Unlike standard generative AI tools, these agents can autonomously plan, reason, and take action to achieve specific goals, with or without a human in the loop.
Agentforce has evolved from basic AI interactions into a comprehensive development lifecycle within Agentforce Studio, introducing the Agentforce Builder and Agent Script for enhanced deterministic control. This shift includes rebranding "Topics" as "Subagents." Ultimately, the platform has transitioned from a prompt-centric approach to a hybrid-reasoning model, prioritising reliable logic over probabilistic natural language prompts.
Yes! See https://www.salesforce.com/agentforce/legacy-guide/
While these guides provide technical detail about how Agentforce works, they’re not official implementation guides with click paths and troubleshooting tips. Find official Agentforce Implementation Guides on Salesforce Help.
Find official Agentforce Implementation Guides on Salesforce Help.
While this guide provides technical detail about how Agentforce works, but it’s not an official implementation guide with click paths and troubleshooting tips.
Hybrid reasoning is Agentforce’s approach to agent orchestration that combines deterministic, rule-based logic with LLM-driven intelligence — letting builders dial up or dial down AI autonomy depending on how much reliability vs. flexibility a given task requires.
The guide covers Agentforce Fundamentals, the difference between Prompts and Agents, How Agentforce Reasons, Best Practices for various components, and whether Agentforce needs Data 360.
Agentforce Script provides full deterministic control by replacing long, convoluted system prompts with structured logic. It allows practitioners to define specific code-like steps and "if-then" sequences that must occur before or after LLM reasoning, guaranteeing predictable outcomes.
Use Agentforce Script for ‘control,’ such as enforcing mandatory sequences, complex calculations, or sensitive business rules. Use instructions for ‘behaviour,’ which includes guiding the agent’s tone, persona, and general conversation patterns.
Context engineering is the successor to prompt engineering. It involves designing a system of subagents, instructions, rules, and actions to provide an agent with the exact information and boundaries it needs to be successful, rather than trying to craft the perfect words in an attempt to coax an LLM to give you exactly the right responses.
Filters act as system-level gatekeepers. They can completely hide or include specific subagents or actions based on real-time data, such as whether a customer has been authenticated or if a specific variable (like an order number) has been collected.
Data 360 is integral building effective enterprise agents, powering the indexing and ‘chunking’ of data for Retrieval Augmented Generation (RAG). It also provisions essential features like Agent Analytics and the Digital Wallet used to track agent performance and usage.
Take a closer look at how agent building works in our library.
Launch Agentforce with speed, confidence, and ROI you can measure.
Tell us about your business needs and we’ll help you to find answers.
