Agent Builder
Agent Builder is Salesforce's no-code design tool for creating, configuring, and testing Agentforce AI agents.
Definition
Agent Builder is Salesforce's no-code design tool for creating, configuring, and testing Agentforce AI agents. It is the Setup-based UI inside Agent Studio where admins define an agent's purpose, build its topics, wire up its actions, configure grounding, and validate behavior through a built-in conversation playground. Agent Builder is to Agentforce what Flow Builder is to Flow: the primary author-time surface.
The tool exposes the entire agent definition through a visual interface. Topics appear as cards with their descriptions and action lists. Actions show their parameters, return values, and behavior descriptions. The Conversation Playground lets you type realistic user inputs, see which topic the reasoning engine selects, watch which actions fire, and read the generated response. This iterative loop (edit, test, refine descriptions) is the daily workflow of agent design. Agent Builder is the only way to design Agentforce agents without writing direct metadata; while metadata-API workflows exist for advanced use cases, most agents are built end-to-end in Agent Builder.
How Agent Builder lets admins design AI agents declaratively
Where Agent Builder fits in Agent Studio
Agent Studio is the umbrella product that contains Agent Builder (design), the Conversation Playground (test), and Usage Analytics (monitor). Agent Builder is where the agent definition lives: name, description, instructions, topics, actions, grounding sources, channels. Each agent is one definition that the platform deploys to one or more channels (Slack, Mobile, Experience Cloud, embedded chat). The metadata representation is Bot in older terminology and AgentDefinition in newer.
Topic design as the core author-time work
Each topic in Agent Builder has three configurable parts: a name and description, instructions for behavior, and a list of actions. Topic descriptions matter most because the reasoning engine reads them to decide which topic handles a given user input. Write descriptions that are specific about scope and behavior. Instructions guide the agent on tone, response style, and constraints. Most admins iterate on topic descriptions repeatedly during testing, refining wording until routing matches expectation.
Wiring actions: Apex, Flow, Prompt Templates, API, Sub-agents
From Agent Builder, you add actions to topics. The action picker lists available Apex methods (those marked @InvocableMethod), Flows (autolaunched), Prompt Templates (from Prompt Builder), API calls (via Named Credentials), and other agents (for composition). Each action has input parameters mapped from the conversation context, output values used in the response or chained into the next action, and a description that guides when the engine picks it. Action description quality determines whether the agent picks the right action consistently.
The Conversation Playground for iterative testing
Agent Builder includes a playground for testing agent conversations without leaving the design tool. Type a realistic user input, watch the reasoning engine pick a topic, see which actions fire with what parameters, and read the generated response. The playground shows the chain of LLM calls and the data fetched for grounding, which is critical for debugging why an agent picked the wrong topic or hallucinated an answer. Most agent design time is spent in the playground iterating on descriptions and grounding rules.
Grounding configuration in Agent Builder
Grounding rules tell the agent which data to fetch before responding. Configure grounding per agent or per topic: query Account records related to the current Contact, pull Knowledge articles matching the user input, fetch Data Cloud unified profiles. Each grounding source can be conditional on the conversation context. Strong grounding configuration is what makes agents stop hallucinating; the playground reveals when an agent is using its own training data instead of your records.
Channel deployment and embedding
Agent Builder exposes channel configuration alongside the agent definition. Slack channel deployment connects to Slack workspaces. Experience Cloud embedding produces a chat widget for community sites. Salesforce Mobile and desktop expose the agent through the Einstein Copilot panel. API endpoints support headless integration. The agent definition is shared across channels; channel-specific UX adaptations happen at the channel layer.
Version control and deployment
Agent definitions are metadata. They deploy through change sets, metadata API, and SFDX-based pipelines like other Salesforce metadata. Each agent has versions, with the active version being what users interact with. Test the new version in a sandbox playground, activate when ready, keep the prior version available for rollback. Mature Agentforce teams version-control agent definitions in source control alongside Apex, Flows, and other components.
How to build an agent in Agent Builder
Building an agent in Agent Builder is iterative. Define the purpose, sketch topics, wire actions, configure grounding, test in the playground, refine descriptions. Most of the value comes from the iteration loop, not the initial build. Plan multiple rounds of testing before considering the agent ready for users.
- Define the agent purpose and scope
Write a clear description of what the agent does and what is out of scope. The scope discipline matters; agents that try to do everything end up doing nothing well.
- Open Agent Builder and create a new agent
Setup > Agent Studio > New Agent. Provide name, description, instructions. Choose the agent type that matches the use case (Service Agent for customer support, Sales Agent for sales workflows, Custom Agent for bespoke purposes).
- Map and create topics
For each major job, create a topic. Write a description that explains exactly when this topic applies. Write instructions that guide the agent''s behavior within the topic. The descriptions are the routing signal for the reasoning engine.
- Add actions to each topic
Click into each topic, click Add Action, pick from Apex methods, Flows, Prompt Templates, API calls, or sub-agents. Configure input parameters and write a description that explains when to invoke the action.
- Configure grounding sources
For topics that need real data to answer accurately, configure grounding rules. Pull from the current record, related records, Knowledge, Data Cloud, or custom queries. Strong grounding stops hallucination.
- Test in the Conversation Playground
Type realistic user inputs covering the main use cases plus edge cases. Watch which topic gets picked, which actions fire, and whether responses are accurate. Iterate on descriptions until routing matches expectation.
- Configure channels and deploy
Add channel deployments: Slack, Experience Cloud, Salesforce Mobile, embedded chat. Each channel has its own configuration. Activate the agent for the chosen channels.
- Monitor and iterate post-launch
Setup > Agent Studio > Usage shows conversation logs and quality signals. Review failed or low-quality conversations and refine the agent definition. Plan ongoing tuning; agents are not "deploy and forget."
Service Agent, Sales Agent, or Custom Agent. Determines starting templates and recommended actions.
Categorical mental model of agent jobs. Topic descriptions drive routing decisions.
Where the agent surfaces: Slack, Experience Cloud, Mobile, embedded chat, API. One agent definition can deploy to many channels.
- Topic and action descriptions drive routing accuracy. Vague descriptions produce inconsistent behavior; specific descriptions produce reliable agents. Plan iteration time accordingly.
- Conversation Playground is essential during design. Skipping iterative testing produces agents that misbehave on real user input. Build the playground into the daily design workflow.
- Grounding is what stops hallucination. Ungrounded agents confidently state facts that are not in your data. Configure grounding for every topic that needs accurate, data-specific answers.
- Action descriptions must be specific. The reasoning engine picks actions based on descriptions; ambiguous descriptions cause the engine to invoke the wrong action or no action.
- Agentforce evolves rapidly. Features available today may be renamed or extended in the next release. Stay current with release notes and Trailhead updates.
Trust & references
Cross-checked against the following references.
- Agent Studio DocumentationSalesforce Help
- Agentforce OverviewSalesforce Help
Straight from the source - Salesforce's reference material on Agent Builder.
- Agent StudioSalesforce Help
- Agent TopicsSalesforce Help
- Agent ActionsSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is Agent Builder primarily used for?
Q2. Which engine powers the reasoning behind Agentforce agents built in Agent Builder?
Q3. Which of these is NOT a building block you configure in Agent Builder?
Discussion
Loading discussion…