ExamFinch.com My Study

Study guide

3.4 When to Use the Agent API

Practice this exam

Salesforce Certified Agentforce Specialist Exam

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Exam Overview & How Agentforce Agents Work

1.1 Agentforce Specialist (AI-201) Exam Facts & Spring '26 Blueprint 1.2 How an Agent Works & the Building Blocks of Agent Script 1.3 Hybrid Reasoning: Agent Script in Canvas View and Script View

2 Chapter 2: Deterministic Control, Topics (Subagents) & Actions

2.1 Deterministic Behavior: Filters, Variables & Template Expressions 2.2 Standard and Custom Topics (Subagents) 2.3 Standard and Custom Agent Actions

3 Chapter 3: Agent Types, Security Context, Channels & Agent API

3.1 When to Use an Employee Agent or a Service Agent 3.2 Security Context: Who the Agent Runs As and How It Affects Actions 3.3 Connecting Agents to Channels: Digital Experiences, Email, Voice & Slack 3.4 When to Use the Agent API

4 Chapter 4: Prompt Builder Fundamentals

4.1 When to Use Prompt Builder 4.2 Access Controls Governing Prompt Templates 4.3 Prompt Template Types: Field Generation, Flex & More 4.4 Creating, Activating & Executing Prompt Templates

5 Chapter 5: Grounding, Prompt Best Practices, Trust Layer & Model Access

5.1 Choosing the Right Grounding Technique 5.2 Best Practices for Writing Effective Prompts 5.3 Einstein Trust Layer Security and Privacy Features 5.4 Managing and Preventing Access to Specific Models

6 Chapter 6: Data 360 Fundamentals for Agentforce

6.1 Agentforce Data Library: Types and Concepts 6.2 Chunking: Breaking Content Into Retrievable Units 6.3 Indexing and Search Types: Vector, Hybrid & Keyword 6.4 Retrievers: Individual, Ensemble & Filtered Retrieval

7 Chapter 7: Testing Agents with Testing Center

7.1 Testing an Agent with Testing Center 7.2 How Testing Center Evaluations Work

8 Chapter 8: Deploying Agents and Prompt Templates

8.1 Deploying an Agent from Sandbox to Production 8.2 Deploying Prompt Templates from Sandbox to Production

9 Chapter 9: Governance and Observability

9.1 Managing and Monitoring Agents 9.2 Agent Analytics and Agent Optimization

10 Chapter 10: Multi-Agent Orchestration, MCP & A2A

10.1 When a Multi-Agent Architecture Is Appropriate 10.2 Open Multi-Agent Protocols: MCP and A2A

3.4 When to Use the Agent API

Key Takeaways Explain This Topic AI

The Agent API is a REST API for starting agent sessions, sending messages synchronously or by streaming, submitting feedback, and ending sessions.

Agent API access requires an external client app using a JWT-based token flow such as client credentials, with the api, refresh_token/offline_access, chatbot_api, and sfap_api scopes.

The Agent API isn't supported for Agentforce (Default) agents, and calls time out after 120 seconds with an HTTP 500 response.

Use the Agent API for custom web or mobile experiences, headless automation, external platforms, and invoking Agentforce agents from other agents.

Agent API usage consumes credits, and custom variables must be marked External for the API to set them.

Last updated: September 2026

3.4 When to Use the Agent API

Quick Answer: Use the Agent API when something outside Salesforce's built-in channels needs to talk to an Agentforce agent over REST: your own website or mobile app UI, a headless automation with no chat window, a third-party platform or workflow, or another agent that invokes an Agentforce agent. If an out-of-the-box channel already meets the need (Enhanced Chat, messaging apps, email, voice, Slack, or the Agentforce panel), use that channel. It includes routing, escalation, and UI.

What the Agent API Does

Salesforce describes the Agent API as access to your autonomous agents from anywhere that can call a REST API . The documented use cases:

Connect to an Agentforce agent from your website with your own chat UI.

Create and deploy headless agents that automate work without UI constraints.

