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",
...     labels=["published"],
...     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.",
...     labels=["published"],
...     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_external_id: str, messages: cognite.client.data_classes.agents.chat.Message | cognite.client.data_classes.agents.chat.ActionResult | collections.abc.Sequence[cognite.client.data_classes.agents.chat.Message | cognite.client.data_classes.agents.chat.ActionResult], cursor: Optional[str] = None, actions: Optional[Sequence[Action]] = 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_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()
>>> 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]
...         )

Agent Data classes

class cognite.client.data_classes.agents.Action

Bases: CogniteObject, 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: CogniteObject, ABC

Base class for action calls requested by the agent.

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

Bases: CogniteObject, ABC

Base class for action execution results.

class cognite.client.data_classes.agents.Agent(external_id: str, name: str, description: Optional[str] = None, instructions: Optional[str] = None, model: Optional[str] = None, labels: Optional[list[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. 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.
labels (list[str] | None) – Labels for the agent. For example, [“published”] to mark an agent as published. Always present in API responses.
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_external_id: str, messages: AgentMessageList, type: str, cursor: Optional[str] = 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[cognite.client.data_classes.agents.chat.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: 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, actions: Optional[list[cognite.client.data_classes.agents.chat.ActionCall]] = 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: 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, labels: Optional[list[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”.
labels (list[str] | None) – Labels for the agent. For example, [“published”] to mark an agent as published.
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.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 | cognite.client.data_classes.agents.chat.MessageContent, data: Optional[list[Any]] = 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: 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: Sequence[DataModelInfo], instance_spaces: Optional[InstanceSpaces] = None, version: Optional[Union[Literal['v1', 'v2'], str]] = 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 (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: 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.ToolConfirmationCall(action_id: str, content: MessageContent, tool_name: str, tool_arguments: dict[str, object], tool_description: str, tool_type: str, details: Optional[dict[str, object]] = None)

Bases: ActionCall

A tool confirmation request from the agent.

Parameters

action_id (str) – The unique identifier for this action call.
content (MessageContent) – The confirmation message content.
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., “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.

Parameters

action_id (str) – The ID of the action 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: 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.