Agents¶

For usage information and examples, please see Agents

class dataikuapi.dss.agent.DSSAgentListItem(client, data)¶

An item in a list of agents

Important

Do not instantiate this class directly, instead use dataikuapi.dss.project.DSSProject.list_agents().

property project_key¶

Returns:: The project
Return type:: string

property id¶

Returns:: The id of the agent.
Return type:: string

property name¶

Returns:: The name of the agent.
Return type:: string

as_llm()¶

Returns:: this agent as a usable dataikuapi.dss.llm.DSSLLM for querying
Return type:: dataikuapi.dss.llm.DSSLLM

class dataikuapi.dss.agent.DSSAgent(client, project_key, id)¶

A handle to interact with a DSS-managed agent.

Important

Do not create this class directly, use dataikuapi.dss.project.DSSProject.get_agent() instead.

property id¶

as_llm()¶

Returns:: this agent as a usable dataikuapi.dss.llm.DSSLLM for querying
Return type:: dataikuapi.dss.llm.DSSLLM

get_settings()¶

Returns:: a handle on the agent’s definition
Return type:: dataikuapi.dss.agent.DSSAgentSettings

delete()¶: Delete the agent

shutdown(version_id=None, force=False)¶

Shutdown all instances of the given version of this agent

Parameters:

version_id (str | None) – If unspecified, uses the active version.
force (bool) – If True, cancel requests being processed and stop the instances. If False, let those active requests complete before stopping.

status(version_id=None)¶

Query status of instances of the given version of this agent

Parameters:: version_id (str | None) – If unspecified, uses the active version.
Returns:: A dict holding the list of the status for each instance.

wake_up(version_id=None)¶

Start an instance of an agent if none is started

Parameters:: version_id (str | None) – If unspecified, uses the active version.

get_metrics_series(from_timestamp_ms=None, to_timestamp_ms=None, aggregation='MINUTE', timezone=None)¶

Get the operational metrics series for this agent.

The returned payload may include the ongoing interval for the requested granularity. As a consequence, the latest datapoint is temporarily inconsistent and may evolve as more raw events are flushed and aggregated at read time. The requested time window is aligned to the bucket boundaries of the selected aggregation before being read.

Parameters:

from_timestamp_ms (int) – Beginning of the requested window, inclusive, as an epoch timestamp in milliseconds. The effective lower bound is rounded down to the start of its bucket. Optional, defaults to the oldest retained timestamp available for the requested aggregation.
to_timestamp_ms (int) – End of the requested window, exclusive, as an epoch timestamp in milliseconds. The effective upper bound is rounded up to the next bucket boundary when it falls inside a bucket. Optional, defaults to the current time when omitted.
aggregation (str) – Aggregation granularity. Supported values are MINUTE, FIVE_MINUTES, HOUR, DAY and MONTH.
timezone (str) – Timezone used to align bucket boundaries. Optional, defaults to UTC. Can be a timezone name like Europe/Paris.

Returns:

The list of datapoints. Each datapoint contains a timestampMs expressed as the start timestamp of its bucket in epoch milliseconds. For example, with HOUR aggregation, a datapoint at 18:00 represents the interval [18:00, 19:00).

Return type:

list[dict]

class dataikuapi.dss.agent.DSSAgentSettings(client, settings)¶

Settings for a agent

Important

Do not instantiate directly, use dataikuapi.dss.agent.DSSAgent.get_settings() instead

get_version_ids()¶

List the ids of each version of this agent

Return type:: list[str]

property active_version¶

Returns:: the active version of this agent, or None if no version is declared as active
Return type:: str | None

get_version_settings(version_id)¶

Returns:: the settings of the given version of this agent
Return type:: DSSAgentVersionSettings

property type¶

get_raw()¶

Returns:: the raw settings of this agent
Return type:: dict

save()¶: Saves the settings for this agent

class dataikuapi.dss.agent.DSSAgentVersionSettings(settings, version_settings)¶

get_raw()¶

Returns:: the raw settings of this agent version
Return type:: dict

property llm_id¶

