Headless Agentforce: The Agent API

Why headless?

Salesforce increasingly works as an API-first — "headless" — platform: agents, LLMs (Models API) and data are all reachable without a browser. The Agent API is the piece that makes Agentforce headless: a REST interface to start a session with an agent, exchange messages (synchronously or streamed), and end the session. Your agent's topics, actions, guardrails and Data Cloud grounding all still apply — only the front end is yours.

That means one agent, built once, can serve your customer portal, a WhatsApp bot, an internal tool, or a nightly automation — no Experience Cloud embed required.

Setup: External Client App + client credentials

Per the official Get Started guide, you authenticate with an External Client App (the successor to connected apps) using the OAuth client credentials flow:

1. Create an External Client App with OAuth scopes: api, refresh_token / offline_access, chatbot_api and sfap_api.
2. Enable the client credentials flow and JWT-based access tokens; set the Run As user (API-only access is enough).
3. Mint a token against your My Domain URL — not lightning.force.com.

curl -X POST \
  https://YOUR_DOMAIN.my.salesforce.com/services/oauth2/token \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CONSUMER_KEY' \
  -d 'client_secret=YOUR_CONSUMER_SECRET'
# => { "access_token": "00D...", ... }

The session lifecycle

1. Start a session with your agent's ID (from the agent's URL in Setup or the Metadata API):

curl -X POST \
  https://api.salesforce.com/einstein/ai-agent/v1/agents/AGENT_ID/sessions \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalSessionKey": "RANDOM_UUID",
    "instanceConfig": { "endpoint": "https://YOUR_DOMAIN.my.salesforce.com" },
    "streamingCapabilities": { "chunkTypes": ["Text"] },
    "bypassUser": true
  }'
# => { "sessionId": "...", "messages": [ { "type": "Inform", ... } ] }

2. Send messages to the session (synchronous variant shown; a streaming endpoint returns Server-Sent Events for token-by-token output):

curl -X POST \
  https://api.salesforce.com/einstein/ai-agent/v1/sessions/SESSION_ID/messages \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": {
      "sequenceId": 1,
      "type": "Text",
      "text": "Where is order 8842?"
    }
  }'

3. End the session when the conversation is over:

curl -X DELETE \
  https://api.salesforce.com/einstein/ai-agent/v1/sessions/SESSION_ID \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'x-session-end-reason: UserRequest'

Always verify payload details against the Agent API reference — the API is evolving quickly release to release.

Real-life scenario: order-status agent in an existing portal

A manufacturer already has a customer portal built on Next.js — no Experience Cloud. They build one Agentforce agent with two actions (look up order, fetch shipment events) and put it behind their existing chat widget:

1. The portal backend (Node.js) mints a client-credentials token server-side — the browser never sees Salesforce credentials.
2. When a logged-in customer opens chat, the backend starts an Agent API session and maps it to the portal user; the customer's account ID is passed as context so the agent only sees their orders.
3. Messages stream back over SSE for a responsive feel; transcripts land on the Case record via the agent's standard Salesforce integration.
4. The same agent later powers a WhatsApp channel — same agent ID, a second thin adapter, zero agent changes.

The pattern to remember: build the intelligence once in Agentforce; treat every channel as a thin client of the Agent API.

Headless checklist

• Keep tokens and session creation server-side; never expose client_secret in a browser.
• Generate a fresh externalSessionKey (UUID) per conversation and persist the mapping to your user.
• Handle agent messages of different types (Inform, Failure, Escalation) — do not assume plain text.
• End sessions explicitly; orphaned sessions make usage reporting murky.
• Load-test with realistic conversation lengths — LLM latency dominates, so design your UI for streaming.

Sources: Agent API — Get Started (Salesforce Developers) · Chat with Agents Using Agent API · Trailhead: Build Custom AI Agents with Agent API