Agents

Create or update an agent

AgentsAPI.upsert(agents: AgentUpsert) → Agent

AgentsAPI.upsert(agents: Sequence[AgentUpsert]) → AgentList

Create or update (upsert) one or more agents.

Parameters: agents (AgentUpsert | Sequence[AgentUpsert]) – Agent or list of agents to create or update.
Returns: The created or updated agent(s).
Return type: Agent | AgentList

Examples

Create a new agent with a query knowledge graph tool to find assets:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.agents import (
...     AgentUpsert,
...     QueryKnowledgeGraphAgentToolUpsert,
...     QueryKnowledgeGraphAgentToolConfiguration,
...     DataModelInfo
... )
>>> client = CogniteClient()
...
>>> find_assets_tool = QueryKnowledgeGraphAgentToolUpsert(
...     name="find assets",
...     description="Use this tool to find assets",
...     configuration=QueryKnowledgeGraphAgentToolConfiguration(
...         data_models=[
...             DataModelInfo(
...                 space="cdf_idm",
...                 external_id="CogniteProcessIndustries",
...                 version="v1",
...                 view_external_ids=["CogniteAsset"],
...             )
...         ]
...     )
... )
>>> agent = AgentUpsert(
...     external_id="my_agent",
...     name="My Agent",
...     tools=[find_assets_tool]
... )
>>> client.agents.upsert(agents=[agent])

Create an agent with multiple different tools:

>>> from cognite.client.data_classes.agents import (
...     AgentUpsert,
...     QueryKnowledgeGraphAgentToolUpsert,
...     QueryKnowledgeGraphAgentToolConfiguration,
...     DataModelInfo,
...     SummarizeDocumentAgentToolUpsert,
...     AskDocumentAgentToolUpsert,
...     QueryTimeSeriesDatapointsAgentToolUpsert
... )
...
>>> find_assets_tool = QueryKnowledgeGraphAgentToolUpsert(
...     name="find assets",
...     description="Use this tool to query the knowledge graph for assets",
...     configuration=QueryKnowledgeGraphAgentToolConfiguration(
...         data_models=[
...             DataModelInfo(
...                 space="cdf_idm",
...                 external_id="CogniteProcessIndustries",
...                 version="v1",
...                 view_external_ids=["CogniteAsset"],
...             )
...         ]
...     )
... )
>>> find_files_tool = QueryKnowledgeGraphAgentToolUpsert(
...     name="find files",
...     description="Use this tool to query the knowledge graph for files",
...     configuration=QueryKnowledgeGraphAgentToolConfiguration(
...         data_models=[
...             DataModelInfo(
...                 space="cdf_idm",
...                 external_id="CogniteProcessIndustries",
...                 version="v1",
...                 view_external_ids=["CogniteFile"],
...             )
...         ]
...     )
... )
>>> find_time_series_tool = QueryKnowledgeGraphAgentToolUpsert(
...     name="find time series",
...     description="Use this tool to query the knowledge graph for time series",
...     configuration=QueryKnowledgeGraphAgentToolConfiguration(
...         data_models=[
...             DataModelInfo(
...                 space="cdf_idm",
...                 external_id="CogniteProcessIndustries",
...                 version="v1",
...                 view_external_ids=["CogniteTimeSeries"],
...             )
...         ]
...     )
... )
>>> summarize_tool = SummarizeDocumentAgentToolUpsert(
...     name="summarize document",
...     description="Use this tool to get a summary of a document"
... )
>>> ask_doc_tool = AskDocumentAgentToolUpsert(
...     name="ask document",
...     description="Use this tool to ask questions about specific documents"
... )
>>> ts_tool = QueryTimeSeriesDatapointsAgentToolUpsert(
...     name="query time series",
...     description="Use this tool to query time series data points"
... )
>>> agent = AgentUpsert(
...     external_id="my_agent",
...     name="My agent",
...     description="An agent with many tools",
...     instructions="You are a helpful assistant that can query knowledge graphs, summarize documents, answer questions about documents, and query time series data points.",
...     tools=[find_assets_tool, find_files_tool, find_time_series_tool, summarize_tool, ask_doc_tool, ts_tool]
... )
>>> client.agents.upsert(agents=[agent])

Retrieve an agent by external id

