Register an external client app in Salesforce Setup with OAuth scopes: chatbot_api, sfap_api, api, and refresh_token; configure the Client Credentials flow for server-to-server calls.
Obtain an access token via the OAuth 2.0 client credentials flow: POST to https://<instance>.salesforce.com/services/oauth2/token with grant_type=client_credentials.
Start an agent session: POST https://api.salesforce.com/einstein/ai-agent/v1/agents/<agentId>/sessions with a JSON body containing externalSessionKey (a UUID), instanceConfig.endpoint (your org URL), and streamingCapabilities.
Send a message to the agent within the session: POST https://api.salesforce.com/einstein/ai-agent/v1/sessions/<sessionId>/messages with body {"message": {"role": "user", "content": [{"type": "text", "text": "<user input>"}]}.
Parse the streaming or synchronous response to extract the agent's reply text and any action outputs; handle the sequenceId to maintain conversation order.
End the session when the conversation is complete: DELETE https://api.salesforce.com/einstein/ai-agent/v1/sessions/<sessionId>.
Known gotchas
The Agent API has a 120-second per-request timeout; if the agent takes longer to respond (e.g., executing slow actions), the call returns HTTP 500 — design clients to handle this and retry with the same sessionId.
The agentId is the 18-character Salesforce record ID of the Bot/Agent record, not the developer name — obtain it from Setup > Agentforce Agents or via a SOQL query on the BotDefinition object.
Sessions are stateful and tied to the externalSessionKey you provide; using the same key for a new session after ending the previous one may cause unexpected behavior — always generate a fresh UUID per conversation.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp