Agents

`AsyncCogniteClient.agents.chat`(...[, ...])	Chat with an agent.
`AsyncCogniteClient.agents.delete`(external_ids)	Delete one or more agents.
`AsyncCogniteClient.agents.list`()	List agents.
`AsyncCogniteClient.agents.retrieve`(external_ids)	Retrieve one or more agents by external ID.
`AsyncCogniteClient.agents.upsert`(agents)	Create or update (upsert) one or more agents.

Agent Data classes

class cognite.client.data_classes.agents.Action

Bases: CogniteResource, ABC

Base class for all action types that can be provided to an agent.

class cognite.client.data_classes.agents.ActionCall(action_id: str)

Bases: CogniteResource, ABC

Base class for action calls requested by the agent.

class cognite.client.data_classes.agents.ActionResult(action_id: str)

Bases: CogniteResource, ABC

Base class for action execution results.

class cognite.client.data_classes.agents.Agent( external_id: str, name: str, created_time: int, last_updated_time: int, description: str | None = None, instructions: str | None = None, model: str | None = None, runtime_version: str | None = None, labels: list[str] | None = None, tools: AgentToolList | Sequence[AgentTool] | None = None, owner_id: str | None = 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.
created_time (int) – The time the agent was created, in milliseconds since Thursday, 1 January 1970 00:00:00 UTC, minus leap seconds.
last_updated_time (int) – The time the agent was last updated, in milliseconds since Thursday, 1 January 1970 00:00:00 UTC, minus leap seconds.
description (str | None) – The human readable description of the agent. Always present in API responses.
instructions (str | None) – Instructions for the agent. Always present in API responses.
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”. Always present in API responses.
runtime_version (str | None) – The runtime version of the agent. Defines the complete execution environment including system prompt, available tools, and core features. Always present in API responses (server defaults to the latest version if not provided on upsert). See https://docs.cognite.com/cdf/atlas_ai/references/atlas_ai_agent_runtime_versions for available versions.
labels (list[str] | None) – Labels for the agent. For example, [“published”] to mark an agent as published. Always present in API responses.
tools (AgentToolList | Sequence[AgentTool] | None) – List of tools for the agent.
owner_id (str | None) – The ID of the user who owns the agent. Always present in API responses.

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_external_id: str, messages: AgentMessageList, type: str, cursor: str | None = None, )

Bases: CogniteResource

Response from agent chat.

Parameters:

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

property action_calls: list[ActionCall] | None: Get all action calls from all messages.

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

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: Sequence[T_CogniteResource], )

Bases: WriteableCogniteResourceList[AgentUpsert, Agent], ExternalIDTransformerMixin

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

class cognite.client.data_classes.agents.AgentMessage( content: MessageContent | None = None, data: list[AgentDataItem] | None = None, reasoning: list[AgentReasoningItem] | None = None, actions: list[ActionCall] | None = 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.
actions (list[ActionCall] | None) – Action calls requested by the agent.
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: Sequence[T_CogniteResource], )

Bases: CogniteResourceList[AgentMessage]

List of agent messages.

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

Bases: CogniteResource

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: Sequence[T_CogniteResource], )

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: Sequence[T_CogniteResource], ): Bases: CogniteResourceList[AgentToolUpsert]

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”.
runtime_version (str | None) – The runtime version of the agent. Defines the complete execution environment including system prompt, available tools, and core features. Defaults to the latest version if not set. See https://docs.cognite.com/cdf/atlas_ai/references/atlas_ai_agent_runtime_versions for available versions.
labels (list[str] | None) – Labels for the agent. For example, [“published”] to mark an agent as published.
tools (AgentToolUpsertList | 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: Sequence[T_CogniteResource], ): 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.ClientToolAction(name: str, description: str, parameters: dict[str, object])

Bases: Action

A client-side tool definition that can be called by the agent.

Parameters:

name (str) – The name of the client tool to call.
description (str) – A description of what the function does. The language model will use this description when selecting the function and interpreting its parameters.
parameters (dict[str, object]) – The parameters the function accepts, described as a JSON Schema object.

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.ClientToolCall(action_id: str, name: str, arguments: dict[str, object])

