Build Headless Agents with the Agent API

Unlike traditional, chat-driven agents, headless agents focus on automation and integrations with third-party systems. Headless agents can be called without a human trigger from a user interface and can perform tasks autonomously. For example, an Apex trigger or a scheduled job can call a headless agent as part of a background process.

At TDX ’25, we unveiled exciting advancements in AI and automation, particularly with Agent API. In this post, we’ll dive into the concept of headless agents and how you can leverage Agent API to build new agentic experiences.

Building complex, autonomous workflows

As the number of headless agents grows in a particular workflow, the need for multi-agent systems becomes crucial. Multi-agent systems involve multiple autonomous agents that interact and collaborate with each other to perform complex tasks and solve problems. In these types of systems, an orchestrator agent would manage and invoke specialized agents, creating a seamless user experience.

For example, a loan application system could use a number of sub-agents that live in distributed systems, such as agents from other Salesforce orgs along with non-Salesforce agents. Examples include:

• Customer Interaction Agent
• Document Verification Agent
• Credit Score Agent
• Risk Analysis Agent
• Loan Decision Agent

This approach brings autonomous intelligence to complex enterprise workflows, both user-facing and headless.

Interacting with agents through APIs

The Messaging for In-App and Web (MIAW) API and newly-released Agent API are the two Salesforce APIs that interact with Agentforce. Both have distinct features that make them suitable for specific use cases.

The MIAW API was released several years ago and it was originally designed for “human in the loop” (UI-first) use cases, such as customer service assistance. MIAW handles conversations on a variety of platforms (Experience Cloud, custom third-party sites, mobile apps, and others) through a number of interaction types (e.g., text, form, file exchange). MIAW is moderately complex to set up. It can be connected to a service agent while allowing escalation to humans.

Agent API, on the other hand, is specifically designed for headless agentic use cases. It is very simple to set up and offers just the right operations for interacting with an agent.

Setting up Agent API

Setting up the API is a simple, two-step process (see documentation for more details).

1. Create a connected app with the required OAuth scopes.
2. Add the connected app as a “connection” in the service agent configuration.

Once you’ve completed these two configuration steps, you can start using the API.

Using Agent API

Agent API lets you establish agent conversations with prompts through synchronous and asynchronous requests. You can use this API regardless of whether or not you have access to a user interface.

Conversations and prompts

The sequence diagram below shows the classic request exchange that takes place between an Agent API client and Agentforce.

The request exchange sequence is as follows:

1. The client starts by authenticating with the Salesforce Platform and receives an access token that it will use in subsequent calls.
2. The client starts a conversation (this is similar to opening a chat session).
3. The client runs a series of prompts that enrich the conversation context. Prompts can be sent synchronously or asynchronously (more on this later).
4. At some point, the client closes the conversation.
5. At any time, the client may provide feedback on the agent’s responses.

Synchronous and asynchronous prompts

The agent API supports both synchronous prompts through blocking HTTP requests and asynchronous prompts with Server-sent events (SSE).

Synchronous prompts: These are the easiest to implement, and they are well tailored to pure back-end operations when no UI is involved. When using synchronous prompts, you’ll run a single HTTP request that lasts for tens of seconds. If you use a synchronous prompt in the context of a UI, you won’t be able to notify the user about the operation’s progress and this would lead to a poor user experience during this time.

Asynchronous prompts: These are slightly more complex to implement as they require an event-driven architecture backed with SSE. However, this extra implementation effort is vital when building UI-driven prompts as they unlock dynamic UI feedback thanks to response streaming and chunking.

The way SSE works is that the client first sends a standard HTTP request. This request is then upgraded to SSE allowing the server to stream multiple events over a long lasting connection.

In the case of Agent API, the prompt is sent in the initial HTTP request. Then, multiple events are streamed back to the client, including:

• Progress Indicator events hold the various custom loading messages of the agent actions that are being run.
• If response chunking is enabled, Text Chunk events hold fragments of the agent response. This lets you start to populate the UI with bits of the response.
• Regardless of whether response chunking is enabled, an Inform event is delivered with the entire agent response.
• Finally, an End of Turn event is delivered to denote the end of the prompt operation.

For a hands-on experience, we recommend that you start by checking out the Agent API Postman collection, and then explore custom integrations with clients, such as this Agent API Node.js client.

More ways to build a headless agent

In addition to Agent API, we’re expanding the ways in which you can build headless agents to include using Flow and Apex.

Call a prompt from a flow

You can pick the new AI Agent Actions flow action that matches your service agent (Customer Assistance Agent in the screenshot below).

Once you’ve selected the action, you can pass a dynamic prompt and an optional session ID to the agent. Then, you can extract the agent response and the session ID.

Call a prompt from Apex

In addition to flow actions, you can run a prompt from Apex by calling the automatically-generated generateAiAgentResponse invocable action as illustrated in the example below.

public with sharing class CourseRecommendationAgent {

    private final static String STANDARD_AI_ACTION = 'generateAiAgentResponse';
    // Your agent's name
    private final static String AGENT_NAME = 'Customer_Assistance_Agent';

    public static String runPrompt(String prompt) {
        // Prepare the action
        Invocable.Action action = Invocable.Action.createCustomAction(STANDARD_AI_ACTION, AGENT_NAME);
        action.setInvocationParameter('userMessage', prompt);

        // Execute the action
        List results = action.invoke();
        Invocable.Action.Result result = results[0];

        // Handle the response
        if (result.isSuccess()) {
            // Retrieve the Session ID and Agent Response
            String sessionId = (String) result.getOutputParameters().get('sessionId');
            String response = (String) result.getOutputParameters().get('agentResponse');
            return response;
        } else {
            throw new AgentPromptException('Action execution failed: ' + result.getErrors());
        }
    }

    public class AgentPromptException extends Exception {}
}

Conclusion

Agent API opens up a new world of automation and efficiency. By building headless, autonomous agents, you can open the door to multi-agent experiences and build complex integrations. Start building headless agents today! 

Resources

• Video: TDX ’25 session on headless agents
• Documentation: Agent API Developer Guide
• Postman: Agent API Postman Collection
• GitHub: Node client for the Salesforce Agent API
• Documentation: Calling an agent from Apex
• Documentation: Calling an agent from Flow

About the author

Philippe Ozil is a Principal Developer Advocate at Salesforce, where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full-stack developer and enjoys working with APIs, DevOps, robotics, and VR projects. Follow him on X, LinkedIn, and Bluesky. Check his GitHub projects.