Section 4 · AI Agents · 35% of exam
4.12 When to Use Agent API
Exam objective
Given a scenario, identify when the Agent API is appropriate for connecting an Agentforce agent to a custom application or workflow.
What the Agent API provides
The Agent API exposes an Agentforce agent through REST endpoints so an external client can interact with it programmatically. A client can start a session, send messages, receive responses, and end the session. Salesforce also documents synchronous and streaming message patterns. This is useful when an organization wants the agent’s reasoning, subagent selection, and actions inside an application or user experience that is not already a Salesforce-managed channel. The API does not build the client interface for you; the application must manage authentication, session state, rendering, errors, and user experience.
Choose API versus a standard channel
Use a standard supported connection when it provides the needed experience and channel behavior, such as Enhanced Chat or Slack. Consider Agent API when the client is custom, a separate application needs direct interaction, or the organization must embed the agent in its own interface. Salesforce’s custom connection documentation describes structured response formats that can support native components such as cards, forms, or pickers. Building a custom channel requires more implementation and testing than enabling an out-of-the-box connection. Do not choose an API simply because the agent uses AI; choose it when programmatic integration solves a specific requirement that a supported channel does not.
Understand setup and limitations
Salesforce Developer documentation says Agent API use requires Agentforce to be enabled and at least one agent activated, plus an External Client App for secure OAuth access. The API is not supported for agents of type Agentforce (Default). Session calls use an agent ID, a bearer token, and a session key; later messages use the active session ID. API calls must be authorized for the correct Salesforce user context, and the bypassUser setting affects whether the agent-assigned user or token-associated user is used. Review current Agent API considerations for usage, timeouts, and supported agent types before committing to an integration.
Design the client responsibly
The external client should securely obtain tokens, avoid exposing client secrets in a browser, maintain the conversation session correctly, and handle timeouts, errors, and service-unavailable responses. If the API returns structured content, validate it before rendering it as a component. Treat user identity, access, and session lifecycle as part of the architecture. Test concurrent sessions, expired tokens, transfer or escalation behavior, and the UI’s response to partial or failed messages. A custom interface may need channel-specific instructions or a custom connection to produce the desired output format. Keep using platform permissions and least-privilege access for the user associated with the API call.
TIP: Select Agent API when a custom application must interact with an Agentforce agent programmatically and a supported standard channel does not meet the experience requirement.
Agent API is not supported for Agentforce (Default) agents. Verify the selected agent type and the current API setup requirements before designing around it.
Extra concept: The Agent API provides session and message operations; your client remains responsible for secure authentication and rendering the conversation.
Official references:
- Get Started with the Agent API https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-get-started.html
- Agent API Developer Guide https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api.html
- Agent API Considerations https://developer.salesforce.com/docs/ai/agentforce/guide/agent-api-considerations.html
Key takeaways
- Agent API connects an agent to custom applications through REST sessions and messages.
- Prefer standard connections when they meet the requirement; custom clients add security and lifecycle responsibilities.
- Confirm agent type, OAuth setup, user context, error handling, and current API limits.
