Build Custom AI Agents with Agent API
Learning Objectives
- Describe how to get started with using Agent API.
- Start a session with an AI agent using Agent API, and manage the session lifecycle.
Get Started with Agent API
You're a developer tasked with integrating Agentforce into your website so that Salesforce AI agents can help your customers with quick and helpful responses to their questions.
You know that this will simplify your workflows and enhance user interactions, but where do you start? Enter Agent API.
Let’s walk through the steps at a high level to get Agentforce up and running with Agent API.
Step 1: Enable Agentforce and Activate an Agent
First, you need to enable Agentforce in your Salesforce org. This is a crucial step, because without it, none of the subsequent configurations will work. Once Agentforce is enabled, you need to activate at least one agent.
Agent API doesn’t support agents of the type “Agentforce (Default)”.
Step 2: Create a Connected App and Enable OAuth Settings
Next, you need to create a connected app in Salesforce. This app handles the client credential flow, which is essential for secure API calls. Enable OAuth settings for API.
Step 3: Add the Connected App to Your Agent
Now, you need to add the connected app to your agent. This is done through the Connections tab in your Salesforce org. This step links your connected app to the agent, allowing you to make API calls.
Step 4: Obtain the Consumer Key and Consumer Secret
Once your connected app is set up, you need to obtain the consumer key and consumer secret. These credentials are essential for authenticating your API calls. You can find them in your connected app.
Step 5: Create a Token
All calls to Agent API require a token. This token is used to authenticate your API calls. You can create a token using the consumer key, consumer secret, and your domain name.
Try It Yourself: Make Your First API Call
Now comes the exciting part—making calls to the Agent API.
Before making the call, you need to gather some information from your org. To learn more, see Call the API in the Agent API Developer Guide.
Using a command-line interface, run this curl command to create a new agent session with the Agent API.
curl --location -X POST https://api.salesforce.com/einstein/ai-agent/v1/agents/{AGENT_ID}/sessions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data '{
"externalSessionKey": "{RANDOM_UUID}",
"instanceConfig": {
"endpoint": "https://{MY_DOMAIN_URL}"
},
"streamingCapabilities": {
"chunkTypes": ["Text"]
},
"bypassUser": true
}'
When this call succeeds, you receive a response with a session ID and additional info. Here’s a sample response.
{
"sessionId": "80ab2e16-392e-4c12-b80a-f028a58400b5",
"_links": {
"self": null,
"messages": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5/messages"
},
"messagesStream": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5/messages/stream"
},
"session": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/agents/0XxHr000000ysOSKAY/sessions"
},
"end": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5"
}
},
"messages": [
{
"type": "Inform",
"id": "d27b7308-f1ab-47bd-949c-0225d5e21a8e",
"feedbackId": "",
"planId": "",
"isContentSafe": true,
"message": "Hi, I'm an AI service assistant. How can I help you?",
"result": [],
"citedReferences": []
}
]
}Now you can start sending messages to the AI agent.
The Agent API supports both synchronous and streaming message handling. Synchronous messages are ideal for use cases where you need the complete response in a single call, while streaming messages are better for real-time interactions like chat conversations.
Once you’re done, remember to close the session.
What to Consider
-
Data usage: Each call to the Agent API consumes Einstein Requests. The number of requests used depends on the API call size and the large language model (LLM) usage type multiplier.
-
API timeouts: The Agent API has a 120-second timeout. If a call times out, you receive an HTTP 500 response.
Summary
There you have it. Use the Get Started with Agent API guide and sample code to start integrating Agentforce onto your website and improving the experience of your customers.