Skip to content

Use the Address Actions in an Agentforce Agent

Overview

An Agentforce agent can capture 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 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: Prepare the Agent User

An agent calls its actions as its own user rather than as the person talking to it, so that user needs an Einstein Agent license, the Agentforce access Salesforce requires, and access to the two Apex classes behind the AddressTools actions. Testing an action as yourself proves nothing about whether the agent can call it.

  1. Navigate to Setup > Users and click New User.
  2. Set User License to Einstein Agent. Profile is then set to Einstein Agent User automatically.
  3. Complete the remaining required fields and save the user.
  4. Assign two Permission Sets to that user: AddressTools Premium Agent User and Agentforce Service Agent User.

AddressTools Premium Agent User grants Apex class access to the two classes behind the actions and nothing else, so it can be assigned to a user on the Einstein Agent license. See Grant Access to the Actions.

If Agentforce refuses to assign the agent user

The message "We couldn't assign the agent user. Check to see if you reached the user limit for your org or select a different existing user and try again." usually has nothing to do with a user limit. It appears when the user is missing an Einstein Agent license or the Agentforce Permission Sets above. Check those before looking at your license counts.

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 capture.
  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 rules about not changing address data: the agent must only ever show what the actions returned.

Ask the user for the building number or building name and their ZIP/Postal Code. Accept any local term, such as ZIP code, postcode, Eircode 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 address one element per line in this order, omitting any that are empty: Organisation name, Formatted street, Post town, Administrative area, State, Postcode, Country name. Show every element exactly as returned, keeping multiple street lines as they are. Use no labels, bullets or trailing punctuation. Then ask the user to confirm it is correct.
When either action returns Success as false, explain what Message says in plain language, quote the trace ID at the end of Message when it has one so the user can give it to support, and offer to search again. Never present an address the service did not return.

A welcome message that asks for the two details the agent needs shortens the conversation, for example: Hello. I can help you find and confirm your postal address. To begin, please give me your building number or building name, together with your ZIP/Postal Code.

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 with one element per line. 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 tell the agent to explain the message, quote the trace ID when the message ends with one, and offer to search again. The message reporting that too many addresses were searched or resolved in one transaction has no trace ID. See Trace IDs.
  • 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 Actions.