Agent API Examples (Pilot)
This section provides examples using the Agent API endpoints. To onboard, see Get Started with Agent API.
The quickest way to get started with the Agent API is with our Postman collection.
This curl command creates a new agent session with the Agent API.
To make this request, these values are required.
AGENT_ID
: The ID of the agent that you want to interact with. You can find this ID in the URL of the Agent Overview Page. When you select the agent from Setup, use the 18-character ID at the end of the URL. For example, when viewing this URL,https://mydomain.test1.my.pc-rnd.salesforce-setup.com/lightning/setup/EinsteinCopilot/0XxSB000000IPCr0AO/edit
, the agent ID is0XxSB000000IPCr0AO
.RANDOM_UUID
: A random UUID value that you provide to represent the session key. You can use this parameter to trace the conversation in your agent’s event logs.ACCESS_TOKEN
: The token that you created in Create a Token.MY_DOMAIN_URL
: From Setup, search for My Domain. Copy the value shown in the Current My Domain URL field.- Specify
application/json
in theContent-Type
header to indicate JSON content in the request.
This example shows a start session response. The response returns the session ID (sessionId
) value, which is required when sending messages to an agent.
For reference info, see Start Session.
When you send a message by using the synchronous endpoint, the server sends back the response synchronously in one response. To use the streaming endpoint, see Send Streaming Messages.
Before sending messages, you must start a session. See Start Session.
This curl command sends a message to the synchronous endpoint.
To make this request, these values are required.
SESSION_ID
: The session ID found in the response payload when you created a session.ACCESS_TOKEN
: The token that you created in Create a Token.SEQUENCE_ID
: A number that you provide to represent the sequence ID. Increase this number for each subsequent message in this session.- Specify
application/json
in theContent-Type
header to indicate JSON content in the request.
This example shows a response to a synchronous send message request.
For reference info, see Send Synchronous Messages.
When you send a message using the streaming endpoint, the server sends back information using the server-sent event (SSE) protocol. To use the synchronous endpoint, see Send Synchronous Messages.
Before sending messages, you must start a session. See Start Session.
This curl command sends a message to the streaming endpoint.
To make this request, these values are required.
SESSION_ID
: The session ID found in the response payload when you created a session.ACCESS_TOKEN
: The token that you created in Create a Token.SEQUENCE_ID
: A number that you provide to represent the sequence ID. Increase this number for each subsequent message in this session.- Specify
application/json
in theContent-Type
header to indicate JSON content in the request. - Specify
text/event-stream
in theAccept
header so that the response contains the message stream.
When you make a streaming request, messages return in the event stream.
This example shows a ProgressIndicator
event, which states that a response is in progress.
The message streams in text chunk increments. This example shows a TextChunk
event.
The API returns the complete message in an Inform
event.
The API returns an EndOfTurn
event when the response is complete.
For reference info, see Send Streaming Messages.
This curl command sends an end session request.
To make this request, these values are required.
SESSION_ID
: The session ID found in the response payload when you created a session.ACCESS_TOKEN
: The token that you created in Create a Token.
This example shows a response to an end message request.
For reference info, see End Session.
You can also submit feedback to the org based on the agent’s responses. This feedback is stored in Data Cloud. To learn more, see Generative AI Audit and Feedback Data.
To make this request, these values are required.
SESSION_ID
: The session ID found in the response payload when you created a session.ACCESS_TOKEN
: The token that you created in Create a Token.- Specify
application/json
in theContent-Type
header to indicate JSON content in the request.
If the feedback was received, you get an HTTP 201 response.
For reference info, see Submit Feedback.
- Get Started with Agent API
- Agent API Session Lifecycle
- Agent API Postman Collection
- Agent API Troubleshooting
- Agent API Reference