Only for Visual Agents

Return type:: str

property tools¶

Returns the list of tools of the agent. The list can be modified.

Each tool is a dict, containing at least “toolRef”, which is the identifier of the tool. The dict may also contain “additionalDescription” which is added to the description of the tool

add_tool(tool)¶

Adds a tool to the agent

Parameters:: tool – a string (identifier of the tool), or a dataikuapi.dss.agent_tool.DSSAgentTool

property interaction_logging_selection¶

Get the interaction logging selection for this version.

Before configuring interaction logging on an agent version, create the target dataset on the project:

project = client.get_project("MYPROJECT")
project.create_llm_interaction_logging_dataset(
    "agent_logs",
    connection_id="filesystem_managed",
    time_partitioning="DAY",
)

Example using inherited settings:

agent = project.get_agent("my_agent")
agent_settings = agent.get_settings()
version_settings = agent_settings.get_version_settings("v1")

agent_logging_selection = version_settings.interaction_logging_selection
agent_logging_selection.inherit()

agent_settings.save()

Example using explicit settings:

agent = project.get_agent("my_agent")
agent_settings = agent.get_settings()
version_settings = agent_settings.get_version_settings("v1")

agent_logging_selection = version_settings.interaction_logging_selection
agent_logging_selection.enable(
    "agent_logs",
    settings={
        "flushEveryS": 60,
        "flushEveryBytes": 1_000_000,
        "contentMode": "FULL",
    },
)

agent_settings.save()

Example disabling interaction logging:

agent = project.get_agent("my_agent")
agent_settings = agent.get_settings()
version_settings = agent_settings.get_version_settings("v1")

agent_logging_selection = version_settings.interaction_logging_selection
agent_logging_selection.disable()

agent_settings.save()

Return type:: dataikuapi.dss.agent.DSSAgentInteractionLoggingSelection

class dataikuapi.dss.agent.DSSAgentInteractionLoggingSettings(settings)¶

Settings for agent interaction logging.

Important

Do not instantiate this class directly, use dataikuapi.dss.agent.DSSAgentInteractionLoggingSelection.settings instead.

CONTENT_MODE_FULL = 'FULL'¶

CONTENT_MODE_NO_LOGS = 'NO_LOGS'¶

CONTENT_MODE_NO_LOGS_NO_TRACE = 'NO_LOGS_NO_TRACE'¶

get_raw()¶

Returns the raw interaction logging settings.

Return type:: dict

get(key, default=None)¶

property dataset_name¶

The dataset name used for interaction logging.

Return type:: str | None

property write_as_user¶

The DSS user used to write logs.

This value is read-only and is set automatically to the user who saves the agent settings.

Return type:: str | None

property flush_every_s¶

The flush interval, in seconds.

Return type:: int | None

property flush_every_bytes¶

The maximum buffered payload size before a flush.

Return type:: int | None

property content_mode¶

The content logging mode.

Return type:: str | None

class dataikuapi.dss.agent.DSSAgentInteractionLoggingSelection(selection)¶

Selection for agent interaction logging.

Important

Do not instantiate this class directly, use dataikuapi.dss.agent.DSSAgentVersionSettings.interaction_logging_selection instead.

MODE_INHERIT = 'INHERIT'¶

MODE_EXPLICIT = 'EXPLICIT'¶

MODE_NONE = 'NONE'¶

get_raw()¶

Returns the raw interaction logging selection.

Return type:: dict

get(key, default=None)¶

property mode¶

The interaction logging mode. One of INHERIT, EXPLICIT or NONE.

In INHERIT mode, settings are inherited from the project-level configuration.

Return type:: str | None

property settings¶

The explicit interaction logging settings.

These settings are only used when the selection is in EXPLICIT mode.

Return type:: dataikuapi.dss.agent.DSSAgentInteractionLoggingSettings

enable(dataset_name, settings=None)¶

Enable interaction logging on this agent version with explicit settings.

This only controls the agent version setting itself. Interaction logging can still be effectively unavailable if it is disabled at the instance level.

Parameters:

