3.4 When to Use the Agent API
Key Takeaways
- The Agent API is a REST API for starting agent sessions, sending messages synchronously or by streaming, submitting feedback, and ending sessions.
- Agent API access requires an external client app using a JWT-based token flow such as client credentials, with the api, refresh_token/offline_access, chatbot_api, and sfap_api scopes.
- The Agent API isn't supported for Agentforce (Default) agents, and calls time out after 120 seconds with an HTTP 500 response.
- Use the Agent API for custom web or mobile experiences, headless automation, external platforms, and invoking Agentforce agents from other agents.
- Agent API usage consumes credits, and custom variables must be marked External for the API to set them.
3.4 When to Use the Agent API
Quick Answer: Use the Agent API when something outside Salesforce's built-in channels needs to talk to an Agentforce agent over REST: your own website or mobile app UI, a headless automation with no chat window, a third-party platform or workflow, or another agent that invokes an Agentforce agent. If an out-of-the-box channel already meets the need (Enhanced Chat, messaging apps, email, voice, Slack, or the Agentforce panel), use that channel. It includes routing, escalation, and UI.
What the Agent API Does
Salesforce describes the Agent API as access to your autonomous agents from anywhere that can call a REST API. The documented use cases:
- Connect to an Agentforce agent from your website with your own chat UI.
- Create and deploy headless agents that automate work without UI constraints.
- Connect agents to your favorite platforms and workflows using standard endpoints.
- Build an agentic ecosystem by invoking Agentforce agents from other agents.
Session lifecycle
| Stage | What you do |
|---|---|
| Start a session | POST to the agent's sessions endpoint, https://api.salesforce.com/einstein/ai-agent/v1/agents/{AGENT_ID}/sessions, with a random UUID session key you can trace in event logs |
| Send messages | Use the synchronous endpoint for a complete response in one call, or the streaming endpoint to show chunks as they arrive in a real-time chat |
| Submit feedback | Optional endpoint to send feedback on a response |
| End the session | Close the session when finished. The agent keeps context only for the session's duration |
For Government Cloud orgs, replace api.salesforce.com with api.gov.salesforce.com.
Setting It Up
- Have an active agent. Agentforce must be enabled with at least one agent activated.
- Create an external client app (ECA) in Setup → External Client Apps Manager, and enable OAuth with these scopes:
- Manage user data via APIs (
api) - Perform requests at any time (
refresh_token,offline_access) - Access chatbot services (
chatbot_api) - Access the Salesforce API Platform (
sfap_api)
- Manage user data via APIs (
- Enable the Client Credentials Flow and Issue JWT-based access tokens for named users. Salesforce's example uses client credentials, but any flow that provides a JWT-based access token works.
- Set the Run As user for the client credentials flow to a user with at least API Only access.
- Mint a token with the consumer key, consumer secret, and your My Domain URL (for example
some_domain.my.salesforce.com, not the lightning.force.com domain). - Get the agent ID (the method depends on which builder created the agent) and start a session.
When you start a session, the bypassUser parameter controls identity. True uses the user assigned to the agent. False uses the user associated with the access token. In the client-credentials example it's set to true.
Considerations and Limits
| Consideration | Detail |
|---|---|
| Unsupported agent type | The Agent API isn't supported for Agentforce (Default) agents |
| Timeout | 120 seconds. A timed-out call returns HTTP 500 |
| Billing | Agent API usage consumes credits under Agentforce and generative AI usage billing |
| Variables | Only custom variables marked External can be set through the API |
| Security | The token's user or the agent's assigned user determines data access, so apply least privilege, the same as for any agent user |
| Channels and escalation | You build the UI and any handoff logic yourself. Omni-Channel escalation comes with Salesforce messaging channels |
Agent API vs. Other Integration Options
| Need | Best option | Why |
|---|---|---|
| A branded chat inside your React web app with your own components | Agent API | Full control of UI and session handling |
| A ready-made chat widget with escalation to reps, queue position, and pre-chat forms | Enhanced Chat | Salesforce-managed UI and Omni-Channel routing |
| A nightly job asks an agent to triage 500 support tickets without a UI | Agent API (headless) | Programmatic sessions and messages |
| A Salesforce flow needs an agent's reasoning inside a business process | Invoke the agent from Flow or Apex (Salesforce documents calling an agent from a Flow or Apex class) | Stays on-platform without an external token |
| An agent needs to call an external system's tools | MCP tool actions or API-based actions | The agent is the caller, not the callee |
| An external agent platform needs to delegate a task to an Agentforce agent | Agent API today; A2A where supported | Agent-to-agent communication |
| Two Agentforce agents in the same org should collaborate | Multi-Agent Orchestration (connected subagents) | Native handoff and supervisor modes |
Scenario Walkthrough
A travel company already has a mobile app with its own chat screen. It wants the Agentforce Service agent to answer booking questions inside that screen and pass the member's loyalty tier into the conversation.
- Create an ECA with the required scopes and the client credentials flow, and set a least-privilege Run As user.
- Mark the agent's
loyalty_tiercustom variable as External. - The app backend mints a token, starts a session, and sends the tier as a variable along with the user's messages.
- The app uses the streaming endpoint so replies appear word by word.
- The app ends the session when the user closes the chat.
Exam Traps
- Don't choose the Agent API when Enhanced Chat meets the requirement. Built-in channels include routing, escalation, and UI.
- Agentforce (Default) can't be called with the Agent API.
- The Agent API is inbound to the agent. For an agent to call external tools, use actions or MCP.
- Remember the 120-second timeout for long-running actions.
A company has a proprietary mobile app with its own chat interface and wants customers to converse with an Agentforce agent inside it. Which approach fits best?
Which OAuth scopes does Salesforce list for an external client app that calls the Agent API?
A developer's Agent API call that triggers a slow external action returns HTTP 500 after about two minutes. What is the most likely cause?
Which agent type can't be accessed with the Agent API?