---
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.
  - `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_stores` MemoryStoreRef[], nullable — Replacement list of 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.
  - `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.
  - `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".

## 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
  - `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_stores` MemoryStoreRef[], required — Memory stores attached to this agent. Always present; empty when no stores are attached.
    - `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.
  - `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
  - `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".

## 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.net/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.net/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/warp/oz-agent-api/versions/97be876c33e3/schema)