Start a chat session with an agent
Starts or continues an agent chat. Pass cursor to continue. Confirm tools before they run. See Chat turns.
POST
/
ai
/
agents
/
chat
Start a chat session with an agent
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": "text",
"text": "<string>"
},
"role": "action",
"type": "clientTool",
"data": []
}
],
"actions": [
{
"clientTool": {
"name": "<string>",
"parameters": {
"type": "object",
"description": "<string>",
"properties": {},
"propertyOrdering": [
"<string>"
],
"required": [
"<string>"
]
},
"description": "<string>"
},
"type": "clientTool"
}
],
"agentExternalId": "<string>",
"agentId": "<string>",
"cursor": "<string>",
"stream": false,
"streamOptions": {
"returnCursor": false
},
"toolConfirmationMode": "default"
}
'import requests
url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat"
payload = {
"messages": [
{
"actionId": "<string>",
"content": {
"type": "text",
"text": "<string>"
},
"role": "action",
"type": "clientTool",
"data": []
}
],
"actions": [
{
"clientTool": {
"name": "<string>",
"parameters": {
"type": "object",
"description": "<string>",
"properties": {},
"propertyOrdering": ["<string>"],
"required": ["<string>"]
},
"description": "<string>"
},
"type": "clientTool"
}
],
"agentExternalId": "<string>",
"agentId": "<string>",
"cursor": "<string>",
"stream": False,
"streamOptions": { "returnCursor": False },
"toolConfirmationMode": "default"
}
headers = {
"content-type": "<content-type>",
"Authorization": "Bearer <token>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'content-type': '<content-type>', Authorization: 'Bearer <token>'},
body: JSON.stringify({
messages: [
{
actionId: '<string>',
content: {type: 'text', text: '<string>'},
role: 'action',
type: 'clientTool',
data: []
}
],
actions: [
{
clientTool: {
name: '<string>',
parameters: {
type: 'object',
description: '<string>',
properties: {},
propertyOrdering: ['<string>'],
required: ['<string>']
},
description: '<string>'
},
type: 'clientTool'
}
],
agentExternalId: '<string>',
agentId: '<string>',
cursor: '<string>',
stream: false,
streamOptions: {returnCursor: false},
toolConfirmationMode: 'default'
})
};
fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'messages' => [
[
'actionId' => '<string>',
'content' => [
'type' => 'text',
'text' => '<string>'
],
'role' => 'action',
'type' => 'clientTool',
'data' => [
]
]
],
'actions' => [
[
'clientTool' => [
'name' => '<string>',
'parameters' => [
'type' => 'object',
'description' => '<string>',
'properties' => [
],
'propertyOrdering' => [
'<string>'
],
'required' => [
'<string>'
]
],
'description' => '<string>'
],
'type' => 'clientTool'
]
],
'agentExternalId' => '<string>',
'agentId' => '<string>',
'cursor' => '<string>',
'stream' => false,
'streamOptions' => [
'returnCursor' => false
],
'toolConfirmationMode' => 'default'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"content-type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat"
payload := strings.NewReader("{\n \"messages\": [\n {\n \"actionId\": \"<string>\",\n \"content\": {\n \"type\": \"text\",\n \"text\": \"<string>\"\n },\n \"role\": \"action\",\n \"type\": \"clientTool\",\n \"data\": []\n }\n ],\n \"actions\": [\n {\n \"clientTool\": {\n \"name\": \"<string>\",\n \"parameters\": {\n \"type\": \"object\",\n \"description\": \"<string>\",\n \"properties\": {},\n \"propertyOrdering\": [\n \"<string>\"\n ],\n \"required\": [\n \"<string>\"\n ]\n },\n \"description\": \"<string>\"\n },\n \"type\": \"clientTool\"\n }\n ],\n \"agentExternalId\": \"<string>\",\n \"agentId\": \"<string>\",\n \"cursor\": \"<string>\",\n \"stream\": false,\n \"streamOptions\": {\n \"returnCursor\": false\n },\n \"toolConfirmationMode\": \"default\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "<content-type>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat")
.header("content-type", "<content-type>")
.header("Authorization", "Bearer <token>")
.body("{\n \"messages\": [\n {\n \"actionId\": \"<string>\",\n \"content\": {\n \"type\": \"text\",\n \"text\": \"<string>\"\n },\n \"role\": \"action\",\n \"type\": \"clientTool\",\n \"data\": []\n }\n ],\n \"actions\": [\n {\n \"clientTool\": {\n \"name\": \"<string>\",\n \"parameters\": {\n \"type\": \"object\",\n \"description\": \"<string>\",\n \"properties\": {},\n \"propertyOrdering\": [\n \"<string>\"\n ],\n \"required\": [\n \"<string>\"\n ]\n },\n \"description\": \"<string>\"\n },\n \"type\": \"clientTool\"\n }\n ],\n \"agentExternalId\": \"<string>\",\n \"agentId\": \"<string>\",\n \"cursor\": \"<string>\",\n \"stream\": false,\n \"streamOptions\": {\n \"returnCursor\": false\n },\n \"toolConfirmationMode\": \"default\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["content-type"] = '<content-type>'
request["Authorization"] = 'Bearer <token>'
request.body = "{\n \"messages\": [\n {\n \"actionId\": \"<string>\",\n \"content\": {\n \"type\": \"text\",\n \"text\": \"<string>\"\n },\n \"role\": \"action\",\n \"type\": \"clientTool\",\n \"data\": []\n }\n ],\n \"actions\": [\n {\n \"clientTool\": {\n \"name\": \"<string>\",\n \"parameters\": {\n \"type\": \"object\",\n \"description\": \"<string>\",\n \"properties\": {},\n \"propertyOrdering\": [\n \"<string>\"\n ],\n \"required\": [\n \"<string>\"\n ]\n },\n \"description\": \"<string>\"\n },\n \"type\": \"clientTool\"\n }\n ],\n \"agentExternalId\": \"<string>\",\n \"agentId\": \"<string>\",\n \"cursor\": \"<string>\",\n \"stream\": false,\n \"streamOptions\": {\n \"returnCursor\": false\n },\n \"toolConfirmationMode\": \"default\"\n}"
response = http.request(request)
puts response.read_body{
"agentExternalId": "<string>",
"agentId": "<string>",
"response": {
"messages": [
{
"content": {
"type": "text",
"text": "<string>"
},
"role": "agent",
"actions": [
{
"actionId": "<string>",
"clientTool": {
"name": "<string>",
"arguments": "<string>"
},
"type": "clientTool",
"caller": {
"id": "<string>",
"name": "<string>"
}
}
],
"data": [
{
"instanceId": {
"externalId": "<string>",
"space": "<string>"
},
"view": {
"externalId": "<string>",
"space": "<string>",
"version": "<string>"
},
"properties": {},
"type": "instance"
}
],
"reasoning": [
{
"content": [
{
"type": "text",
"text": "<string>"
}
],
"data": [
{
"type": "toolCall",
"toolCall": {
"id": "<string>",
"input": {},
"name": "<string>",
"result": {},
"toolType": "analyzeData"
}
}
]
}
]
}
],
"cursor": "<string>",
"type": "result"
}
}{
"error": {
"code": 401,
"message": "Could not authenticate.",
"missing": [
{}
],
"duplicated": [
{}
]
}
}Authorizations
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
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.
Scopes
Headers
Body
application/json
messages
(ClientToolCallActionMessage · object | UserConfirmationResponseDTO · object | UserSessionResponseDTO · object | AgentChatMessageUserRequest · object)[]
required
A list of one or multiple input items for the agent, which include various content types used to generate a response.
Required array length:
1 - 1000 elements- ClientToolCallActionMessage
- UserConfirmationResponseDTO
- UserSessionResponseDTO
- AgentChatMessageUserRequest
Show child attributes
Show child attributes
Custom tool calls that a client can inject.
Maximum array length:
20Show child attributes
Show child attributes
An external ID that uniquely identifies the agent.
Pattern:
^[^\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.
Pattern:
^[^\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.
Retention class for the conversation. "persisted" retains the conversation until explicitly deleted. "temporary" (default) can result in the conversation being deleted at any time. This value is only honored when starting a conversation, ignored otherwise.
Available options:
temporary, persisted Enable progress message streaming.
Options that shape the streaming response. Only applies when stream is true.
Show child attributes
Show child attributes
Controls whether tools requiring user confirmation prompt for approval. Set to "default" to enforce standard confirmation requirements, or "dangerouslyAllowAll" to bypass approval for tools executed during this request. This setting is not persisted across turns and must be resent with each request. It propagates to subagents.
Available options:
default, dangerouslyAllowAll Response
Successful Response
An external ID that uniquely identifies the agent.
Pattern:
^[^\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.
Pattern:
^[^\x00]{1,128}$- AgentSessionResultResponse
- AgentSessionProgressResponse
- AgentSessionChunkResponse
- AgentSessionCursorResponse
Show child attributes
Show child attributes
⌘I
Start a chat session with an agent
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": "text",
"text": "<string>"
},
"role": "action",
"type": "clientTool",
"data": []
}
],
"actions": [
{
"clientTool": {
"name": "<string>",
"parameters": {
"type": "object",
"description": "<string>",
"properties": {},
"propertyOrdering": [
"<string>"
],
"required": [
"<string>"
]
},
"description": "<string>"
},
"type": "clientTool"
}
],
"agentExternalId": "<string>",
"agentId": "<string>",
"cursor": "<string>",
"stream": false,
"streamOptions": {
"returnCursor": false
},
"toolConfirmationMode": "default"
}
'import requests
url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat"
payload = {
"messages": [
{
"actionId": "<string>",
"content": {
"type": "text",
"text": "<string>"
},
"role": "action",
"type": "clientTool",
"data": []
}
],
"actions": [
{
"clientTool": {
"name": "<string>",
"parameters": {
"type": "object",
"description": "<string>",
"properties": {},
"propertyOrdering": ["<string>"],
"required": ["<string>"]
},
"description": "<string>"
},
"type": "clientTool"
}
],
"agentExternalId": "<string>",
"agentId": "<string>",
"cursor": "<string>",
"stream": False,
"streamOptions": { "returnCursor": False },
"toolConfirmationMode": "default"
}
headers = {
"content-type": "<content-type>",
"Authorization": "Bearer <token>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'content-type': '<content-type>', Authorization: 'Bearer <token>'},
body: JSON.stringify({
messages: [
{
actionId: '<string>',
content: {type: 'text', text: '<string>'},
role: 'action',
type: 'clientTool',
data: []
}
],
actions: [
{
clientTool: {
name: '<string>',
parameters: {
type: 'object',
description: '<string>',
properties: {},
propertyOrdering: ['<string>'],
required: ['<string>']
},
description: '<string>'
},
type: 'clientTool'
}
],
agentExternalId: '<string>',
agentId: '<string>',
cursor: '<string>',
stream: false,
streamOptions: {returnCursor: false},
toolConfirmationMode: 'default'
})
};
fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'messages' => [
[
'actionId' => '<string>',
'content' => [
'type' => 'text',
'text' => '<string>'
],
'role' => 'action',
'type' => 'clientTool',
'data' => [
]
]
],
'actions' => [
[
'clientTool' => [
'name' => '<string>',
'parameters' => [
'type' => 'object',
'description' => '<string>',
'properties' => [
],
'propertyOrdering' => [
'<string>'
],
'required' => [
'<string>'
]
],
'description' => '<string>'
],
'type' => 'clientTool'
]
],
'agentExternalId' => '<string>',
'agentId' => '<string>',
'cursor' => '<string>',
'stream' => false,
'streamOptions' => [
'returnCursor' => false
],
'toolConfirmationMode' => 'default'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"content-type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat"
payload := strings.NewReader("{\n \"messages\": [\n {\n \"actionId\": \"<string>\",\n \"content\": {\n \"type\": \"text\",\n \"text\": \"<string>\"\n },\n \"role\": \"action\",\n \"type\": \"clientTool\",\n \"data\": []\n }\n ],\n \"actions\": [\n {\n \"clientTool\": {\n \"name\": \"<string>\",\n \"parameters\": {\n \"type\": \"object\",\n \"description\": \"<string>\",\n \"properties\": {},\n \"propertyOrdering\": [\n \"<string>\"\n ],\n \"required\": [\n \"<string>\"\n ]\n },\n \"description\": \"<string>\"\n },\n \"type\": \"clientTool\"\n }\n ],\n \"agentExternalId\": \"<string>\",\n \"agentId\": \"<string>\",\n \"cursor\": \"<string>\",\n \"stream\": false,\n \"streamOptions\": {\n \"returnCursor\": false\n },\n \"toolConfirmationMode\": \"default\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "<content-type>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat")
.header("content-type", "<content-type>")
.header("Authorization", "Bearer <token>")
.body("{\n \"messages\": [\n {\n \"actionId\": \"<string>\",\n \"content\": {\n \"type\": \"text\",\n \"text\": \"<string>\"\n },\n \"role\": \"action\",\n \"type\": \"clientTool\",\n \"data\": []\n }\n ],\n \"actions\": [\n {\n \"clientTool\": {\n \"name\": \"<string>\",\n \"parameters\": {\n \"type\": \"object\",\n \"description\": \"<string>\",\n \"properties\": {},\n \"propertyOrdering\": [\n \"<string>\"\n ],\n \"required\": [\n \"<string>\"\n ]\n },\n \"description\": \"<string>\"\n },\n \"type\": \"clientTool\"\n }\n ],\n \"agentExternalId\": \"<string>\",\n \"agentId\": \"<string>\",\n \"cursor\": \"<string>\",\n \"stream\": false,\n \"streamOptions\": {\n \"returnCursor\": false\n },\n \"toolConfirmationMode\": \"default\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["content-type"] = '<content-type>'
request["Authorization"] = 'Bearer <token>'
request.body = "{\n \"messages\": [\n {\n \"actionId\": \"<string>\",\n \"content\": {\n \"type\": \"text\",\n \"text\": \"<string>\"\n },\n \"role\": \"action\",\n \"type\": \"clientTool\",\n \"data\": []\n }\n ],\n \"actions\": [\n {\n \"clientTool\": {\n \"name\": \"<string>\",\n \"parameters\": {\n \"type\": \"object\",\n \"description\": \"<string>\",\n \"properties\": {},\n \"propertyOrdering\": [\n \"<string>\"\n ],\n \"required\": [\n \"<string>\"\n ]\n },\n \"description\": \"<string>\"\n },\n \"type\": \"clientTool\"\n }\n ],\n \"agentExternalId\": \"<string>\",\n \"agentId\": \"<string>\",\n \"cursor\": \"<string>\",\n \"stream\": false,\n \"streamOptions\": {\n \"returnCursor\": false\n },\n \"toolConfirmationMode\": \"default\"\n}"
response = http.request(request)
puts response.read_body{
"agentExternalId": "<string>",
"agentId": "<string>",
"response": {
"messages": [
{
"content": {
"type": "text",
"text": "<string>"
},
"role": "agent",
"actions": [
{
"actionId": "<string>",
"clientTool": {
"name": "<string>",
"arguments": "<string>"
},
"type": "clientTool",
"caller": {
"id": "<string>",
"name": "<string>"
}
}
],
"data": [
{
"instanceId": {
"externalId": "<string>",
"space": "<string>"
},
"view": {
"externalId": "<string>",
"space": "<string>",
"version": "<string>"
},
"properties": {},
"type": "instance"
}
],
"reasoning": [
{
"content": [
{
"type": "text",
"text": "<string>"
}
],
"data": [
{
"type": "toolCall",
"toolCall": {
"id": "<string>",
"input": {},
"name": "<string>",
"result": {},
"toolType": "analyzeData"
}
}
]
}
]
}
],
"cursor": "<string>",
"type": "result"
}
}{
"error": {
"code": 401,
"message": "Could not authenticate.",
"missing": [
{}
],
"duplicated": [
{}
]
}
}