Connect agents to your favorite platforms and workflows using standard endpoints.

Build an agentic ecosystem by invoking Agentforce agents from other agents.

Session lifecycle

Stage What you do

Start a session POST to the agent's sessions endpoint, https://api.salesforce.com/einstein/ai-agent/v1/agents/{AGENT_ID}/sessions , with a random UUID session key you can trace in event logs

Send messages Use the synchronous endpoint for a complete response in one call, or the streaming endpoint to show chunks as they arrive in a real-time chat

  • Submit feedback Optional endpoint to send feedback on a response
  • End the session Close the session when finished. The agent keeps context only for the session's duration

For Government Cloud orgs, replace api.salesforce.com with api.gov.salesforce.com .

Setting It Up

Have an active agent. Agentforce must be enabled with at least one agent activated.

Create an external client app (ECA) in Setup → External Client Apps Manager, and enable OAuth with these scopes:

  • Manage user data via APIs ( api )
  • Perform requests at any time ( refresh_token , offline_access )
  • Access chatbot services ( chatbot_api )
  • Access the Salesforce API Platform ( sfap_api )

Enable the Client Credentials Flow and Issue JWT-based access tokens for named users . Salesforce's example uses client credentials, but any flow that provides a JWT-based access token works.

Set the Run As user for the client credentials flow to a user with at least API Only access.

Mint a token with the consumer key, consumer secret, and your My Domain URL (for example some_domain.my.salesforce.com , not the lightning.force.com domain).

Get the agent ID (the method depends on which builder created the agent) and start a session.

When you start a session, the bypassUser parameter controls identity. True uses the user assigned to the agent. False uses the user associated with the access token. In the client-credentials example it's set to true.

Loading diagram... Agent API session lifecycle

Considerations and Limits

  • Consideration Detail
  • Unsupported agent type The Agent API isn't supported for Agentforce (Default) agents
  • Timeout 120 seconds. A timed-out call returns HTTP 500
  • Billing Agent API usage consumes credits under Agentforce and generative AI usage billing
  • Variables Only custom variables marked External can be set through the API

Security The token's user or the agent's assigned user determines data access, so apply least privilege, the same as for any agent user

Channels and escalation You build the UI and any handoff logic yourself. Omni-Channel escalation comes with Salesforce messaging channels

Agent API vs. Other Integration Options

Need Best option Why

A branded chat inside your React web app with your own components Agent API Full control of UI and session handling

A ready-made chat widget with escalation to reps, queue position, and pre-chat forms Enhanced Chat Salesforce-managed UI and Omni-Channel routing

A nightly job asks an agent to triage 500 support tickets without a UI Agent API (headless) Programmatic sessions and messages

A Salesforce flow needs an agent's reasoning inside a business process Invoke the agent from Flow or Apex (Salesforce documents calling an agent from a Flow or Apex class) Stays on-platform without an external token

An agent needs to call an external system's tools MCP tool actions or API-based actions The agent is the caller, not the callee

An external agent platform needs to delegate a task to an Agentforce agent Agent API today; A2A where supported Agent-to-agent communication

Two Agentforce agents in the same org should collaborate Multi-Agent Orchestration (connected subagents) Native handoff and supervisor modes

Scenario Walkthrough

A travel company already has a mobile app with its own chat screen. It wants the Agentforce Service agent to answer booking questions inside that screen and pass the member's loyalty tier into the conversation.

Create an ECA with the required scopes and the client credentials flow, and set a least-privilege Run As user.

Mark the agent's loyalty_tier custom variable as External .

The app backend mints a token, starts a session, and sends the tier as a variable along with the user's messages.

The app uses the streaming endpoint so replies appear word by word.

The app ends the session when the user closes the chat.

Exam Traps

Don't choose the Agent API when Enhanced Chat meets the requirement. Built-in channels include routing, escalation, and UI.

Agentforce (Default) can't be called with the Agent API.

The Agent API is inbound to the agent. For an agent to call external tools, use actions or MCP.

Remember the 120-second timeout for long-running actions.