curl --request POST \
--url https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat \
--header 'Authorization: Bearer <token>' \
--header 'content-type: <content-type>' \
--data '
{
"messages": [
{
"actionId": "<string>",
"content": {
"type": "<string>",
"text": "<string>"
},
"role": "<string>",
"type": "<string>",
"data": []
}
],
"actions": [
{
"clientTool": {
"name": "<string>",
"parameters": {
"type": "<string>",
"description": "<string>",
"properties": {},
"propertyOrdering": [
"<string>"
],
"required": [
"<string>"
]
},
"description": "<string>"
},
"type": "<string>"
}
],
"agentExternalId": "<string>",
"agentId": "<string>",
"cursor": "<string>",
"stream": false
}
'{
"agentExternalId": "<string>",
"agentId": "<string>",
"response": {
"messages": [
{
"content": {
"type": "<string>",
"text": "<string>"
},
"role": "<string>",
"actions": [
{
"actionId": "<string>",
"clientTool": {
"name": "<string>",
"arguments": "<string>"
},
"type": "<string>"
}
],
"data": [
{
"instanceId": {
"externalId": "<string>",
"space": "<string>"
},
"view": {
"externalId": "<string>",
"space": "<string>",
"version": "<string>"
},
"properties": {},
"type": "instance"
}
],
"reasoning": [
{
"content": [
{
"type": "<string>",
"text": "<string>"
}
]
}
]
}
],
"cursor": "<string>",
"type": "result"
}
}Start a chat session with an agent
Begin a chat session with an agent.
You can use the cursor field to continue a multi-turn conversation:
- Start a new conversation by omitting
cursor. - Continue a conversation by passing the
cursorfrom the previous response.
When a cursor is provided, there is no need to include previous message history in the messages field.
Tool confirmation flow
Integration tools — Call Function, Run Python code, and Call REST API — require explicit user confirmation before execution. When the agent wants to run one of these tools, the response includes a toolConfirmation action instead of the final result.
To continue, send a follow-up request with the same cursor and a message of type toolConfirmation in the messages array:
{
"agentExternalId": "my_agent",
"cursor": "<cursor from previous response>",
"messages": [
{
"role": "action",
"type": "toolConfirmation",
"actionId": "<actionId from the toolConfirmation action>",
"status": "ALLOW"
}
]
}
Set status to "ALLOW" to let the agent execute the tool, or "DENY" to cancel it.
curl --request POST \
--url https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat \
--header 'Authorization: Bearer <token>' \
--header 'content-type: <content-type>' \
--data '
{
"messages": [
{
"actionId": "<string>",
"content": {
"type": "<string>",
"text": "<string>"
},
"role": "<string>",
"type": "<string>",
"data": []
}
],
"actions": [
{
"clientTool": {
"name": "<string>",
"parameters": {
"type": "<string>",
"description": "<string>",
"properties": {},
"propertyOrdering": [
"<string>"
],
"required": [
"<string>"
]
},
"description": "<string>"
},
"type": "<string>"
}
],
"agentExternalId": "<string>",
"agentId": "<string>",
"cursor": "<string>",
"stream": false
}
'{
"agentExternalId": "<string>",
"agentId": "<string>",
"response": {
"messages": [
{
"content": {
"type": "<string>",
"text": "<string>"
},
"role": "<string>",
"actions": [
{
"actionId": "<string>",
"clientTool": {
"name": "<string>",
"arguments": "<string>"
},
"type": "<string>"
}
],
"data": [
{
"instanceId": {
"externalId": "<string>",
"space": "<string>"
},
"view": {
"externalId": "<string>",
"space": "<string>",
"version": "<string>"
},
"properties": {},
"type": "instance"
}
],
"reasoning": [
{
"content": [
{
"type": "<string>",
"text": "<string>"
}
]
}
]
}
],
"cursor": "<string>",
"type": "result"
}
}Authorizations
Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
Headers
Body
A list of one or multiple input items for the agent, which include various content types used to generate a response.
1 - 1000 elements- ClientToolCallActionMessage
- UserConfirmationResponseDTO
- UserSessionResponseDTO
- AgentChatMessageUserRequest
Show child attributes
Show child attributes
Custom tool calls that a client can inject.
15Show child attributes
Show child attributes
An external ID that uniquely identifies the agent.
^[^\x00]{1,128}$Deprecated: Use AgentExternalId instead. This field uniquely identifies the agent, but is deprecated and will be removed in a future release. If both AgentId and AgentExternalId are provided, AgentExternalId takes precedence.
^[^\x00]{1,128}$The cursor for continuing a multi-turn conversation. Omit this field to start a new conversation. To continue a conversation, pass the cursor value returned in the previous response. When cursor is provided, you do not need to resend earlier conversation history.
Enable progress message streaming.
Response
Successful Response
An external ID that uniquely identifies the agent.
^[^\x00]{1,128}$Deprecated: Use AgentExternalId instead. This field uniquely identifies the agent, but is deprecated and will be removed in a future release. If both AgentId and AgentExternalId are provided, AgentExternalId takes precedence.
^[^\x00]{1,128}$Show child attributes
Show child attributes
Was this page helpful?