New: build custom CDF applications with Cognite Flows. Documentation · What's new.
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>",
"retentionPolicy": "temporary",
"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>"
}
],
"data": [
{
"type": "<string>",
"toolCall": {
"id": "<string>",
"input": {},
"name": "<string>",
"result": {},
"toolType": "analyzeData"
}
}
]
}
]
}
],
"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.
Streaming
Set stream to true in the request to receive Server-Sent Events (SSE) as the agent works. Each event is an AgentSessionResponse whose response.type discriminator indicates the kind of event:
progress— status updates while the agent is working (e.g. “Searching knowledge graph…”). Useful for showing a spinner or activity indicator.responseChunk— incremental content fragments of the agent’s reply. Concatenate these to build the full response as it streams in.result— the final complete response, including messages, cursor, and any actions. Always the last event in the stream.
When stream is false (the default), only a single result response is returned.
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>",
"retentionPolicy": "temporary",
"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>"
}
],
"data": [
{
"type": "<string>",
"toolCall": {
"id": "<string>",
"input": {},
"name": "<string>",
"result": {},
"toolType": "analyzeData"
}
}
]
}
]
}
],
"cursor": "<string>",
"type": "result"
}
}Documentation Index
Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
Use this file to discover all available pages before exploring further.
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.
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.
temporary, persisted 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}$- AgentSessionResultResponse
- AgentSessionProgressResponse
- AgentSessionChunkResponse
Show child attributes
Show child attributes
Was this page helpful?