> ## 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.

# Using Atlas AI agents via API and SDK

> Use the Cognite Python SDK or REST API to chat with Atlas AI agents, continue conversations with a cursor, and approve or deny tool confirmations for integration tools.

You can call Atlas AI agents from the [Cognite Python SDK](https://cognite-sdk-python.readthedocs-hosted.com/en/latest/agents.html) or the [Agents REST API](/api-reference/concepts/20230101-beta/ai-agents) to embed agents in your applications, automate workflows, and build custom user interfaces.

<Warning>
  The Agents REST API is in *beta* release status. Python SDK coverage may lag the API and is subject to change.
</Warning>

## Prerequisites

* A deployed Atlas AI agent. See [Building agents](/cdf/atlas_ai/guides/atlas_ai_agent_building).
* The `agents:run` and `agents:read` [capabilities](/cdf/access/guides/capabilities).
* Python SDK version 7.80.3 or later:

  ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  pip install "cognite-sdk>=7.80.3"
  ```

## Chatting with an agent

Send a message to an agent and read the response:

<Tabs>
  <Tab title="Python SDK">
    ```python theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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)
    ```
  </Tab>

  <Tab title="REST API">
    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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?" }
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

## 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:

<Tabs>
  <Tab title="Python SDK">
    ```python theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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)
    ```
  </Tab>

  <Tab title="REST API">
    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "agentExternalId": "my_agent",
      "cursor": "<cursor from previous response>",
      "messages": [
        {
          "role": "user",
          "content": { "type": "text", "text": "What are the related time series?" }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Handling tool confirmation

When an agent uses an integration tool ([Call Function](/cdf/atlas_ai/references/atlas_ai_call_function_tool), [Run Python code](/cdf/atlas_ai/references/atlas_ai_agent_python_tool), 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

<Steps>
  <Step title="Send a message that triggers a confirmation-required tool">
    Your message causes the agent to run an integration tool.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Receive the final response">
    The agent executes (or skips) the tool and returns the final result.
  </Step>
</Steps>

### Example

<Tabs>
  <Tab title="Python SDK">
    ```python theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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)
    ```
  </Tab>

  <Tab title="REST API">
    **Step 1: Initial request**

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "agentExternalId": "my_agent",
      "messages": [
        {
          "role": "user",
          "content": { "type": "text", "text": "Run the data quality check function" }
        }
      ]
    }
    ```

    **Step 2: Response with confirmation request**

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "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**

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "agentExternalId": "my_agent",
      "cursor": "<cursor from above>",
      "messages": [
        {
          "role": "action",
          "type": "toolConfirmation",
          "actionId": "id_22c74316-1014-47e8-ae2b-ed0767c6c471",
          "status": "ALLOW"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  Include the `cursor` from the confirmation response in your ALLOW or DENY request so the agent continues the same conversation.
</Info>

## Related information

* [Call Function tool reference](/cdf/atlas_ai/references/atlas_ai_call_function_tool)
* [Run Python code tool reference](/cdf/atlas_ai/references/atlas_ai_agent_python_tool)
* [Building agents](/cdf/atlas_ai/guides/atlas_ai_agent_building)
* [Agents API reference](/api-reference/concepts/20230101-beta/ai-agents)
* [Python SDK: Agents](https://cognite-sdk-python.readthedocs-hosted.com/en/latest/agents.html)