AgentsAPI.retrieve(external_ids: str, ignore_unknown_ids: bool = False) → cognite.client.data_classes.agents.agents.Agent | None

AgentsAPI.retrieve(external_ids: SequenceNotStr[str], ignore_unknown_ids: bool = False) → AgentList

Retrieve one or more agents by external ID.

Parameters

external_ids (str | SequenceNotStr[str]) – The external id of the agent(s) to retrieve.
ignore_unknown_ids (bool) – Whether to ignore unknown IDs. Defaults to False.

Returns

The requested agent or agent list. None is returned if ignore_unknown_ids is True and the external ID is not found.

Return type

Agent | AgentList | None

Examples

Retrieve an agent by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.agents.retrieve(external_ids="my_agent")

Retrieve multiple agents:

>>> res = client.agents.retrieve(external_ids=["my_agent_1", "my_agent_2"])

List all agents

AgentsAPI.list() → AgentList

List agents.

Returns: The list of agents.
Return type: AgentList

Examples

List all agents:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> agent_list = client.agents.list()

Delete an agent by external id

AgentsAPI.delete(external_ids: Union[str, SequenceNotStr[str]], ignore_unknown_ids: bool = False) → None

Delete one or more agents.

Parameters

external_ids (str | SequenceNotStr[str]) – External ID of the agent or a list of external ids.
ignore_unknown_ids (bool) – If True, the call will ignore unknown external IDs. Defaults to False.

Examples

Delete an agent by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.agents.delete(external_ids="my_agent")

Chat with an agent by external id

AgentsAPI.chat(agent_id: str, messages: cognite.client.data_classes.agents.chat.Message | collections.abc.Sequence[cognite.client.data_classes.agents.chat.Message], cursor: Optional[str] = None) → AgentChatResponse

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_id (str) – External ID that uniquely identifies the agent.
messages (Message | Sequence[Message]) – A list of one or many input messages to the agent.
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.

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()
>>> response = client.agents.chat(
...     agent_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_id="my_agent",
...     messages=Message("Tell me more about that"),
...     cursor=response.cursor
... )

Send multiple messages at once:

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

Agent Data classes

class cognite.client.data_classes.agents.Agent(external_id: str, name: str, description: Optional[str] = None, instructions: Optional[str] = None, model: Optional[str] = None, tools: Optional[Sequence[AgentTool]] = None, created_time: Optional[int] = None, last_updated_time: Optional[int] = None, owner_id: Optional[str] = None)

Bases: AgentCore

Representation of an AI agent. This is the read format of an agent.

Parameters

external_id (str) – The external ID provided by the client. Must be unique for the resource type.
name (str) – The name of the agent, for use in user interfaces.
description (str | None) – The human readable description of the agent.
instructions (str | None) – Instructions for the agent.
model (str | None) – Name of the language model to use. For example, “azure/gpt-4o”, “gcp/gemini-2.0” or “aws/claude-3.5-sonnet”.
tools (Sequence[AgentTool] | None) – List of tools for the agent.
created_time (int | None) – The time the agent was created, in milliseconds since Thursday, 1 January 1970 00:00:00 UTC, minus leap seconds.
last_updated_time (int | None) – The time the agent was last updated, in milliseconds since Thursday, 1 January 1970 00:00:00 UTC, minus leap seconds.
owner_id (str | None) – The ID of the user who owns the agent.

as_write() → AgentUpsert: Returns this Agent in its writeable format

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.agents.AgentChatResponse(agent_id: str, messages: AgentMessageList, type: str, cursor: Optional[str] = None)

Bases: CogniteResource

Response from agent chat.

Parameters

agent_id (str) – The ID of the agent.
messages (AgentMessageList) – The response messages from the agent.
type (str) – The response type.
cursor (str | None) – Cursor for conversation continuation.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

property text: str | None: Get the text content from the first message with text content.

class cognite.client.data_classes.agents.AgentDataItem(type: str, data: dict[str, Any])

Bases: CogniteObject

Data item in agent response.

Parameters

type (str) – The type of data item.
data (dict[str, Any]) – The data payload.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.agents.AgentList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[AgentUpsert, Agent], ExternalIDTransformerMixin

as_write() → AgentUpsertList: Returns this AgentList as writeableinstance

