Prototype the Agent
Learning Objectives
After completing this unit, you’ll be able to:
- Design a custom topic for your Agentforce use case.
- Plan the flows, Apex, and prompt templates for your agent actions.
- Explain some considerations for designing reference actions.
Trailcast
If you'd like to listen to an audio recording of this module, please use the player below. When you’re finished listening to this recording, remember to come back to each unit, check out the resources, and complete the associated assessments.
How to Prototype
Nora and her project team have been building their AI agent and experimenting in their sandbox environment while conducting planning activities for their Agentforce project. But how is Coral Cloud prototyping its AI agent in its Salesforce org? In this unit, we walk through the team’s approach so you can get hands-on and start iterating on your own solution.
First, let’s see how Nora approaches the design of the topic Coral Cloud created for its reservation management use case.
Set the Stage for the Conversation
Topics are an important component of Agentforce because the topic defines the AI agent’s goal and provides the context and direction it needs to achieve that goal.
When a user starts chatting with an AI agent, the brain of Agentforce—its reasoning engine—works with the large language model (LLM) behind the scenes to resolve any ambiguity in the conversation and establish the user’s intent. Then it evaluates all the topics available to the agent and picks the topic that aligns with the user’s goal. When you’re designing your topics, you have to make it as easy as possible for the reasoning engine to choose the right topic. If it doesn’t pick the right topic, then it won’t have access to the right actions, which means it won’t have the tools it needs to do its job.
Design the Topic
Agentforce has built-in tools to help you design your topic, but Nora can also choose from out-of-the-box topics and edit any existing topic. By reviewing the different parts of a topic, Nora can easily choose a label, classification description, scope, and instructions.
Label
The topic’s label should reflect its job to be done. For Coral Cloud’s use case, reservation management is identified as a job to be done. So the name of its new topic is Reservation Management. When an agent has multiple topics, make sure the names aren’t too similar or the reasoning engine won’t be able to tell the topics apart.
Classification Description
The classification description is 1–3 sentences that describe what the topic does. An agent uses this description to determine when to use a topic in a conversation. The classification description should be semantically distinct from the agent’s other topics. And it’s most effective when it closely mirrors the types of inquiries expected to trigger the topic.
Here’s the first iteration of Coral Cloud’s classification description: “Answers questions and addresses requests related to a guest’s hotel reservation, confirmation, or travel itinerary.”
Scope
Once the agent selects the Reservation Management topic, the scope determines what the agent can and can’t do. It’s most effective when it narrowly defines the agent's job.
During the use case definition stage, Coral Cloud’s project team wisely starts with an MVP version of the AI agent that handles reservation management. Then they gradually expand the agent’s scope in the following two versions. As you can imagine, the boundaries for each version should be reflected in the topic’s scope in Agentforce Builder.
Here’s how the scope might be written for the MVP version of the topic.
“Your job is to only assist the user with their hotel reservation questions and communicate information to guests about existing reservations. You can also resend the reservation confirmation email or itinerary. Never make new reservations, modify reservations, or cancel reservations. Never handle inquiries unrelated to hotel reservations.”
When Coral Cloud expands the agent’s capabilities in the second version of the topic, the project team can update the topic’s scope to include modifying and creating reservations but exclude cancellations and refunds.
Instructions
Instructions help an agent make decisions about how to perform its job and how to use the actions assigned to the topic, and the instructions are written in natural language. An example of an instruction for Coral Cloud’s topic might be: “Always confirm the details of a reservation modification with the user before finalizing any changes.”
Keep in mind that topic instructions are nondeterministic—which means they can’t guarantee the same outcome 100% of the time. That’s just the nature of generative AI. So Nora and her team make sure to build important or sensitive business rules, requirements, and guardrails into the functionality of the agent’s actions, not the topic instructions. For example, instead of adding the instruction “Don’t refund a booking unless it was canceled within 2 days of the check-in date,” Coral Cloud creates an agent action that assesses the criteria for issuing a refund.
As you prototype your agent, we suggest crafting the topic instructions last. You can’t write effective instructions without knowing how much logic you built into the actions versus how much decision-making you’re asking the agent to complete on its own. After the Coral Cloud team creates topics and actions, they can test the AI agent. Then they can add and refine the topic instructions by following the best practices in Salesforce Help and the Salesforce Developer Blog.
Time for Action
In the previous unit, Coral Cloud defined its business processes related to hotel reservations. And many of those business processes translated into custom actions for its Reservation Management topic.
The good news about custom actions is that you don’t have to create them out of thin air. In fact, custom actions are based on Salesforce technologies you already know and love. When you create a custom action, you build it on top of existing platform functionality that you want to make available in Agentforce—invocable Apex classes, autolaunched flows, and prompt templates. In Agentforce, we refer to that underlying functionality as a reference action, and it’s an awesome way to get more mileage out of your Salesforce Platform capabilities.
Design Considerations for Reference Actions
So what is Coral Cloud’s approach to the design of the underlying reference actions (Apex, flows, and prompt templates) for its agent actions? Below are some factors the team considers.
Deterministic or Prompt-Based
When developing the underlying platform functionality for your agent actions, first review the business processes and tasks related to your use case. Then decide whether the process or task should be deterministic or prompt-based.
-
Deterministic: Uses an invocable Apex class or autolaunched flow to generate output. Actions based on flows or Apex are deterministic and use business logic and rules to produce a consistent outcome.
-
Prompt-based: Uses one or more prompt templates to generate output. A prompt-based action lets you control how a response is written or use reasoning and generative capabilities of an LLM. For example, to generate a summary or perform sentiment analysis, you need to use a prompt template as a reference action. Prompt templates are also used to ground an agent in data, such as knowledge or external system data.
Keep in mind that an action can combine both deterministic and prompt-based approaches. For example, say that when a guest cancels their reservation, a flow-based action is triggered to complete the cancellation. At some point during that flow, the agent could also follow a prompt to ask the customer for information about why they’re cancelling. The agent could even summarize the response from the customer and provide that summary for review if the customer indicates a particular reason for cancelling. Over time, Coral Cloud can use this combined approach to better understand—and respond to—the issues that impact customers. It could call a prompt template that sends a cancellation confirmation email with personalized offers to entice that particular customer to make a future booking.
Atomic or Composite
Another factor to consider is whether the reference action is atomic or composite.
-
Atomic: A small, singular task. A modular approach gives the agent freedom to combine actions in different ways to accomplish a more sophisticated goal. It also tends to provide more opportunities for action reuse across different topics.
-
Composite: A complex task made up of multiple subtasks. The benefit of a composite action is that you control the exact sequence of steps the agent takes to complete a task.
Inputs and Outputs
In Agentforce, each agent action must have at least one input, which means the underlying flow, Apex, or prompt template must also have at least one input. For example, to look up a hotel reservation, the input might be the guest’s email or reservation number. During a conversation, the AI agent has the autonomy to gather information and decide if it has all the details required for it to trigger the action and pass in the input.
Each action must also have at least one output. The way you build the action determines what the output is, how it’s used, and whether and how it’s displayed to users in the conversation. Don’t be afraid to experiment with test actions that aren’t fully implemented, either—they can be a great way to see how your ideas work in execution.
Coral Cloud’s Reference Actions
After considering business processes and the different ways to design Apex, flows, and prompt templates, Coral Cloud’s project team proposed these reference actions for the Reservation Management topic.
-
Get Reservation by Email: A flow that looks up an existing reservation using the guest’s email address.
-
Get Reservation by Number: A flow that looks up an existing reservation using the reservation number.
-
Send Reservation Confirmation: An Apex class that sends the guest a confirmation email with their reservation details.
-
Create or Update Reservation: A flow that creates a new reservation if one doesn’t exist; if the reservation exists, it updates the record.
-
Cancel Reservation: A flow that cancels an existing reservation. The flow calls a prompt template that sends a cancellation confirmation email with personalized offers to promote future bookings.
-
Initiate Refund: A flow that processes a refund for a reservation cancellation if certain conditions are met.
From Reference Actions to Agent Actions
Creating all the necessary flows, Apex, or prompt templates for your use case can take some time, but turning them into custom agent actions is a breeze!
When you create a custom action, the action label and API name are populated with the existing reference action’s name and API name. The instructions for the custom action and each input and output are also populated with the descriptions from the reference action.
The action instructions tell the AI agent what a specific action does and when to trigger it. Well-written instructions ensure that actions are used consistently and accurately. To learn more about optimizing action instructions, check out the best practices for action instructions.
Coral Cloud now has a set of actions for their use case, so the project team assigns them to a topic. Now they’re ready to test the prototype and refine its building blocks.
Evaluate the Performance
After you configure a prototype in Agentforce, it’s important to test and see how the AI agent performs. You have two options for testing your AI agent.
- Manual testing in Agentforce Builder
- Batch testing in Testing Center
The Coral Cloud team tests their AI agent with questions and requests their users might make about hotel reservations. Then they answer these questions.
- Does the agent accurately interpret user input?
- Does it launch the right actions?
- Does it provide helpful, accurate responses?
- Does it execute business processes correctly and adhere to company policies and rules?
Based on the test results, the Coral Cloud team refines their topic instructions and continues iterating on the AI agent. And remember: If you’re getting errors during the testing process, be sure to check the permissions for your AI agent.
The Finishing Touches
There are a few other items that the Coral Cloud team needs to cross off their to-do list as they refine their prototype.
- Customize the standard escalation topic so that it can route conversations to live service reps when necessary.
- Build an authentication solution to verify users interacting with the AI agent.
-
Connect the AI agent to customer channels.
And when Nora and her team reach the point where the AI agent is performing reliably and accurately in Coral Cloud’s sandbox environment, they create their deployment plan for rolling out the AI agent to production. Then they monitor the agent, which helps them continuously improve and iterate on the agent’s design.
A Strong Foundation
Now you know that planning and designing an AI agent is all about laying down a strong foundation. You need to identify your use case and objectives, think about your data strategy, consider the user experience, and outline your project’s technical requirements. Address potential risks and define your business processes to make sure the AI agent aligns with your organization’s operational, security, legal, ethical, regulatory requirements.
Don’t make the mistake of taking a waterfall approach to agent design. That is to say, you don’t have to develop and deploy with a linear, phased plan. As you consider your Agentforce solution from all the necessary angles, get hands-on and begin prototyping the AI agent in your sandbox environment. That way, you don’t invest too much time up front on a plan that might not work out in the end. By combining thorough planning with continuous experimentation, you can roll out a trustworthy AI agent that unlocks transformative value for your organization.