Create Session

POST/api/v2/aipAgents/agents/{agentRid}/sessions

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 new conversation session between the calling user and an Agent. Use blockingContinue or streamingContinue to start adding exchanges to the session.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:aip-agents-write.

Path parameters

agentRid

string

An RID identifying an AIP Agent created in AIP Agent Studio.

Query parameters

preview

boolean

optional

Enables the use of preview functionality.

Request body

CreateSessionRequest

object

Hide child attributes

agentVersion

string

optional

The version of the Agent associated with the session. This can be set by clients on session creation. If not specified, defaults to use the latest published version of the Agent at session creation time.

Response body

Session

object

The created Session

Hide child attributes

rid

string

The Resource Identifier (RID) of the conversation session.

metadata

object

Metadata about the session.

Show child attributes

agentRid

string

The Resource Identifier (RID) of the Agent associated with the session.

agentVersion

string

Examples

Request

Copied!

curl -X POST \
	-H "Content-type: application/json" \
	-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v2/aipAgents/agents/ri.aip-agents..agent.732cd5b4-7ca7-4219-aabb-6e976faf63b1/sessions?preview=true" \
	-d '{"agentVersion":"1.0"}'

Response

Copied!

{
  "metadata": {
    "updatedTime": "2024-10-01T22:04:24.962583055Z",
    "estimatedExpiresTime": "2024-10-02T22:04:24.962583055Z",
    "messageCount": 6,
    "createdTime": "2024-10-01T20:04:24.962583055Z",
    "title": "What is the status of my order?"
  },
  "agentRid": "ri.aip-agents..agent.732cd5b4-7ca7-4219-aabb-6e976faf63b1",
  "agentVersion": "1.0",
  "rid": "ri.aip-agents..session.292db3b2-b653-4de6-971c-7e97a7b881d6"
}

Error responses

Error Name
`NoPublishedAgentVersion`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	Failed to retrieve the latest published version of the Agent because the Agent has no published versions. Try publishing the Agent in AIP Agent Studio to use the latest published version, or specify the version of the Agent to use.
	Parameters	`agentRid`
`ObjectTypeIdsNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	Some object types are configured for use by the Agent but could not be found. The object types either do not exist or the client token does not have access. Object types can be checked by listing available object types through the API, or searching in [Ontology Manager](/docs/foundry/ontology-manager/overview/).
	Parameters	`agentRid, sessionRid, objectTypeIds`
`ObjectTypeRidsNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	Some object types are configured for use by the Agent but could not be found. The object types either do not exist or the client token does not have access. Object types can be checked by listing available object types through the API, or searching in [Ontology Manager](/docs/foundry/ontology-manager/overview/).
	Parameters	`agentRid, sessionRid, objectTypeRids`
`FunctionLocatorNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	The specified function locator is configured for use by the Agent but could not be found. The function type or version may not exist or the client token does not have access.
	Parameters	`agentRid, sessionRid, functionRid, functionVersion`
`CreateSessionPermissionDenied`	Error Code	`PERMISSION_DENIED`
	Status Code	403
	Description	Could not create the Session.
	Parameters	`agentRid`

See Errors for a general overview of errors in the platform.