Exercise 5: Extend Agents with APIs

In this exercise, you’ll create a new topic that looks up Pronto orders by customer email address. Because orders live in a 3rd-party system (not Salesforce), you’ll connect Salesforce to the Orders API using External Services, then expose it to your agent through an Agent Action.

Step 1: Create the Order Lookup topic

Next, create a topic that acts as the entry point for order lookup workflows.

1. In Agentforce Builder, hover over Topics in the explorer, and click the + sign.

2. Select Create new topic.

3. Set the following values:

   Field	Value
   Name	Order Lookups
   Describe the job you want the topic to do	Looks up Pronto orders for a customer using their email address, then uses the order context to support tracking, reviews, and case creation.

4. Click on Create and Open.

5. Click Save.

6. Paste the basic topic instructions below (you can refine later):

   This topic is used to look up Pronto orders for a customer based on their email address.
   
   Orders are stored in a 3rd-party order database (not Salesforce). Use the Orders API action to retrieve:
   - Recent orders
   - Orders by date range
   - The status of a current order
   
   If a user wants to look up a recent order, track an order, leave a review, or create a new case, we must first look up the order.
   Ask for the customer’s email address if it is missing.

7. Click Save.

Step 2: Add Order Lookups to Topic Selector (routing)

Next, make sure the agent can route into your new topic.

1. In the explorer, open Topic Selector.

2. Open the Authoring Agent (toggle the right panel).

3. Enter the following prompt:

   Add Order Lookup as a transition in the Topic Selector.

4. Review the suggested change and apply it.

5. Click Save.

Step 3: Create an External Service for the Orders API

Next, create an External Service from an API specification so Flows can call the Orders API.

1. Click the back arrow to leave Agentforce Builder.

2. Open the Setup Menu and click Setup.

3. In Quick Find, search for External Services and open it.

4. Click Add an External Service.

5. Select From API Specification, then click Next.

6. Enter the following values:

   Field	Value
   Name	ProntoOrders
   Description	Pronto Orders API
   Service Schema	Relative URL
   Named Credential	Pronto_Orders_API
   URL	/swagger.json

7. Click Save & Next.

8. In the Select Operations step, select the listOrders and listOrdersByEmail operators. These operators let you search for orders by email.

9. Click Next.

10. Click Finish.

Add the Named Principle to the Agent's Permission Set

1. In Quick Find, search for Permission Sets and open it.

2. Open the Agentforce Action Access Permission Set.

3. Open the External Credential Principal Access

4. Click Edit.

5. Select the Pronto_Orders_API_Key - ProntoPrinciple External Credential and Add it to the Enabled column.

6. Click Save.

Step 4: Create an API-backed Agent Action

Next, create an Agent Action that calls the Orders API via the ProntoOrders External Service.

1. In Agentforce Builder, open the Order Lookup topic.

2. Click on the arrow besides Select action, and select Create an action.

3. Enter Lookup Orders as action name and click Create and Open.

4. Enter the following information:

   Field	Value
   Description	Retrieves a customer’s orders from Pronto’s external Orders system using their email address.
   Reference Action Type	API
   Reference Action Category	External Services
   Reference Action	List Orders
   Inputs - Contact Email	Select checkbox Require Input to execute action
   Outputs - 200	Select checkbox Show in conversation

   TIP

   The 200 output is the default successful response from the API and typically contains an array of orders.

5. Click Save.

Update the Lookup Orders Action Agent Script

1. In the Lookup Orders Action, Switch the current view from Canvas to Script.

2. Find the Lookup_Orders action.

3. Find the 200 output and make the following changes:

   1. Update the label 200 to "200"
   2. update the complex_data_type_name to @apexClassType/ExternalService__c__ProntoOrders_Order?isAuraEnabled=true

4. Click Save.

Step 5: Configure the Order Lookup topic

Next, add both actions to the topic canvas and update the instructions so the agent only runs them after the customer is verified.

1. In Agentforce Builder, open the Order Lookup topic.

2. In the topic, you can reference an existing action by adding a new line after an action bubble. Add a new line under the existing actions and on arrow besides Select action, and select Get Customer Profile.

3. Expand the Get Customer Profile action and configure it:

   • Set the input for the verifiedCustomerId by mapping the verifiedCustomerId variable to the verifiedCustomerId input

4. In the Instructions block, type / to open the resource picker.

5. Select Conditional Statement.

6. Select the IsVerifiedCustomer variable.

7. Leave the default == operator and set the value to True.

8. In the True branch, add instructions that tell the agent how to calculate inputs and run the actions:

   Run Get Customer Profile first and set the email for Lookup Orders using the email returned from Get Customer Profile.
   
   If the customer inquires about a current order, set the order date to today's date.
   If the customer specifies "last x days," adjust the date range to go back by the specified number of days.
   If the customer specifies "last x orders," retrieve the last x orders.

9. Click the Add button next to the conditional logic and select Else.

10. Under the Else block, add a transition to Verify Customers.

11. Click Save.

Step 6: Test the agent

1. Click Preview.

2. Enter the following prompt:

   Can you show me my last 3 orders?

3. Press Enter on your keyboard.

4. If the agent asks for an email address, enter alex.morgan@example.com and press Enter.

5. After verification completes, confirm the agent runs Get Customer Profile and then Lookup Orders to query the Orders API.

6. In the Interaction Details area, click on Action: Lookup Orders and review the inputs and outputs.

Summary

You have connected Salesforce to a 3rd-party Orders API using External Services and extended your agent with API and Apex actions that retrieve customer context and look up orders using verified customer identity.