Agent API Examples

This section provides examples using the Agent API endpoints. To onboard, see Get Started with Agent API.

The examples on this page use api.salesforce.com as the base endpoint. If your org is on Government Cloud, replace api.salesforce.com with api.gov.salesforce.com in every Agent API request.

Note

Postman Collection

The quickest way to get started with the Agent API is with our Postman collection.

Start Session

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

1curl --location -X POST https://api.salesforce.com/einstein/ai-agent/v1/agents/{AGENT_ID}/sessions \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer {ACCESS_TOKEN}' \
4--data '{
5  "externalSessionKey": "{RANDOM_UUID}",
6  "instanceConfig": {
7    "endpoint": "https://{MY_DOMAIN_URL}"
8  },
9  "streamingCapabilities": {
10    "chunkTypes": ["Text"]
11  },
12  "bypassUser": true
13}'

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.

Note

To make this request, these values are required.

AGENT_ID: The ID of the agent that you want to interact with. The method for obtaining this ID depends on which builder you used to create your agent. See Get the Agent ID for an Agent for detailed instructions.
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.

1{
2  "sessionId": "8e715939-a121-40ec-80e3-a8d1ac89da33",
3  "_links": {
4    "self": null,
5    "messages": {
6      "href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/8e715939-a121-40ec-80e3-a8d1ac89da33/messages/stream"
7    },
8    "session": {
9      "href": "https://api.salesforce.com/einstein/ai-agent/v1/agents/0XxQZ0000000Ty50AE/sessions"
10    },
11    "end": {
12      "href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/8e715939-a121-40ec-80e3-a8d1ac89da33"
13    }
14  },
15  "messages": [
16    {
17      "type": "Inform",
18      "id": "8e7cafae-0eb5-44b1-9195-21f1cd6e1f4b",
19      "feedbackId": "",
20      "planId": "",
21      "isContentSafe": true,
22      "message": "Hi, I'm an AI service assistant. How can I help you?",
23      "result": [],
24      "citedReferences": []
25    }
26  ]
27}

For API reference info, see Start Session.

Send Synchronous Messages

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.

1curl --location 'https://api.salesforce.com/einstein/ai-agent/v1/sessions/{SESSION_ID}/messages' \
2--header 'Accept: application/json' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer {ACCESS_TOKEN}' \
5--data '{
6  "message": {
7    "sequenceId": {SEQUENCE_ID},
8    "type": "Text",
9    "text": "Show me the cases associated with Lauren Bailey."
10  }
11}'

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.

1{
2    "messages": [
3        {
4            "type": "Inform",
5            "id": "ceb6b5de-6063-4e39-bc02-91e9bf7da867",
6            "metrics": {},
7            "feedbackId": "0bc8720e-e010-4129-87bb-70caaa885ee4",
8            "planId": "0bc8720e-e010-4129-87bb-70caaa885ee4",
9            "isContentSafe": true,
10            "message": "Here are two cases related to Lauren Bailey:\n\n1. Case Number: 00001116\n   - Subject: I have a question about my bill\n   - Description: When I received my most recent bill, I noticed there was a charge I didn't recognize. Can you look over my orders and help me understand what this might have been? Thank you!\n   - Status: New\n   - Created Date: 2025-04-05\n2. Case Number: 00001106\n   - Subject: I have a product suggestion.\n   - Description: I've been using your products for a long time, and I have a suggestion that I think would make them even better. What's the best way to share this with you?\n   - Status: Closed\n   - Created Date: 2025-04-05\n   - Closed Date: 2022-10-13.",
11            "result": [],
12            "citedReferences": []
13        }
14    ],
15    "_links": {
16        …(shortened)
17    }
18}

For API reference info, see Send Synchronous Messages.

Send Streaming 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.

1curl --location 'https://api.salesforce.com/einstein/ai-agent/v1/sessions/{SESSION_ID}/messages/stream' \
2--header 'Accept: text/event-stream' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer {ACCESS_TOKEN}' \
5--data '{
6  "message": {
7    "sequenceId": {SEQUENCE_ID},
8    "type": "Text",
9    "text": "Show me the cases associated with Lauren Bailey."
10  }
11}'

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.

