Agentforce Agent API: agents in your own dealer apps
The Agentforce Agent API lets your own dealer app, machine portal or service app talk to an Agentforce agent over REST. Your backend gets a token through the client credentials flow, opens a session, sends messages and streams the answer to the screen. The hard part is identity. Every dealer in your app reaches Salesforce as one run-as user, so Salesforce sharing no longer keeps dealer A out of dealer B’s orders. I would build this only when your backend authenticates dealers itself, passes their account as a fixed variable and the agent’s actions filter on it.
What does the Agent API do?
Salesforce describes the Agent API1 as access to Agentforce agents “from anywhere that can call a REST API”. The listed use cases include websites, headless agents and agents calling other agents. For a machine builder that means the dealer app, the machine portal or a service partner’s app can use the agent your service team uses inside Salesforce.
The setup is short: an External Client App, a run-as user and a token, then start a session, send messages, end the session.
For developers
What the setup guide asks for in detail
- An External Client App with OAuth scopes
api,refresh_token,offline_access,chatbot_apiandsfap_api, the client credentials flow and JWT-based access tokens. - A Run As user with at least API Only access.
- A token from your My Domain, then calls to
api.salesforce.com/einstein/ai-agent/v1: start a session for an agent ID, send messages, end the session with aDELETE.
Messages go either synchronously or as a server-sent event stream2 with text chunks. One event matters for your app team: on ValidationFailureChunk the client has to remove chunks it already displayed, so a dealer may see text appear and disappear.
Three limits from the considerations3 and troubleshooting4 pages shape the architecture. Agents of type “Agentforce (Default)” are not supported. A call that runs longer than 120 seconds returns HTTP 500. A session handles one request at a time and answers a second one with HTTP 423. If an action fetches order data from SAP through middleware, that lookup has to come back well inside the 120 seconds, which is one more reason for the narrow ERP API I describe in Agentforce and SAP order status.
Who is the user when a dealer asks?
I would settle this before anyone writes code. With client credentials, the token belongs to the run-as user. The session flag bypassUser decides whether the agent runs as the agent-assigned user or as the user tied to the token. Either way it is one Salesforce identity for every dealer in your app.
Salesforce’s own architects warn about this pattern for headless access. In a Salesforce blog post of 19 May 20265 on agents calling Salesforce, Miriam McCabe writes: “The client credentials flow would create a service account pattern where all calls run as one identity, losing per-user permissions and the audit trail.” That post covers MCP clients with human users; the Agent API guide prescribes client credentials. Know which protection you give up.
What you give up is sharing as a dealer boundary. The run-as user needs read access to the orders, assets and warranty claims of all dealers, otherwise the agent cannot answer anyone. The boundary moves into two places you own:
- Your backend. It authenticates the dealer through your own login, maps the user to a Salesforce account ID and keeps the client secret. The secret never goes into a mobile app or a browser.
- The agent’s actions. The backend passes the account ID when it starts the session. The Agent API variables guide6 says many variables are read-only and can only be set at session start, and that a variable must allow “value to be set by API”. Every action, a Flow or Apex class, then filters on that variable. The language model never decides which account a query uses.
The second point is where Agent Script and deterministic rules earn their place. A dealer who types “show me the orders of account 4711” is attempting exactly the cross-dealer access you want to block, and a filter in logic stops it where an instruction in the prompt may not. The wider pattern is in prompt injection in dealer portals.
Audit follows the same logic. Salesforce logs the run-as user, so it cannot tell you which dealer asked. The session start takes an externalSessionKey, a UUID that, according to the setup guide, you can use to trace the conversation in the agent’s event logs. I would write that key next to the dealer’s user ID in your app’s log, so a question from your data protection officer can be answered from both sides.
For the run-as user I would use the Salesforce Integration user licence7 with its API-only profile and a permission set on top. Orgs get “a limited number” of these licences by default; the page gives no figure. One External Client App and one run-as user per external app keeps the damage small; token and IP controls are in connected apps and OAuth for AI integrations.
Agent API, chat channel and hosted MCP compared
The Agent API is one of three ways out of Salesforce, and the one with the most work on your side.
| Path | Who talks to the agent | Identity | Fits |
|---|---|---|---|
| Agent API | your own app or backend | one run-as user | dealer app, machine portal, system to agent |
| Enhanced Chat v2 | visitors on a website | Salesforce channel | service agent on a website |
| Hosted MCP tool | Claude, ChatGPT, Slackbot | signed-in Salesforce user | employees with their own AI client |
Salesforce positions its custom connections8, which let your client render agent answers as cards or forms through the Agent API, for teams that “need to build a channel from the ground up”, and points to Enhanced Chat v2 when an out-of-the-box channel is enough. If your dealers already log in to an Experience Cloud portal, that portal with its licences and sharing is often the simpler home for the agent; the trade-offs are in the Manufacturing Cloud customer portal.
For employees the hosted MCP page on agents9 describes the opposite model: the agent runs “in the authenticated user’s context”, with sharing and field-level security applied. Only agents built with the new Agent Script Builder qualify. The page states no release status; the GA announcement of 29 April 202610 still said “soon”. The MCP decisions for IT leads are in MCP explained for IT leads.
Worked example: dealer app and machine portal
Assume a machine builder with 250 dealers and its own dealer app for orders and spare parts, plus a portal where end customers see their installed machines. Both run on the company’s own backend and login. All numbers here are assumptions.
The dealer app gets an agent for order status and open warranty claims, the machine portal one for “which spare parts kit fits my machine”. The backend passes the dealer’s account ID or the customer’s asset IDs, and actions query only within them.
Assume 5,000 sessions a month with three actions each. At 20 Flex Credits per action11 that is 300,000 credits a month, 3.6 million a year. At $500 per 100,000 credits12 list price that is $1,500 a month for actions alone, prompts and Data 360 grounding on top. The year exceeds the 2.75 million Flex Credits that the Max edition13 includes per org per year, before your service team uses a single credit.
The test I would insist on before go-live: dealer A asks for an order number of dealer B in twenty phrasings. Every answer must be “not found”.
What does it cost, and what is still open?
The considerations page says Agent API usage “impacts credit consumption” and links to a Salesforce Help article on generative AI usage and billing, which did not render for me. So I calculate with the action rate above, and sandbox actions cost 16 credits instead of 20.
The open line is the Headless Platform Interaction meter. The rate card lists it as “TBA”. According to Salesforce Ben14, every successful call by a registered agent through MCP or direct API traffic classed as agentic will count, with 30 days’ notice before metering starts.
How to budget a meter without a price is in MCP calls as a budget risk.
Begin with one read-only use case such as order status
- Pick one read-only use case, such as order status for dealers, and keep write actions for later.
- Design the identity chain first: your login, account mapping, a session variable set by the API, actions that filter on it.
- One External Client App and one integration user per external app, with a permission set built from the action list.
- Run the cross-dealer test in a sandbox and repeat it with every new action.
- Log
externalSessionKeywith the dealer’s user ID in your app. - Get the Headless Platform Interaction question answered before you size the Flex Credit order.
For the cross-dealer test, two dealer accounts in a sandbox are enough: logged in as dealer A, you ask for the orders of dealer B. Interface and identity design is what I do under Salesforce integration; all interfaces side by side are in the masterclass chapter MCP and interfaces.
Sources14
- 1Agent API (opens in a new tab)developer.salesforce.com
- 2server-sent event stream (opens in a new tab)developer.salesforce.com
- 3considerations (opens in a new tab)developer.salesforce.com
- 4troubleshooting (opens in a new tab)developer.salesforce.com
- 5Salesforce blog post of 19 May 2026 (opens in a new tab)salesforce.com
- 6Agent API variables guide (opens in a new tab)developer.salesforce.com
- 7Salesforce Integration user licence (opens in a new tab)help.salesforce.com
- 8custom connections (opens in a new tab)developer.salesforce.com
- 9hosted MCP page on agents (opens in a new tab)developer.salesforce.com
- 10GA announcement of 29 April 2026 (opens in a new tab)developer.salesforce.com
- 1120 Flex Credits per action (opens in a new tab)salesforce.com
- 12$500 per 100,000 credits (opens in a new tab)salesforce.com
- 13Max edition (opens in a new tab)salesforce.com
- 14Salesforce Ben (opens in a new tab)salesforceben.com
Frequently asked questions
What is the Agentforce Agent API?
A REST API that gives access to Agentforce agents from anywhere that can call REST. A client creates a session for an agent, sends messages synchronously or as a stream and ends the session when done.
Which agents can be called through the Agent API?
Salesforce documents one exclusion: agents of type Agentforce (Default) are not supported. I would build a dedicated agent for the external app anyway, with only the topics and actions that app needs.
Do dealers in our own app need Salesforce licences to use the agent?
The setup guide only requires one run-as user with at least API Only access, which suits the Salesforce Integration user licence. The guide says nothing about the people typing into your app, so I would get the licence position confirmed in writing.
How long may an agent take to answer through the Agent API?
The Agent API has a 120-second timeout and returns HTTP 500 when a call exceeds it. A session also handles one request at a time, so your app must wait for the answer before sending the next message.
Can Claude or ChatGPT call our Agentforce agent instead of our own app?
Yes, through a hosted MCP server that exposes the agent as a tool. Only agents built with the new Agent Script Builder qualify, and the agent then runs in the context of the signed-in Salesforce user.