Sign in
agent

Update an agent

Update an existing agent.

put/agent/identities/{uid}

Path parameters

uidstring required

The unique identifier of the agent

Request body

namestring

The new name for the agent

descriptionstring nullable

Replacement description. Omit or pass null to leave unchanged, or use an empty value to clear.

promptstring nullable

Replacement prompt. Omit or pass null to leave unchanged, or use an empty value to clear.

environment_idstring nullable

Replacement default cloud environment ID. Omit or pass null to leave unchanged, or pass an empty string to clear.

default_runner_uidstring nullable

Replacement default runner UID. Omit or pass null to leave unchanged, or pass an empty string to clear. A non-empty value must reference a runner the editor can View.

skillsstring[] nullable

Replacement list of skill specs. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace.

base_modelstring nullable

Replacement base model. Omit or pass null to leave unchanged, or pass an empty string to clear.

mcp_serversobject

Replacement map of MCP server configurations by name. Omit to leave unchanged, pass an empty object to clear, or pass a non-empty object to replace. Run-level MCP config takes precedence over this agent-level default.

base_harnessstring nullable

Replacement default harness. Omit or pass null to leave unchanged, or pass an empty string to clear. Deprecated - use harness instead. Kept for backward compatibility; when both are sent, harness is authoritative and a conflicting type is rejected with invalid_request.

credential_strategy'CREATOR' | 'EXECUTOR'

Default credential strategy for runs executed by a named agent.

  • EXECUTOR: runs authenticate with the named agent's own credentials (e.g. a GitHub App installation token for the agent's team).
  • CREATOR: runs authenticate with the credentials of the principal that created the run. Unlike the factory default, an agent may leave this unset. The strategy applied to a run is resolved in this order: the run's config.credential_strategy, then the agent's default, then the factory's default for factory-seeded agents, and finally EXECUTOR. The inherited strategy is validated at run creation time (the required credential must be mintable), like an explicit run-level value.
on_behalf_of_enabledboolean nullable

Whether runs created with this agent's API key may use the on_behalf_of field to attribute runs to another team member. Omit or pass null to leave unchanged. Only team admins may set this field.

worker_hoststring nullable

Replacement default worker host. Omit or pass null to leave unchanged, or pass an empty string to clear (the workspace default then applies). A non-empty value is trimmed and replaces the stored default; use "warp" to force Warp-hosted execution over a self-hosted workspace default.

Response

Agent updated successfully

uidstring required

Unique identifier for the agent

namestring required

Name of the agent

descriptionstring nullable

Optional description of the agent

promptstring nullable

Optional base prompt for this agent

environment_idstring

Default cloud environment ID for runs executed by this agent. The precedence order for environment resolution is:

  1. The environment specified on the run itself
  2. The agent's default environment
  3. An empty environment
default_runner_uidstring required

Default runner UID for runs executed by this agent. When set, it overrides the selected environment's default runner for runs that do not specify their own runner_id. The precedence order for runner resolution is:

  1. The runner specified on the run itself
  2. The agent's default runner
  3. The selected environment's default runner
  4. The environment's legacy inline compute fields
  5. System defaults
availableboolean required

Whether this agent is within the team's plan limit and can be used for runs

created_atstring date-time required

When the agent was created (RFC3339)

updated_atstring date-time required

When the agent was last updated (RFC3339)

skillsstring[] required

Ordered list of normalized skill specs associated with this agent. Always present; empty when no skills are attached.

base_modelstring

Base model for runs executed by this agent. The precedence order for model resolution is:

  1. The model specified on the run itself
  2. The agent's base model
  3. The team's default model
mcp_serversobject

MCP server configurations attached to this agent by default. Run-level MCP config takes precedence over this agent-level default.

base_harnessstring

Default harness for runs executed by this agent. The precedence order for harness resolution is:

  1. The harness specified on the run itself
  2. The agent's base harness
  3. Oz Deprecated - use harness instead, which carries the full {type, model_id, reasoning_level} default.
credential_strategy'CREATOR' | 'EXECUTOR'

Default credential strategy for runs executed by a named agent.

  • EXECUTOR: runs authenticate with the named agent's own credentials (e.g. a GitHub App installation token for the agent's team).
  • CREATOR: runs authenticate with the credentials of the principal that created the run. Unlike the factory default, an agent may leave this unset. The strategy applied to a run is resolved in this order: the run's config.credential_strategy, then the agent's default, then the factory's default for factory-seeded agents, and finally EXECUTOR. The inherited strategy is validated at run creation time (the required credential must be mintable), like an explicit run-level value.
on_behalf_of_enabledboolean

Whether runs created with this agent's API key may use the on_behalf_of field to attribute runs to another team member.

worker_hoststring

Default worker host for runs executed by this agent, or empty when unset. The precedence order for worker host resolution is:

  1. The host specified on the run itself
  2. The agent's default host
  3. The workspace default host

Changes