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")

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