dataset_name (str) – Dataset name used for interaction logging.
settings (dict | dataikuapi.dss.agent.DSSAgentInteractionLoggingSettings | None) – Optional explicit settings payload or dataikuapi.dss.agent.DSSAgentInteractionLoggingSettings.

inherit()¶

Enable interaction logging on this agent version in inherited mode.

In this mode, the version inherits the project-level interaction logging settings.

disable()¶: Disable interaction logging on this agent version.

dataikuapi.dss.agent.DSSLLMInteractionLoggingSettings¶: alias of DSSAgentInteractionLoggingSettings

dataikuapi.dss.agent.DSSLLMInteractionLoggingSelection¶: alias of DSSAgentInteractionLoggingSelection

class dataikuapi.dss.agent_tool.DSSAgentToolListItem(client, project_key, data)¶

Important

Do not instantiate this class directly, instead use dataikuapi.dss.project.DSSProject.list_agent_tools().

to_agent_tool()¶: Convert the current item.

property id¶

Returns:: The id of the tool.
Return type:: string

property type¶

Returns:: The type of the tool
Return type:: string

property name¶

Returns:: The name of the tool
Return type:: string

class dataikuapi.dss.agent_tool.DSSAgentTool(client, project_key, tool_id, descriptor=None)¶

Important

Do not instantiate this class directly, instead use dataikuapi.dss.project.DSSProject.get_agent_tool().

property id¶

Returns:: The id of the tool.
Return type:: string

get_descriptor(context=None)¶

Get the descriptor of the tool

Returns:: a descriptor of the tool
Return type:: dict

get_settings()¶

Get the agent tools’ settings

Returns:: a handle on the tool settings
Return type:: dataikuapi.dss.agent_tool.DSSAgentToolSettings or a subclass

delete()¶: Delete the agent tool

as_langchain_structured_tool(context=None)¶

Returns:: this tool as a LangChain StructuredTool
Return type:: langchain_core.tools.StructuredTool

run(input, context=None, subtool_name=None, memory_fragment=None, tool_validation_responses=None, tool_validation_requests=None)¶

Execute a tool call

Parameters:

input (dict) – Input for the tool
context (dict) – Additional request context
subtool_name (str) – Name of the sub-tool, if applicable (e.g., for a MCP tool)

Return type:

dict

Returns:

The result of running this tool

describe_tool_call(input, descriptor, context=None, subtool_name=None)¶

Get a description for a tool call before it is executed

Returns:: a string description of the tool call
Return type:: Optional[str]

class dataikuapi.dss.agent_tool.DSSAgentToolCreator(project, type, name, id)¶

Helper to create new agent tools

Important

Do not instantiate directly, use dataikuapi.dss.project.DSSProject.new_agent_tool() instead.

create()¶

Creates the new agent tool in the project, and return a handle to interact with it.

Return type:: dataikuapi.dss.agent_tool.DSSAgentTool

class dataikuapi.dss.agent_tool.DSSAgentToolSettings(agent_tool, settings)¶

get_raw()¶

Returns:: the raw settings dict for this agent tool
Return type:: dict

property params¶: The parameters of the tool, as a dict. Changes to the dict will be reflected when saving

property name¶

Returns:: The name of the tool
Return type:: string

property type¶

Returns:: The type of the tool
Return type:: string

save()¶: Saves the settings of the agent tool

property custom_fields¶: The custom fields of the object as a dict. Returns None if there are no custom fields

property description¶: The description of the object as a string

property short_description¶: The short description of the object as a string

property tags¶: The tags of the object, as a list of strings

class dataikuapi.dss.agent_tool.DSSVectorStoreSearchAgentToolCreator(project, type, name, id)¶

with_knowledge_bank(kb)¶

Parameters:: kb (DSSKnowledgeBank | DSSKnowledgeBankListItem | str) – Knowledge Bank (object, list item, or identifier) to use in this tool

create()¶

Creates the new agent tool in the project, and return a handle to interact with it.

Return type:: dataikuapi.dss.agent_tool.DSSAgentTool

