You can call Atlas AI agents from the Cognite Python SDK or the Agents REST API to embed agents in your applications, automate workflows, and build custom user interfaces.
The Agents REST API is in beta release status. Python SDK coverage may lag the API and is subject to change.
Prerequisites
-
A deployed Atlas AI agent. See Building agents.
-
The
agents:run and agents:read capabilities.
-
Python SDK version 7.80.3 or later:
pip install "cognite-sdk>=7.80.3"
Chatting with an agent
Send a message to an agent and read the response:
from cognite.client import CogniteClient
from cognite.client.data_classes.agents import Message
client = CogniteClient()
response = client.agents.chat(
agent_external_id="my_agent",
messages=Message("What can you tell me about compressor C-101?"),
)
print(response.text)
curl -X POST "https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/agents/chat" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"agentExternalId": "my_agent",
"messages": [
{
"role": "user",
"content": { "type": "text", "text": "What can you tell me about compressor C-101?" }
}
]
}'
Continuing a conversation
Use the cursor from the previous response to continue the same conversation. You do not need to resend previous messages; the cursor maintains conversation state:
follow_up = client.agents.chat(
agent_external_id="my_agent",
messages=Message("What are the related time series?"),
cursor=response.cursor,
)
print(follow_up.text)
{
"agentExternalId": "my_agent",
"cursor": "<cursor from previous response>",
"messages": [
{
"role": "user",
"content": { "type": "text", "text": "What are the related time series?" }
}
]
}
toolConfirmation action in the response. Your application must respond with ALLOW to proceed or DENY to cancel. In the Python SDK, response.action_calls is None when the response contains no actions, so check for it before you iterate over it.
The confirmation flow
Send a message that triggers a confirmation-required tool
Your message causes the agent to run an integration tool.
Receive a toolConfirmation action in the response
The response contains an action with type: "toolConfirmation" instead of
the final result. It includes the tool name, arguments, and a human-readable
description of what the tool will do.
Inspect and decide: ALLOW or DENY
Your application reviews the tool call details and sends back ALLOW to
execute it or DENY to cancel it.
Receive the final response
The agent executes (or skips) the tool and returns the final result.
Example
from cognite.client import CogniteClient
from cognite.client.data_classes.agents import Message, ToolConfirmationCall, ToolConfirmationResult
client = CogniteClient()
# Step 1: Send the initial message
response = client.agents.chat(
agent_external_id="my_agent",
messages=Message("Run the data quality check function"),
)
# Step 2: Check for tool confirmation requests
if response.action_calls:
confirmations = []
for action in response.action_calls:
if isinstance(action, ToolConfirmationCall):
print(f"Agent wants to run: {action.tool_name}")
print(f"Tool type: {action.tool_type}")
print(f"Arguments: {action.tool_arguments}")
print(f"Description: {action.tool_description}")
confirmations.append(
ToolConfirmationResult(
action_id=action.action_id,
status="ALLOW", # or "DENY" to cancel
)
)
# Step 3: Send ALLOW or DENY
if confirmations:
response = client.agents.chat(
agent_external_id="my_agent",
messages=confirmations,
cursor=response.cursor,
)
# Step 4: Print the final result
print(response.text)
Step 1: Initial request{
"agentExternalId": "my_agent",
"messages": [
{
"role": "user",
"content": { "type": "text", "text": "Run the data quality check function" }
}
]
}
{
"agentExternalId": "my_agent",
"response": {
"type": "result",
"cursor": "<cursor>",
"messages": [
{
"role": "agent",
"content": { "type": "text", "text": "" },
"actions": [
{
"actionId": "id_22c74316-1014-47e8-ae2b-ed0767c6c471",
"type": "toolConfirmation",
"toolConfirmation": {
"content": { "type": "text", "text": "Please confirm the action." },
"toolName": "Data quality check",
"toolType": "callFunction",
"toolArguments": {},
"toolDescription": "This tool calls a Cognite Function."
}
}
]
}
]
}
}
{
"agentExternalId": "my_agent",
"cursor": "<cursor from above>",
"messages": [
{
"role": "action",
"type": "toolConfirmation",
"actionId": "id_22c74316-1014-47e8-ae2b-ed0767c6c471",
"status": "ALLOW"
}
]
}
Include the cursor from the confirmation response in your ALLOW or DENY request so the agent continues the same conversation.
