Chat with an agent by external id

Chat with an agent.

Given a user query, the Atlas AI agent responds by reasoning and using the tools associated with it. Users can ensure conversation continuity by including the cursor from the previous response in subsequent requests.

Parameters:

agent_external_id (str) – External ID that uniquely identifies the agent.
messages (Message | ActionResult | Sequence[Message | ActionResult]) – A list of one or many input messages to the agent. Can include regular messages and action results.
cursor (str | None) – The cursor to use for continuation of a conversation. Use this to create multi-turn conversations, as the cursor will keep track of the conversation state.
actions (Sequence[Action] | None) – A list of client-side actions that can be called by the agent.

Returns:

The response from the agent.

Return type:

AgentChatResponse

Examples

Start a simple chat with an agent:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.agents import Message
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> response = client.agents.chat(
...     agent_external_id="my_agent", messages=Message("What can you help me with?")
... )
>>> print(response.text)

Continue a conversation using the cursor:

>>> follow_up = client.agents.chat(
...     agent_external_id="my_agent",
...     messages=Message("Tell me more about that"),
...     cursor=response.cursor,
... )

Send multiple messages at once:

>>> response = client.agents.chat(
...     agent_external_id="my_agent",
...     messages=[
...         Message("Help me find the 1st stage compressor."),
...         Message("Once you have found it, find related time series."),
...     ],
... )

Chat with client-side actions:

>>> from cognite.client.data_classes.agents import ClientToolAction, ClientToolResult
>>> add_numbers_action = ClientToolAction(
...     name="add",
...     description="Add two numbers together",
...     parameters={
...         "type": "object",
...         "properties": {
...             "a": {"type": "number", "description": "First number"},
...             "b": {"type": "number", "description": "Second number"},
...         },
...         "required": ["a", "b"],
...     },
... )
>>> response = client.agents.chat(
...     agent_external_id="my_agent",
...     messages=Message("What is 42 plus 58?"),
...     actions=[add_numbers_action],
... )
>>> if response.action_calls:
...     for call in response.action_calls:
...         # Execute the action
...         result = call.arguments["a"] + call.arguments["b"]
...         # Send result back
...         response = client.agents.chat(
...             agent_external_id="my_agent",
...             messages=ClientToolResult(
...                 action_id=call.action_id, content=f"The result is {result}"
...             ),
...             cursor=response.cursor,
...             actions=[add_numbers_action],
...         )

Handle tool confirmation for integration tools (Call Function, Run Python code, Call REST API):

>>> from cognite.client.data_classes.agents import (
...     ToolConfirmationCall,
...     ToolConfirmationResult,
... )
>>> response = client.agents.chat(
...     agent_external_id="my_agent",
...     messages=Message("Run the data quality check function"),
... )
>>> if response.action_calls:
...     confirmations = []
...     for action in response.action_calls:
...         if isinstance(action, ToolConfirmationCall):
...             # Inspect each tool call before deciding
...             print(f"Tool: {action.tool_name}, type: {action.tool_type}")
...             print(f"Arguments: {action.tool_arguments}")
...             confirmations.append(
...                 ToolConfirmationResult(
...                     action_id=action.action_id,
...                     status="ALLOW",  # or "DENY" to cancel
...                 )
...             )
...     if confirmations:
...         response = client.agents.chat(
...             agent_external_id="my_agent",
...             messages=confirmations,
...             cursor=response.cursor,
...         )