1{
2  "timestamp": 1736902938827,
3  "originEventId": "1736902935340-REQ",
4  "traceId": "2fdb1d5e7eb48d35b9d1ba402eeb4b69",
5  "offset": 0,
6  "message": {
7    "type": "ProgressIndicator",
8    "id": "c4410599-8c0a-412d-910f-a60e4159d807",
9    "indicatorType": "ACTION",
10    "message": "Working on it"
11}

The message streams in text chunk increments. This example shows a TextChunk event.

1{
2  "timestamp": 1736902952425,
3  "originEventId": "1736902935340-REQ",
4  "traceId": "2fdb1d5e7eb48d35b9d1ba402eeb4b69",
5  "offset": 1,
6  "message": {
7    "type": "TextChunk",
8    "id": "6fc64974-9c20-484e-8b8c-105e460d4a00",
9    "offset": 1,
10    "message": "Here",
11    "formatType": "Text"
12  }
13}

The API returns the complete message in an Inform event.

1{
2    "messages": [
3        {
4            "type": "Inform",
5            "id": "f0313bcb-65a2-4abb-9d84-b872247b1420",
6            "metrics": {},
7            "feedbackId": "ab403163-b87f-4e4b-9fa6-18670a2be655",
8            "planId": "ab403163-b87f-4e4b-9fa6-18670a2be655",
9            "isContentSafe": true,
10            "message": "Here are two cases related to Lauren Bailey:\n\n1. Case Number: 00001116\n   - Subject: I have a question about my bill\n   - Description: When I received my most recent bill, I noticed there was a charge I didn't recognize. Can you look over my orders and help me understand what this might have been? Thank you!\n   - Status: New\n   - Created Date: 2025-04-05\n2. Case Number: 00001106\n   - Subject: I have a product suggestion.\n   - Description: I've been using your products for a long time, and I have a suggestion that I think would make them even better. What's the best way to share this with you?\n   - Status: Closed\n   - Created Date: 2025-04-05\n   - Closed Date: 2022-10-13",
11            "result": [],
12            "citedReferences": []
13        }
14    ],
15    "_links": {
16        "self": null,
17        "messages": {
18            "href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/499713a4-b441-4234-bafd-392ee08dbd01/messages"
19        },
20        "messagesStream": {
21            "href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/499713a4-b441-4234-bafd-392ee08dbd01/messages/stream"
22        },
23        "session": {
24            "href": "https://api.salesforce.com/einstein/ai-agent/v1/agents/0XxQZ0000000Ty50AE/sessions"
25        },
26        "end": {
27            "href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/499713a4-b441-4234-bafd-392ee08dbd01"
28        }
29    }
30}

The API returns an EndOfTurn event when the response is complete.

1{
2  "timestamp": 1736902953027,
3  "originEventId": "1736902935340-REQ",
4  "traceId": "2fdb1d5e7eb48d35b9d1ba402eeb4b69",
5  "offset": 0,
6  "message": {
7    "type": "EndOfTurn",
8    "id": "2a2be92b-f479-481a-9f22-1e5bf39e038e"
9  }
10}

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.

Tip

For API reference info, see Send Streaming Messages.

Send Agent Variables

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

Handle Citations

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.

1{
2    "timestamp": 1745599724677,
3    "originEventId": "1745599714159-REQ",
4    "traceId": "310046aaded69001de5dbddaec4f8a75",
5    "offset": 0,
6    "message": {
7        "type": "Inform",
8        "id": "484c59e5-9c24-4735-ba55-0707a071a9e7",
9        "feedbackId": "a9695531-091b-42de-8b4d-61f3aaadd42e",
10        "planId": "a9695531-091b-42de-8b4d-61f3aaadd42e",
11        "isContentSafe": true,
12        "message": "The 2024 Acura ZDX is Acura's first-ever all-electric vehicle, featuring:\n\n- Maximum Range: 313 miles\n- Starting Price: $65,850\n- Interior: Premium and spacious\n- Charging: Compatible with Tesla's Supercharger network\n- Trim Levels: Two available trims\n- Platform: Shares a platform with the Cadillac Lyriq and is built in the same Tennessee factory\n- Sales: Conducted exclusively online\n- Pricing:\n   - ZDX A-Spec: $65,850\n   - ZDX A-Spec with all-wheel drive: $69,850\n   - ZDX Type S: $74,850\n- Tax Credit: Eligible for a federal tax credit of up to $7,500\n\nIf you have any more questions or need further details, feel free to ask!",
13        "result": [],
14        "citedReferences": [
15            {
16                "type": "link",
17                "value": "https://myorgdomain.salesforce.com/ka0RZ000002DzSmYAK",
18                "recordId": "ka0RZ000002DzSmYAK",
19                "label": null,
20                "inlineMetadata": [
21                    {
22                        "claim": "The 2024 Acura ZDX is Acura's first-ever all-electric vehicle, featuring:\n\n- Maximum Range: 313 miles\n- Starting Price: $65,850\n- Interior: Premium and spacious\n- Charging: Compatible with Tesla's Supercharger network\n- Trim Levels:",
23                        "location": 236
24                    }
25                ]
26            },
27            {
28                "type": "link",
29                "value": "https://myorgdoamin.salesforce.com/ka0RZ000002E0INYA0",
30                "recordId": "ka0RZ000002E0INYA0",
31                "label": null,
32                "inlineMetadata": [
33                    {
34                        "claim": "Two available trims\n- Platform: Shares a platform with the Cadillac Lyriq and is built in the same Tennessee factory\n- Sales: Conducted exclusively online\n- Pricing:\n   - ZDX A-Spec: $65,850\n   - ZDX A-Spec with all-wheel drive: $69,850\n   - ZDX Type S: $74,850\n- Tax Credit: Eligible for a federal tax credit of up to $7,500",
35                        "location": 562
36                    }
37                ]
38            }
39        ]
40    }
41}

For API reference info, see InformMessage and CitedReference.

End Session

This curl command sends an end session request.

1curl --location --request DELETE 'https://api.salesforce.com/einstein/ai-agent/v1/sessions/{SESSION_ID}' \
2--header 'x-session-end-reason: UserRequest' \
3--header 'Authorization: Bearer {ACCESS_TOKEN}'

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.

1{
2  "messages": [
3    {
4      "type": "SessionEnded",
5      "id": "c5692ca0-ee1b-414a-9d96-4e7862456500",
6      "reason": "ClientRequest",
7      "feedbackId": ""
8    }
9  ],
10  "_links": {
11    "self": null,
12    "messages": {
13      "href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/8d705938-a121-40ec-80e3-a8d1ac89da33/messages/stream"
14    },
15    "session": {
16      "href": "https://api.salesforce.com/einstein/ai-agent/v1/agents/0XxQZ0000000Ty50AE/sessions"
17    },
18    "end": {
19      "href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/8d705938-a121-40ec-80e3-a8d1ac89da33"
20    }
21  }
22}

For API reference info, see End Session.

Submit Feedback

You can also submit feedback to the org based on the agent’s responses. This feedback is stored in Data 360. To learn more, see About Generative AI Audit and Feedback Data.

1curl -v --location 'https://api.salesforce.com/einstein/ai-agent/v1/sessions/{SESSION_ID}/feedback' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer {ACCESS_TOKEN}' \
4--data '{
5  "feedbackId": "9247bbd8-5ed9-11ee-8c99-0242ac120002",
6  "feedback": "GOOD",
7  "text": "Email looks great"
8}'

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.

Agent API Examples

Postman Collection

Start Session

Send Synchronous Messages

Send Streaming Messages

Send Agent Variables

Handle Citations

End Session

Submit Feedback

See Also