Bases: ActionCall

A client tool call requested by the agent.

Parameters:

action_id (str) – The unique identifier for this action call.
name (str) – The name of the client tool being called.
arguments (dict[str, object]) – The parsed arguments for the tool call.

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.ClientToolResult( action_id: str, content: str | MessageContent, data: list[Any] | None = None, )

Bases: ActionResult

Result of executing a client tool, for sending back to the agent.

Parameters:

action_id (str) – The ID of the action being responded to.
content (str | MessageContent) – The result of executing the action.
data (list[Any] | None) – Optional structured data.

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.DataModelInfo( space: str, external_id: str, version: str, view_external_ids: Sequence[str] | None = 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: Sequence[str] | None = 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 | 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: CogniteResource, ABC

Base class for message content types.

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.MessageList( resources: Sequence[T_CogniteResource], )

Bases: CogniteResourceList[Message]

List of messages.

class cognite.client.data_classes.agents.QueryKnowledgeGraphAgentTool( name: str, description: str, configuration: QueryKnowledgeGraphAgentToolConfiguration | None = 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: Sequence[DataModelInfo], instance_spaces: InstanceSpaces | None = None, version: Literal['v1', 'v2'] | str | None = None, )

Bases: WriteableCogniteResource

Configuration for knowledge graph query agent tools.

Parameters:

data_models (Sequence[DataModelInfo]) – The data models and views to query.
instance_spaces (InstanceSpaces | None) – The instance spaces to query.
version (Literal['v1', 'v2'] | str | None) – The version of the query generation strategy to use. A higher number does not necessarily mean a better query. Supported values are “v1” and “v2”.

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: QueryKnowledgeGraphAgentToolConfiguration | None = 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.ToolConfirmationCall( action_id: str, content: MessageContent, tool_name: str, tool_arguments: dict[str, object], tool_description: str, tool_type: str, details: dict[str, object] | None = None, )

Bases: ActionCall

A tool confirmation request from the agent.

Some tools require explicit user confirmation before execution, to prevent unintended or destructive actions. These tools include Call Function, Run Python code, and Call REST API. When an agent wants to run one of these tools, this action is included in the response instead of the final result. Respond with a ToolConfirmationResult using status="ALLOW" to proceed or status="DENY" to cancel.

Parameters:

action_id (str) – The unique identifier for this action call.
content (MessageContent) – The human-readable confirmation message from the agent.
tool_name (str) – The name of the tool requiring confirmation.
tool_arguments (dict[str, object]) – The arguments for the tool call.
tool_description (str) – Description of what the tool does.
tool_type (str) – The type of tool (e.g., “callFunction”, “runPythonCode”, “callRestApi”).
details (dict[str, object] | None) – Optional additional details about the tool call.

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.ToolConfirmationResult(action_id: str, status: Literal['ALLOW', 'DENY'])

Bases: ActionResult

Result of a tool confirmation request, sent back to the agent.

Use this to respond to a ToolConfirmationCall received in the agent response. Pass status="ALLOW" to let the agent execute the tool, or status="DENY" to cancel it. Always include the cursor from the confirmation response when sending this result.

Parameters:

action_id (str) – The ID of the ToolConfirmationCall being responded to.
status (Literal['ALLOW', 'DENY']) – Whether to allow or deny the tool execution.

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.UnknownAction(type: str, data: dict[str, object] = <factory>)

Bases: Action

Unknown action type for forward compatibility.

Parameters:

type (str) – The action type.
data (dict[str, object]) – The raw action data.

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.UnknownActionCall( action_id: str, type: str, data: dict[str, object] = <factory>, )

Bases: ActionCall

Unknown action call type for forward compatibility.

Parameters:

action_id (str) – The unique identifier for this action call.
type (str) – The action call type.
data (dict[str, object]) – The raw action call data.

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.UnknownAgentTool( name: str, description: str, type: str, configuration: dict[str, Any] | None = 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: dict[str, Any] | None = 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.
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.

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

Bases: MessageContent

Unknown content type for forward compatibility.

Parameters:

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

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]