---
title: "Update an agent"
method: PUT
path: "/agent/identities/{uid}"
tags: ["agent"]
---

# Update an agent

`PUT /agent/identities/{uid}`

Update an existing agent.

## Path parameters

- `uid` string, required

## Request body

- UpdateAgentRequest — Partial update for an agent. Each field is optional: * Omitted or `null`: leave the field unchanged. * Empty value: clear the field. * Non-empty: replace the field wholesale with the provided value.
  - `name` string — The new name for the agent
  - `description` string, nullable — Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear.
  - `prompt` string, nullable — Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear.
  - `environment_id` string, nullable — Replacement default cloud environment ID. Omit or pass `null` to leave unchanged, or pass an empty string to clear.
  - `default_runner_uid` string, 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.
  - `secrets` SecretRef[], nullable — Replacement list of secrets. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace. Duplicate names are rejected.
    - `name` string, required — Name of the managed secret.
  - `skills` string[], 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_model` string, nullable — Replacement base model. Omit or pass `null` to leave unchanged, or pass an empty string to clear.
  - `memory` AgentMemoryUpdateConfig — Memory settings for updating an agent.
    - `attached_stores` MemoryStoreRef[], nullable — Replacement list of attached team memory stores. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace.
      - `uid` string, required — UID of the memory store.
      - `access` 'read_write' | 'read_only', required — Access level for the store.
      - `instructions` string, required — Instructions for how the agent should use this memory store. Must not be empty.
  - `mcp_servers` object — 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.
  - `inference_providers` InferenceProvidersConfig — Inference provider settings used for LLM calls.
    - `aws` AwsInferenceProviderConfig — Configures AWS Bedrock as the LLM inference provider for this agent or run.
      - `disabled` boolean — If true, opt out of Bedrock at this layer.
      - `role_arn` string — IAM role ARN to assume when calling Bedrock.
      - `region` string — AWS region used for STS when assuming the Bedrock inference role.
  - `base_harness` string, 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.
  - `harness` Harness — Specifies which execution harness to use for the agent run. Default (nil/empty) uses Warp's built-in harness. When stored as a named agent's default (create/update agent identity), this field replaces the deprecated base_harness/base_model pair: a non-oz type here requires the agent's base_model to be empty, since the two describe mutually exclusive default models.
    - `type` 'oz' | 'claude' | 'gemini' | 'codex' — The harness type identifier. - oz: Warp's built-in harness (default) - claude: Claude Code harness - gemini: Gemini CLI harness - codex: Codex CLI harness
    - `model_id` string — Model to use with a third-party harness (e.g. "claude-haiku-4-5"). Only applies when type is a non-oz harness; the top-level config model_id targets the built-in Oz harness instead. When omitted or empty, the harness uses its own default model.
    - `reasoning_level` string — Reasoning effort for harnesses that support it (e.g. Codex). Only applies when type is a non-oz harness. Ignored by harnesses that do not support reasoning levels.
  - `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.
  - `harness_auth_secrets` HarnessAuthSecrets — Authentication secrets for third-party harnesses. Only the secret for the harness specified gets injected into the environment.
    - `claude_auth_secret_name` string — Name of a managed secret for Claude Code harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "claude".
    - `codex_auth_secret_name` string — Name of a managed secret for Codex harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "codex".
  - `on_behalf_of_enabled` boolean, 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_host` string, 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 `200`

Agent updated successfully

- AgentResponse
  - `uid` string, required — Unique identifier for the agent
  - `name` string, required — Name of the agent
  - `description` string, nullable — Optional description of the agent
  - `prompt` string, nullable — Optional base prompt for this agent
  - `environment_id` string — 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_uid` string, 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
  - `available` boolean, required — Whether this agent is within the team's plan limit and can be used for runs
  - `created_at` string, date-time, required — When the agent was created (RFC3339)
  - `updated_at` string, date-time, required — When the agent was last updated (RFC3339)
  - `secrets` SecretRef[], required — Secrets that this agent may access by default.
    - `name` string, required — Name of the managed secret.
  - `skills` string[], required — Ordered list of normalized skill specs associated with this agent. Always present; empty when no skills are attached.
  - `base_model` string — 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
  - `inference_providers` InferenceProvidersConfig — Inference provider settings used for LLM calls.
    - `aws` AwsInferenceProviderConfig — Configures AWS Bedrock as the LLM inference provider for this agent or run.
      - `disabled` boolean — If true, opt out of Bedrock at this layer.
      - `role_arn` string — IAM role ARN to assume when calling Bedrock.
      - `region` string — AWS region used for STS when assuming the Bedrock inference role.
  - `memory` AgentMemoryResponse, required — Memory settings for an agent.
    - `auto_memory` AgentAutoMemoryResponse, required — Auto-memory state for an agent.
      - `enabled` boolean, required — Whether this agent has an agent-owned memory store.
      - `store` MemoryStoreAttachmentResponse — Memory store attached to an agent.
        - `uid` string, required — UID of the memory store.
        - `access` 'read_write' | 'read_only', required — Access level for the store.
        - `instructions` string, required — Instructions for how the agent should use this memory store.
        - `owner_type` 'user' | 'service_account' | 'team', required — Public owner type.
        - `owner_uid` string, required — Public UID of the user, service account, or team that owns the memory store.
        - `description` string — Optional description for the memory store.
    - `attached_stores` MemoryStoreRef[], required — Team memory stores attached to the agent.
      - `uid` string, required — UID of the memory store.
      - `access` 'read_write' | 'read_only', required — Access level for the store.
      - `instructions` string, required — Instructions for how the agent should use this memory store. Must not be empty.
  - `mcp_servers` object — MCP server configurations attached to this agent by default. Run-level MCP config takes precedence over this agent-level default.
  - `base_harness` string — 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.
  - `harness` Harness — Specifies which execution harness to use for the agent run. Default (nil/empty) uses Warp's built-in harness. When stored as a named agent's default (create/update agent identity), this field replaces the deprecated base_harness/base_model pair: a non-oz type here requires the agent's base_model to be empty, since the two describe mutually exclusive default models.
    - `type` 'oz' | 'claude' | 'gemini' | 'codex' — The harness type identifier. - oz: Warp's built-in harness (default) - claude: Claude Code harness - gemini: Gemini CLI harness - codex: Codex CLI harness
    - `model_id` string — Model to use with a third-party harness (e.g. "claude-haiku-4-5"). Only applies when type is a non-oz harness; the top-level config model_id targets the built-in Oz harness instead. When omitted or empty, the harness uses its own default model.
    - `reasoning_level` string — Reasoning effort for harnesses that support it (e.g. Codex). Only applies when type is a non-oz harness. Ignored by harnesses that do not support reasoning levels.
  - `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.
  - `harness_auth_secrets` HarnessAuthSecrets — Authentication secrets for third-party harnesses. Only the secret for the harness specified gets injected into the environment.
    - `claude_auth_secret_name` string — Name of a managed secret for Claude Code harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "claude".
    - `codex_auth_secret_name` string — Name of a managed secret for Codex harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "codex".
  - `on_behalf_of_enabled` boolean — Whether runs created with this agent's API key may use the on_behalf_of field to attribute runs to another team member.
  - `worker_host` string — 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

## Other responses

- `400` — Missing or invalid request body
- `401` — Authentication required
- `403` — Only human users can manage agents, or plan limit exceeded
- `404` — Agent not found
- `500` — Internal server error

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/warp/oz-agent-api/revisions/a0daf9e59774/schema)