class dataikuapi.dss.agent_tool.DSSVectorStoreSearchAgentToolSettings(agent_tool, settings)¶

set_knowledge_bank(kb)¶

Parameters:: kb (DSSKnowledgeBank | DSSKnowledgeBankListItem | str) – Knowledge Bank (object, list item, or identifier) to use in this tool

property custom_fields¶: The custom fields of the object as a dict. Returns None if there are no custom fields

property description¶: The description of the object as a string

get_raw()¶

Returns:: the raw settings dict for this agent tool
Return type:: dict

property name¶

Returns:: The name of the tool
Return type:: string

property params¶: The parameters of the tool, as a dict. Changes to the dict will be reflected when saving

save()¶: Saves the settings of the agent tool

property short_description¶: The short description of the object as a string

property tags¶: The tags of the object, as a list of strings

property type¶

Returns:: The type of the tool
Return type:: string

class dataikuapi.dss.agent_skill.DSSAgentSkillListItem(client, project_key, data)¶

Important

Do not instantiate this class directly, instead use dataikuapi.dss.project.DSSProject.list_agent_skills().

to_agent_skill()¶

Convert the current item.

Return type:: dataikuapi.dss.agent_skill.DSSAgentSkill

property id¶

Returns:: The id of the skill.
Return type:: string

property name¶

Returns:: The name of the skill.
Return type:: string

class dataikuapi.dss.agent_skill.DSSAgentSkill(client, project_key, skill_id)¶

Important

Do not instantiate this class directly, instead use dataikuapi.dss.project.DSSProject.get_agent_skill().

property id¶

Returns:: The id of the skill.
Return type:: string

get_settings()¶

Get the DSS metadata settings of the agent skill.

The parsed SKILL.md fields are available through get_skill_content() and the raw file through get_file().

Returns:: a handle on the skill settings
Return type:: dataikuapi.dss.agent_skill.DSSAgentSkillSettings

get_skill_content()¶

Get the parsed contents of SKILL.md.

Returns:: A dictionary containing name, description, metadata, and instructions.
Return type:: dict

delete()¶: Delete the agent skill.

list_resources()¶

List the files and folders attached to this skill as a recursive tree.

Return type:: list[dict]

get_file(path)¶

Get a file’s contents.

Parameters:: path (str) – Root-relative path of the file to download
Return type:: requests.models.Response

get_file_details(path)¶

Get a file’s metadata without its content.

Parameters:: path (str) – Root-relative path of the file
Return type:: dict

put_file(path, data)¶

Create or overwrite a file.

Strings are encoded as UTF-8 and bytes are stored unchanged. Parent folders must already exist. Replacing the root SKILL.md validates the supplied content and rejects an invalid skill file.

Parameters:

path (str) – Root-relative path of the file
data – String, bytes, or file-like content

Return type:

dict

rename_resource(path, new_name)¶

Rename a resource.

Parameters:

path (str) – Root-relative path of the existing resource
new_name (str) – New file name, without a folder path

Return type:

str

move_resource(path, new_path)¶

Move a resource to a destination folder.

Parameters:

path (str) – Root-relative path of the existing resource
new_path (str) – Root-relative path of the destination folder, or an empty string for the skill root

Return type:

str

create_folder(path)¶

Create a resource folder in the skill.

Missing parent folders are created as needed.

Parameters:: path (str) – Root-relative path of the folder to create

delete_resource(path)¶

Delete a resource from the skill.

Parameters:: path (str) – Root-relative path of the resource to delete

class dataikuapi.dss.agent_skill.DSSAgentSkillSettings(agent_skill, settings)¶

get_raw()¶

Get the raw settings of the skill.

Return type:: dict

save()¶

Saves the DSS metadata settings of the agent skill.

This does not modify SKILL.md. Use DSSAgentSkill.put_file() to replace the skill file.

property custom_fields¶: The custom fields of the object as a dict. Returns None if there are no custom fields

property description¶: The description of the object as a string

property short_description¶: The short description of the object as a string

property tags¶: The tags of the object, as a list of strings