Get Started with the Agent API (Pilot)

Bring the power of generative AI to your business with Agentforce. Build intelligent, trusted, and customizable AI agents and empower your users to get more done with Salesforce. Use the Agent API to communicate with AI agents directly from a REST API. Start sessions, send messages to the AI agent, receive messages, and end sessions using the API.

To access the Agent API, you must set up a connected app that supports the client credential flow. These instructions show you how to get your environment set up for use with the API and demonstrate how to make your first call to the API.

API Flow

You must have Agentforce enabled with at least one agent activated. See Set Up Agents in Salesforce Help.

The Agent API isn’t supported for agents of type “Agentforce (Default)”.

To use the Agent API, you must create a Connected App that supports the client credential flow. You use this connected app to create a token. To learn more about Salesforce Connected Apps, see Create a Connected App in Salesforce Help along with these specific topics.

These instructions are for a sample connected app implementation that supports Agent API communication.

  1. Open your org and go to Setup.
  2. From Setup, use Quick Find to search for App Manager.
  3. From the App Manager page, click New Connected App, and then select Create a Connected App.
  4. For Connected App Name, specify an app name.
  5. For Contact Email, specify your admin email address.
  6. In the API section, check Enable OAuth Settings. This action displays additional OAuth-related settings.
  7. For Callback URL, specify https://login.salesforce.com.
  8. From Selected OAuth Scopes, add these scopes to the connected app.
    • Access chatbot services (chatbot_api)
    • Access the Salesforce API Platform (sfap_api)
    • Manage user data via APIs (api)
    • Perform requests at any time (refresh_token, offline_access)
  9. Deselect:
    • Require Proof Key for Code Exchange (PKCE) Extension for Support Authorization Flows
    • Require Secret for Web Server Flow
    • Require Secret for Refresh Token Flow
  10. Select:
    • Enable Client Credentials Flow
    • Issue JSON Web Token (JWT)-based access tokens for named users
  11. Review this screenshot to verify that you selected the correct settings. API Flow
  12. From the bottom of the page, save the app, and then click Continue.
  13. After saving the app, you see the Manage Connected Apps page. Click Manage. (To view this same screen later, select Manage Connected Apps from Setup.)
  14. Click Edit Policies.
  15. In the OAuth Policies section, from the Permitted Users dropdown, select the appropriate permitted users. See Manage OAuth Access Policies for a Connected App in Salesforce Help.
  16. In the Client Credentials Flow section, set Run As to a user that has at least API Only access.
  17. Select Issue JSON Web Token (JWT)-based access tokens. Leave the Token Timeout value as 30 minutes.
  18. Save the app.
  19. This step is only applicable if you selected "Admin approved users are pre-authorized" from the OAuth Policies section above. Scroll down the page to the Profiles section, click Manage Profiles, and select the profiles needed to access this connected app. See Manage Other Access Settings for a Connected App in Salesforce Help.

Before calling the API, add your connected app to your agent.

  1. From Setup, select Agents. Select your agent.
  2. Select the Connections tab, and click Add from the Connections section.
    API Flow
  3. Add a new API connection, choose your connected app, and then save.
    API Flow

To create a token, you need the consumer key and consumer secret from your connected app.

  1. From Setup, select App Manager.
  2. Find your connected app, click the dropdown arrow on the right, and then click View.
  3. Click Manage Consumer Details.
  4. Copy Consumer Key and Consumer Secret.

All calls to the Agent API require a token. Create a token by using the consumer key, consumer secret, and your domain name.

  • MY_DOMAIN_URL: You can get the domain from Setup. Search for My Domain. Copy the value shown in the Current My Domain URL field.
  • CONSUMER_KEY, CONSUMER_SECRET: You can get the consumer key and secret by following the instructions in Obtain Credentials.

The previous command returns a JSON payload similar to this response.

Copy the access token specified in the access_token property. This token is required when making requests to the API.

After you set up your connected app and created a token, you’re ready to call the API. Before making the call, gather this information.

  • AGENT_ID: The ID of the agent that you want to interact with. You can find this ID in the URL of the Agent Overview Page. When you select the agent from Setup, use the 18-character ID at the end of the URL. For example, when viewing this URL, https://mydomain.test1.my.pc-rnd.salesforce-setup.com/lightning/setup/EinsteinCopilot/0XxSB000000IPCr0AO/edit, the agent ID is 0XxSB000000IPCr0AO.
  • ACCESS_TOKEN: The token that you created in Create a Token.
  • RANDOM_UUID: A random UUID value that you provide to represent the session key. You can use this parameter to trace the conversation in your agent’s event logs.
  • MY_DOMAIN_URL: From Setup, search for My Domain. Copy the value shown in the Current My Domain URL field.

This curl command creates a new agent session with the Agent API.

When this call succeeds, you receive a response with a session ID and additional links.

Congratulations, you’ve successfully started using the Agent API! To continue using the API, see Agent API Examples and the Agent API Postman Collection.