This endpoint is in preview and may be modified or removed at any time.
To use this endpoint, add preview=true to the request query parameters.
Create a session for the specified Agent version. Creating a session runs Agent logic and may modify platform data.
Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:agents-write.
objectunionIdentifies an Agent.
map<ArgumentName, JsonValue>optionalValues for the creation arguments.
A missing key is treated as as undefined. A present key with an empty value is treated as null.
stringThe Agent version the session was created for.
objectThe created AgentSession
stringIdentifies an Agent session.
stringThe Agent the session was created for.
objectoptionalThe Agent API name and ontology RID for the Agent the session was created for. Empty if the Agent does not have an ontology binding.
stringThe Agent version the session was created for.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl -X POST \
\t-H "Content-type: application/json" \
\t-H "Authorization: Bearer $TOKEN" \
"https://$HOSTNAME/api/v2/agents/agentSessions?preview=true" \
-d '{
"agent": {
"type": "agentApiName",
"ontology": "customer-service",
"agentApiName": "customerSupportAgent"
},
"agentVersion": "1.2.0",
"arguments": {
"customer": {
"name": "Alice"
}
}
}'1
2
3
4
5
6
7
8
9
{
"agentRid": "ri.agent-engine..agent-definition.0b1a801c-de31-4c3d-96a6-e8a1a6a0c1b2",
"agentVersion": "1.2.0",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"agentApiNameIdentifier": {
"agentApiName": "customerSupportAgent",
"ontology": "example-ontology"
}
}| Error Name | ||
|---|---|---|
Agent | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The given Agent could not be found. | |
| Parameters | agentDefinitionApiName | |
Ontology | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The requested Ontology is not found, or the client token does not have access to it. | |
| Parameters | ontologyRid, apiName | |
Create | Error Code | INTERNAL |
| Status Code | 500 | |
| Description | The Agent session could not be started. | |
| Parameters | ontology, agentApiName, agentVersion | |
Create | Error Code | PERMISSION_DENIED |
| Status Code | 403 | |
| Description | Could not create the AgentSession. | |
| Parameters | | |
Agent | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The given AgentDefinitionVersion could not be found. | |
| Parameters | agentDefinitionVersionVersion, agentDefinitionApiName | |
See Errors for a general overview of errors in the platform.