Search documentation
karat

+

K

User Documentation ↗
Version 2.0

Create Agent Session

POST/api/v2/agents/agentSessions
Warning

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.

Query parameters

preview
booleanoptional

Enables the use of preview functionality.

Request body

CreateAgentSessionRequest
object
Hide child attributes

Hide child attributes

agent
union

Identifies an Agent.

Show child attributes

Show child attributes

arguments
map<ArgumentName, JsonValue>optional

Values for the creation arguments.

A missing key is treated as as undefined. A present key with an empty value is treated as null.

Show child attributes

Show child attributes

agentVersion
string

The Agent version the session was created for.

Response body

AgentSession
object

The created AgentSession

Hide child attributes

Hide child attributes

id
string

Identifies an Agent session.

agentRid
string

The Agent the session was created for.

agentApiNameIdentifier
objectoptional

The Agent API name and ontology RID for the Agent the session was created for. Empty if the Agent does not have an ontology binding.

Show child attributes

Show child attributes

agentVersion
string

The Agent version the session was created for.

Examples

Request

Copied!
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" } } }'

Response

Copied!
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 responses

Error Name
AgentDefinitionNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe given Agent could not be found.
ParametersagentDefinitionApiName
OntologyNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe requested Ontology is not found, or the client token does not have access to it.
ParametersontologyRid, apiName
CreateAgentSessionFailedError CodeINTERNAL
Status Code500
DescriptionThe Agent session could not be started.
Parametersontology, agentApiName, agentVersion
CreateAgentSessionPermissionDeniedError CodePERMISSION_DENIED
Status Code403
DescriptionCould not create the AgentSession.
Parameters
AgentDefinitionVersionNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe given AgentDefinitionVersion could not be found.
ParametersagentDefinitionVersionVersion, agentDefinitionApiName