Using Atlas AI agents via API and SDK

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:

Python SDK
REST API

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:

Python SDK
REST API

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?" }
    }
  ]
}

Handling tool confirmation

When an agent uses an integration tool (Call Function, Run Python code, or Call REST API), the response may include a tool confirmation request before the tool runs. This prevents the agent from performing destructive or unintended actions without your approval. The confirmation appears as a 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

Python SDK
REST API

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" }
    }
  ]
}

Step 2: Response with confirmation request

{
  "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."
            }
          }
        ]
      }
    ]
  }
}

Step 3: Send ALLOW or DENY

{
  "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.

​Prerequisites

​Chatting with an agent

​Continuing a conversation

​Handling tool confirmation

​The confirmation flow

​Example

​Related information

Prerequisites

Chatting with an agent

Continuing a conversation

Handling tool confirmation

The confirmation flow

Example

Related information