# Agent API for headless agent integrations

*Agentforce Specialist Study Guide · AI Agents · Last updated October 15, 2026 · https://www.certifyforce.com/study-guide/agentforce-specialist/ai-agents/agent-api-for-headless-agent-integrations*

When to reach an agent over the Agent API instead of a channel, SDK or flow action, and how an integration works: external client app with client credentials, sessions with a session key, sequence IDs, synchronous versus streaming replies, bypassUser, and the documented limits.

- Certification: Salesforce Agentforce Specialist
- Exam section: AI Agents
- Study guide: https://www.certifyforce.com/study-guide/agentforce-specialist

**Official exam objective:**

> Given a scenario, identify when it's appropriate to use Agent API.

## What the exam expects

- Decide when the Agent API is the right way to reach an agent and when a channel connection, the Agentforce Mobile SDK, Enhanced Chat v2 or the flow/Apex invocable action fits better.
- List the setup for a headless integration: external client app, client credentials flow, Run As user, token minted against My Domain.
- Explain sessions, session keys, sequence IDs, synchronous versus streaming responses and the streaming events a client must handle.
- Recall the documented constraints: Agentforce (Default) unsupported, 120-second timeout, credit consumption, Government Cloud endpoint, bypassUser.
- Key terms: **Agent API** (REST API to start sessions, send and receive messages, and end sessions with an agent); **external client app** (the OAuth app that issues the API's access token); **session key** (a random UUID you supply to trace the conversation); **sequenceId** (a number that must increase with each message in a session); **bypassUser** (start-session flag choosing the agent's user or the token's user).

## Key facts

| Fact | Detail | Source |
|---|---|---|
| What the API does | Start sessions, send and receive messages, end sessions over REST | [Get Started with the Agent API](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-get-started.html) |
| Prerequisite | Agentforce enabled with at least one active agent | [Get Started with the Agent API](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-get-started.html) |
| Token source | External client app, JWT-based token; Run As user with at least API Only | [Get Started with the Agent API](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-get-started.html) |
| Token URL | My Domain URL, not the lightning.force.com domain | [Get Started with the Agent API](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-get-started.html) |
| Session key | Random UUID you supply; traces the conversation in event logs | [Agent API Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-examples.html) |
| sequenceId | Increase it for each subsequent message in a session | [Agent API Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-examples.html) |
| bypassUser true | Uses the agent's assigned user; false uses the token's user | [Agent API Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-examples.html) |
| Streaming | Accept: text/event-stream; ProgressIndicator, TextChunk, Inform, EndOfTurn | [Agent API Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-examples.html) |
| Timeout | 120 seconds, then HTTP 500 | [Agent API Considerations](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-considerations.html) |
| Unsupported agent type | Agentforce (Default) | [Agent API Considerations](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-considerations.html) |
| In-platform alternative | Invocable action to chat with an agent from a flow or Apex class | [Agentforce APIs and SDKs](https://developer.salesforce.com/docs/ai/agentforce/guide/get-started-agents.html) |

## Check yourself

- When is the invocable action a better choice than the Agent API?
- Why must a client increase sequenceId on every send?
- What happens when an Agent API call runs longer than 120 seconds?
- Why would you choose the synchronous endpoint?

## Sources

- [Get Started with the Agent API](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-get-started.html)
- [Agent API Considerations](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-considerations.html)
- [Agent API Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-examples.html)
- [Agent API Session Lifecycle](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-lifecycle.html)
- [Get Started with Agentforce APIs and SDKs](https://developer.salesforce.com/docs/ai/agentforce/guide/get-started-agents.html)
- [Deploy Your Agent to Channels](https://help.salesforce.com/s/articleView?id=ai.service_agent_setup_channels.htm&language=en_US&type=5)

## About the full unit

The "Core concepts", "Exam traps" and "Worked scenario" sections of this unit, its 13 linked practice questions, and unlimited timed mock exams are included with the Agentforce Specialist pack (USD $19): https://www.certifyforce.com/practice-exams