Manage an Agentforce agent session lifecycle: start, continue conversation, and end the session
domain: developer.salesforce.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Salesforce Bulk API 2.0 limits — the full failure-mode walkthrough related to developer.salesforce.com, checked against official docs, with linked verified routes.
Steps
Start a session by POSTing to https://api.salesforce.com/einstein/ai-agent/v1/agents/<agentId>/sessions; include externalSessionKey (a UUID you generate and store), instanceConfig.endpoint (org URL), and bypassUser (true to run as the agent's assigned user).
Capture the sessionId from the response — all subsequent calls for this conversation must reference this ID.
Send user messages via POST https://api.salesforce.com/einstein/ai-agent/v1/sessions/<sessionId>/messages; include the message payload and a unique sequenceId to detect out-of-order delivery.
Process the response, which may include the agent's text reply and any invoked action results; if the response indicates the agent is waiting for more input, send the next user turn with a new sequenceId.
Detect session expiration: if a message POST returns 404 or a session-not-found error, the session has expired — start a new session and resume the conversation.
Explicitly end sessions when the conversation is complete via DELETE https://api.salesforce.com/einstein/ai-agent/v1/sessions/<sessionId> to free server-side resources.
Known gotchas
Sessions time out after a period of inactivity (typically a few minutes); clients must handle the 404/session-expired error and restart the session if the user resumes after an idle gap.
The externalSessionKey is your correlation handle — store it alongside your application's session state so you can reference it in logs; it does not replace the sessionId for API calls.
Sending two messages concurrently to the same sessionId is not supported; messages must be sent sequentially and you must wait for the response before sending the next turn.
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?