class cognite.client.data_classes.agents.AgentMessage(content: Optional[MessageContent] = None, data: Optional[list[cognite.client.data_classes.agents.chat.AgentDataItem]] = None, reasoning: Optional[list[cognite.client.data_classes.agents.chat.AgentReasoningItem]] = None, role: Literal['agent'] = 'agent')

Bases: CogniteResource

A message from an agent.

Parameters

content (MessageContent | None) – The message content.
data (list[AgentDataItem] | None) – Data items in the response.
reasoning (list[AgentReasoningItem] | None) – Reasoning items in the response.
role (Literal["agent"]) – The role of the message sender.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.agents.AgentMessageList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[AgentMessage]

List of agent messages.

class cognite.client.data_classes.agents.AgentReasoningItem(content: list[cognite.client.data_classes.agents.chat.MessageContent])

Bases: CogniteObject

Reasoning item in agent response.

Parameters: content (list[MessageContent]) – The reasoning content.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.agents.AgentTool(name: str, description: str)

Bases: AgentToolCore, ABC

The read format of an agent tool.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.

abstract as_write() → AgentToolUpsert: Convert this tool to its upsert representation.

dump(camel_case: bool = True) → dict[str, Any]: Dump the instance into a json serializable Python data type.

class cognite.client.data_classes.agents.AgentToolList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[AgentToolUpsert, AgentTool]

as_write() → AgentToolUpsertList: Returns this agent tool list as a writeable instance

class cognite.client.data_classes.agents.AgentToolUpsert(name: str, description: str)

Bases: AgentToolCore, ABC

The write format of an agent tool.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.

dump(camel_case: bool = True) → dict[str, Any]: Dump the instance into a json serializable Python data type.

class cognite.client.data_classes.agents.AgentToolUpsertList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[AgentToolUpsert]

class cognite.client.data_classes.agents.AgentUpsert(external_id: str, name: str, description: Optional[str] = None, instructions: Optional[str] = None, model: Optional[str] = None, tools: Optional[Sequence[AgentToolUpsert]] = None)

Bases: AgentCore

Representation of an AI agent. This is the write format of an agent.

Parameters

external_id (str) – The external ID provided by the client. Must be unique for the resource type.
name (str) – The name of the agent, for use in user interfaces.
description (str | None) – The human readable description of the agent.
instructions (str | None) – Instructions for the agent.
model (str | None) – Name of the language model to use. For example, “azure/gpt-4o”, “gcp/gemini-2.0” or “aws/claude-3.5-sonnet”.
tools (Sequence[AgentToolUpsert] | None) – List of tools for the agent.

as_write() → AgentUpsert: Returns this AgentUpsert in its writeable format

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.agents.AgentUpsertList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[AgentUpsert], ExternalIDTransformerMixin

class cognite.client.data_classes.agents.AskDocumentAgentTool(name: str, description: str)

Bases: AgentTool

Agent tool for asking questions about documents.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.

as_write() → AskDocumentAgentToolUpsert: Convert this tool to its upsert representation.

class cognite.client.data_classes.agents.AskDocumentAgentToolUpsert(name: str, description: str)

Bases: AgentToolUpsert

Upsert version of document question agent tool.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.

class cognite.client.data_classes.agents.DataModelInfo(space: str, external_id: str, version: str, view_external_ids: Optional[Sequence[str]] = None)

Bases: WriteableCogniteResource

Information about a data model used in knowledge graph queries.

Parameters

space (str) – The space of the data model.
external_id (str) – The external ID of the data model.
version (str) – The version of the data model.
view_external_ids (Sequence[str] | None) – The external IDs of the views of the data model.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.agents.InstanceSpaces(type: Literal['manual', 'all'], spaces: Optional[Sequence[str]] = None)

Bases: WriteableCogniteResource

Configuration for instance spaces in knowledge graph queries.

Parameters

type (Literal["manual", "all"]) – The type of instance spaces.
spaces (Sequence[str] | None) – The spaces of the instance spaces.

class cognite.client.data_classes.agents.Message(content: str | cognite.client.data_classes.agents.chat.MessageContent, role: Literal['user'] = 'user')

Bases: CogniteResource

A message to send to an agent.

Parameters

