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.
stringAn RID identifying an AIP Agent created in AIP Agent Studio.
objectstringThe 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.
objectThe created Session
stringThe Resource Identifier (RID) of the conversation session.
objectMetadata about the session.
stringThe Resource Identifier (RID) of the Agent associated with the session.
stringThe 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.
1
2
3
4
5
curl -X POST \
\t-H "Content-type: application/json" \
\t-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"}'1
2
3
4
5
6
7
8
9
10
11
12
{
"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 Name | ||
|---|---|---|
No | 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 | |
Object | 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 | |
Object | 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 | |
Function | 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 | |
Invalid | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The provided version string is not a valid format for an Agent version. | |
| Parameters | agentRid, version | |
Ontology | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | Some ontology types are configured for use by the Agent but could not be found. The types either do not exist or the client token does not have access. Object types and their link types can be checked by listing available object/link types through the API, or searching in [Ontology Manager](/docs/foundry/ontology-manager/overview/). | |
| Parameters | agentRid, sessionRid, objectTypeRids, linkTypeRids | |
Create | Error Code | PERMISSION_DENIED |
| Status Code | 403 | |
| Description | Could not create the Session. | |
| Parameters | agentRid | |
Agent | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The given Agent could not be found. | |
| Parameters | agentRid | |
Agent | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The given AgentVersion could not be found. | |
| Parameters | agentRid, agentVersionString | |
Session | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The given Session could not be found. | |
| Parameters | agentRid, sessionRid | |
See Errors for a general overview of errors in the platform.