Skip to content

Use the Address Actions in an Agentforce Agent

Overview

An Agentforce agent can collect a postal address in conversation using the AddressTools Search Address and Select Address actions. The agent asks the user for part of their address, searches for matching candidates, narrows the results where required, and then resolves the chosen candidate into a full verified address, which it confirms with the user.

Neither action writes to a record. The verified address is returned to the agent, so to store it, add a further action of your own that takes the outputs of Select Address.

This page covers the Agentforce configuration and the instructions the agent needs. For how the two actions work together, their inputs and outputs, and their use in Flow Builder, see Search and Select Address Verification Actions.

Before You Start

  • AddressTools must be installed and connected with an authentication token. See Create an Authentication Token.
  • The Country and State reference data must be installed. These are the two objects selected by default, and the actions need no others. See Install Country Data.
  • Agentforce must be enabled in your org, and you need access to Agentforce Studio.

Step 1: Give the Agent User Access

An agent calls its actions as its own agent user rather than as the person talking to it. Set up the agent user by following the Salesforce Agentforce documentation, then assign it the AddressTools Premium Agent User Permission Set, which grants access to the two Apex classes behind the actions. See Grant Access to the Actions.

Note

Testing an action as yourself does not confirm that the agent can call it. Test through the agent, as described in Step 5.

Step 2: Create the Agent Actions

The AddressTools actions are Apex invocable methods. Before an agent can use them, create an agent action for each one in the Agentforce Asset Library.

The Asset Library starts empty for AddressTools

AddressTools does not ship ready-made agent actions, so searching the library for "Address" before this step returns nothing. The two actions appear only once you have created them here.

  1. Navigate to Setup > Agentforce Assets. The page heading is Agentforce Asset Library.
  2. Open the Actions tab and click New Agent Action.

  3. In the Create an Agent Action dialog, complete the Connect an existing action step:

    Field Value
    Reference Action Type Apex
    Reference Action Category Invocable Method
    Reference Action Search Address

    Agent Action Label and Agent Action API Name are filled in for you as Search Address and Search_Address.

  4. Click Next to reach Configure your action for Agent. The input and output descriptions are filled in from the AddressTools action definition. Leave them unchanged.

  5. Enter Loading Text, which is required and starts blank, for example Searching for addresses....
  6. Click Finish.
  7. Repeat steps 2 to 6 for the second action, selecting Select Address as the Reference Action and giving it its own Loading Text, for example Retrieving the address....

Both actions then appear on the Actions tab with Source set to Custom and Reference Action Type set to Apex.

Step 3: Add the Actions to Your Agent

  1. Navigate to Setup > Agentforce Agents and click New Agent, or open an existing agent. New agents open in Agentforce Builder.
  2. Open the subagent that will collect addresses, or add one for address entry.
  3. Under Actions Available For Reasoning, click Add action, then Add from Asset Library.
  4. In the Actions dialog, click Select on Search Address, then on Select Address, and click Add to Agent.

Step 4: Add the Instructions

The instructions tell the agent when to search, how to narrow the results, how to present candidates and how to display the final address. Paste the following text into the instructions of the subagent that owns the two actions. Adjust the wording to your organisation's tone, but keep the rule that the agent never alters an address returned by the actions.

Ask the user for the building number or building name and their ZIP/Postal Code. Accept any local term, such as ZIP code, postcode or PIN code.
If the user gives a building number or name without a ZIP/Postal Code, ask for it once and tell them that if they do not know it they can say so and you will still search. Never ask for it twice, and never ask for the street or city when a ZIP/Postal Code has already been given.
Call Search Address as soon as you have a building number or name plus one other detail and have either received the ZIP/Postal Code or asked for it once. Combine what the user gave you into a single search string, for example "10 SW1A 2AA", "1600 20500" or "221B Baker Street London". Do not ask further questions before searching.
Leave Allowed country codes and Preferred country code blank so that the search covers all countries.

Search Address returns candidates, each with an Is Container value. When Is Container is true the candidate is a group of addresses rather than a single address. If exactly one candidate is returned and it is a container, call Search Address again with Container Id set to its Candidate Id and Search Text unchanged, and repeat while that is still the case. If exactly one candidate is returned and it is not a container, treat it as the user's choice and call Select Address without asking them to pick from a list.
Otherwise present every candidate as a numbered list showing its Candidate Text, followed by its Candidate Description when it has one, and ask the user to reply with the number. Never invent, merge, reword or reorder a candidate. If the user picks a container, call Search Address again with Container Id set to its Candidate Id and Search Text unchanged, and present the new candidates the same way. If no candidates are returned, say so plainly and offer to search again.

Once the user picks one, call Select Address with Address Id set to that candidate's Candidate Id and Search Context set to the same candidate's Search Context, passed through unchanged.
When Success is true, show the Formatted address label exactly as returned, keeping its line breaks, with no label, bullets or trailing punctuation. Then ask the user to confirm it is correct.
When either action returns Success as false, do not show Message or any technical detail to the user. Tell them the address could not be retrieved, offer to search again, and let the conversation continue if they would rather move on. Never present an address the service did not return.

Note

These instructions are an example of a self-contained address conversation. Extend them to suit your own process. For example, you may want the agent to accept an address typed by the user when the search cannot find one they are happy with, or to store the confirmed address on a record using an action of your own.

Restricting the search to particular countries

Replace the sentence about leaving the country inputs blank with the codes to use, for example Set Allowed country codes to "US,CA" on every search. The codes are two-letter ISO country codes.

Step 5: Test and Activate the Agent

  1. Save the agent.
  2. Open Preview and enter a building number and postal code, for example 10 SW1A 2AA.
  3. Check that the agent shows the verified address as a formatted address label. A search that matches a single address goes straight to it without asking you to choose.
  4. Enter a building number and postal code that match many addresses, for example 1 W1A 1AA, and check that the agent lists the candidates, asks you to reply with a number, and narrows a container rather than listing it as if it were an address.
  5. Commit the version and activate the agent.

Good to Know

  • Both actions report problems through Success and Message rather than stopping the conversation. The instructions above keep error details away from the user and let the conversation continue, which suits agents open to partners or the public.
  • The agent only ever shows what the actions returned. If the address the user expects is not among the candidates, the instructions have it say so and search again rather than compose an address.
  • The full list of inputs and outputs, including the address fields returned by Select Address, is in Search and Select Address Verification Actions.