content (str | MessageContent) – The message content. If a string is provided, it will be converted to TextContent.
role (Literal["user"]) – The role of the message sender. Defaults to “user”.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.agents.MessageContent

Bases: CogniteObject, ABC

Base class for message content types.

dump(camel_case: bool = True) → dict[str, Any]: Dump the content to a dictionary.

class cognite.client.data_classes.agents.MessageList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[Message]

List of messages.

class cognite.client.data_classes.agents.QueryKnowledgeGraphAgentTool(name: str, description: str, configuration: Optional[QueryKnowledgeGraphAgentToolConfiguration] = None)

Bases: AgentTool

Agent tool for querying knowledge graphs.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.
configuration (QueryKnowledgeGraphAgentToolConfiguration | None) – The configuration of the knowledge graph query agent tool.

as_write() → QueryKnowledgeGraphAgentToolUpsert: Convert this tool to its upsert representation.

dump(camel_case: bool = True) → dict[str, Any]: Dump the instance into a json serializable Python data type.

class cognite.client.data_classes.agents.QueryKnowledgeGraphAgentToolConfiguration(data_models: Optional[Sequence[DataModelInfo]] = None, instance_spaces: Optional[InstanceSpaces] = None)

Bases: WriteableCogniteResource

Configuration for knowledge graph query agent tools.

Parameters

data_models (Sequence[DataModelInfo] | None) – The data models and views to query.
instance_spaces (InstanceSpaces | None) – The instance spaces to query.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.agents.QueryKnowledgeGraphAgentToolUpsert(name: str, description: str, configuration: Optional[QueryKnowledgeGraphAgentToolConfiguration] = None)

Bases: AgentToolUpsert

Upsert version of knowledge graph query agent tool.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.
configuration (QueryKnowledgeGraphAgentToolConfiguration | None) – The configuration of the knowledge graph query agent tool.

dump(camel_case: bool = True) → dict[str, Any]: Dump the instance into a json serializable Python data type.

class cognite.client.data_classes.agents.QueryTimeSeriesDatapointsAgentTool(name: str, description: str)

Bases: AgentTool

Agent tool for querying time series datapoints.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.

as_write() → QueryTimeSeriesDatapointsAgentToolUpsert: Convert this tool to its upsert representation.

class cognite.client.data_classes.agents.QueryTimeSeriesDatapointsAgentToolUpsert(name: str, description: str)

Bases: AgentToolUpsert

Upsert version of time series datapoints query agent tool.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.

class cognite.client.data_classes.agents.SummarizeDocumentAgentTool(name: str, description: str)

Bases: AgentTool

Agent tool for summarizing documents.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.

as_write() → SummarizeDocumentAgentToolUpsert: Convert this tool to its upsert representation.

class cognite.client.data_classes.agents.SummarizeDocumentAgentToolUpsert(name: str, description: str)

Bases: AgentToolUpsert

Upsert version of document summarization agent tool.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.

class cognite.client.data_classes.agents.TextContent(text: str = '')

Bases: MessageContent

Text content for messages.

Parameters: text (str) – The text content.

class cognite.client.data_classes.agents.UnknownAgentTool(name: str, description: str, type: str, configuration: Optional[dict[str, Any]] = None)

Bases: AgentTool

Agent tool for unknown/unrecognized tool types.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.
type (str) – The type of the agent tool.
configuration (dict[str, Any] | None) – The configuration of the agent tool.

as_write() → UnknownAgentToolUpsert: Convert this tool to its upsert representation.

class cognite.client.data_classes.agents.UnknownAgentToolUpsert(name: str, description: str, type: str, configuration: Optional[dict[str, Any]] = None)

Bases: AgentToolUpsert

Upsert version of unknown agent tool.

Parameters

name (str) – The name of the agent tool. Used by the agent to decide when to use this tool.
type (str) – The type of the agent tool.
description (str) – The description of the agent tool. Used by the agent to decide when to use this tool.
configuration (dict[str, Any] | None) – The configuration of the agent tool.

class cognite.client.data_classes.agents.UnknownContent(type: str, data: dict[str, typing.Any] = <factory>)

Bases: MessageContent

Unknown content type for forward compatibility.

Parameters

data (dict[str, Any]) – The raw content data.
type (str) – The content type.

dump(camel_case: bool = True) → dict[str, Any]: Dump the content to a dictionary.