agents

Modify Agent

Update an existing agent.

Authentication

AuthorizationBearer

Header authentication of the form Bearer <token>

Path Parameters

agent_idstringRequiredformat: "^agent-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"=42 characters

The ID of the agent in the format ‘agent-<uuid4>’

Request

This endpoint expects an object.
namestring or nullOptional
The name of the agent.
tool_idslist of strings or nullOptional
The ids of the tools used by the agent.
source_idslist of strings or nullOptional
The ids of the sources used by the agent.
block_idslist of strings or nullOptional
The ids of the blocks used by the agent.
tagslist of strings or nullOptional
The tags associated with the agent.
systemstring or nullOptional
The system prompt used by the agent.
tool_ruleslist of objects or nullOptional
The tool rules governing the agent.
message_idslist of strings or nullOptional

The ids of the messages in the agent’s in-context memory.

descriptionstring or nullOptional
The description of the agent.
metadatamap from strings to any or nullOptional
The metadata of the agent.
tool_exec_environment_variablesmap from strings to strings or nullOptional

Deprecated: use secrets field instead

secretsmap from strings to strings or nullOptional
The environment variables for tool execution specific to this agent.
project_idstring or nullOptional
The id of the project the agent belongs to.
template_idstring or nullOptional
The id of the template the agent belongs to.
base_template_idstring or nullOptional
The base template id of the agent.
identity_idslist of strings or nullOptional
The ids of the identities associated with this agent.
message_buffer_autoclearboolean or nullOptional

If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case.

modelstring or nullOptional

The model handle used by the agent (format: provider/model-name).

embeddingstring or nullOptional

The embedding model handle used by the agent (format: provider/model-name).

model_settingsobject or nullOptional
The model settings for the agent.
context_window_limitinteger or nullOptional
The context window limit used by the agent.
embedding_configobject or nullOptional
The embedding configuration used by the agent.
enable_sleeptimeboolean or nullOptional
If set to True, memory management will move to a background agent thread.
last_run_completionstring or nullOptionalformat: "date-time"
The timestamp when the agent last completed a run.
last_run_duration_msinteger or nullOptional
The duration in milliseconds of the agent's last run.
last_stop_reasonenum or nullOptional
The stop reason from the agent's last run.
timezonestring or nullOptional

The timezone of the agent (IANA format).

max_files_openinteger or nullOptional
Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent.
per_file_view_window_char_limitinteger or nullOptional

The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent.

hiddenboolean or nullOptional
If set to True, the agent will be hidden.
reasoningboolean or nullOptionalDeprecated

Deprecated: Use model field to configure reasoning instead. Whether to enable reasoning for this agent.

llm_configobject or nullOptionalDeprecated

Deprecated: Use model field instead. The LLM configuration used by the agent.

parallel_tool_callsboolean or nullOptionalDefaults to falseDeprecated

Deprecated: Use model field to configure parallel tool calls instead. If set to True, enables parallel tool calling.

response_formatobject or nullOptionalDeprecated

Deprecated: Use model field to configure response format instead. The response format for the agent.

max_tokensinteger or nullOptionalDeprecated

Deprecated: Use model field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step.

Response

Successful Response
idstring
The id of the agent. Assigned by the database.
namestring
The name of the agent.
systemstring
The system prompt used by the agent.
agent_typeenum
The type of agent.
llm_configobject

Deprecated: Use model field instead. The LLM configuration used by the agent.

embedding_configobject

Deprecated: Use embedding field instead. The embedding configuration used by the agent.

memoryobject

Deprecated: Use blocks field instead. The in-context memory of the agent.

blockslist of objects
The memory blocks used by the agent.
toolslist of objects
The tools used by the agent.
sourceslist of objects
The sources used by the agent.
tagslist of strings
The tags associated with the agent.
created_by_idstring or null
The id of the user that made this object.
last_updated_by_idstring or null
The id of the user that made this object.
created_atstring or nullformat: "date-time"
The timestamp when the object was created.
updated_atstring or nullformat: "date-time"
The timestamp when the object was last updated.
tool_ruleslist of objects or null
The list of tool rules.
message_idslist of strings or null

The ids of the messages in the agent’s in-context memory.

modelstring or null

The model handle used by the agent (format: provider/model-name).

embeddingstring or null

The embedding model handle used by the agent (format: provider/model-name).

model_settingsobject or null
The model settings used by the agent.
response_formatobject or null
The response format used by the agent
descriptionstring or null
The description of the agent.
metadatamap from strings to any or null
The metadata of the agent.
secretslist of objects or null
The environment variables for tool execution specific to this agent.
project_idstring or null
The id of the project the agent belongs to.
template_idstring or null
The id of the template the agent belongs to.
base_template_idstring or null
The base template id of the agent.
deployment_idstring or null
The id of the deployment.
entity_idstring or null
The id of the entity within the template.
identitieslist of objects or null
The identities associated with this agent.
message_buffer_autoclearboolean or nullDefaults to false

If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case.

enable_sleeptimeboolean or null
If set to True, memory management will move to a background agent thread.
managed_groupobject or null

The multi-agent group that this agent manages

last_run_completionstring or nullformat: "date-time"
The timestamp when the agent last completed a run.
last_run_duration_msinteger or null
The duration in milliseconds of the agent's last run.
last_stop_reasonenum or null
The stop reason from the agent's last run.
timezonestring or null

The timezone of the agent (IANA format).

max_files_openinteger or null
Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent.
per_file_view_window_char_limitinteger or null

The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent.

hiddenboolean or null
If set to True, the agent will be hidden.
tool_exec_environment_variableslist of objects or nullDeprecated

Deprecated: use secrets field instead.

identity_idslist of strings or nullDeprecated

Deprecated: Use identities field instead. The ids of the identities associated with this agent.

multi_agent_groupobject or nullDeprecated

Deprecated: Use managed_group field instead. The multi-agent group that this agent manages.

Errors