Agent API Examples

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. You can also review our video tutorial on Agent API setup and using the Postman collection.

This curl command creates a new agent session with the Agent API.

The bypassUser parameter indicates whether to use the agent-assigned user instead of the logged in user. If set to true, the API uses the user associated with the agent. If set to false, the API uses the user associated with the token.

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 is 0XxSB000000IPCr0AO.
  • 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 the Content-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 API 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 the Content-Type header to indicate JSON content in the request.

This example shows a potential response to a synchronous send message request.

For API 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 the Content-Type header to indicate JSON content in the request.
  • Specify text/event-stream in the Accept 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 indicates 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.

If you receive a ValidationFailureChunk streaming event, there was a failure validating the agent's response. Remove all previously rendered chunks and display only the new streamed content.

For API reference info, see Send Streaming Messages.

For an example using agent variables, see Send Agent Variables with the Agent API.

Some message responses include cited sources. Cited sources surface in the citedReferences array of an Inform response message. Citations can either appear as sources at the bottom of the response, or inline citations (using the inlineMetadata object) that are associated with a specific location in the response.

For API reference info, see InformMessage and CitedReference.

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 API 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 the Content-Type header to indicate JSON content in the request.

If the feedback was received, you get an HTTP 201 response.

For API reference info, see Submit Feedback.