Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Update an agent

beta.agents.update(agent_id, **kwargs) -> Agent
POST
/agents/{agent_id}

Updates a reusable agent. See agent configuration.

Parameters
agent_id: str
minLength0
maxLength1048576
compaction: Optional[Compaction]

Context compaction settings. Omit to keep the current settings. A supplied object replaces the settings; null or an empty object enables background compaction.

experimental: Optional[Experimental]

Experimental settings to merge by key. Omitted settings keep their current values.

instructions: Optional[str]

Additional instructions appended to the agent’s default base instructions. Omit to leave unchanged.

minLength0
maxLength1048576
metadata: Optional[Dict[str, str]]

Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters.

model: Optional[str]

The model to use for the agent. The requested model name is preserved.

minLength0
maxLength1048576
multi_agent: Optional[MultiAgentConfigParam]

Configuration for creating and coordinating subagents.

name: Optional[str]

A replacement name. Omit to leave unchanged, or pass null to clear it.

minLength0
maxLength128
reasoning: Optional[AgentReasoningParam]

Configuration for model reasoning. Omit to keep the current settings; pass null to reset to the model’s default effort.

service_tier: Optional[Literal["auto", "default", "flex", 3 more]]

The service tier used for model requests.

text: Optional[AgentTextParam]

Configuration for text generated by the agent.

tools: Optional[Iterable[PersistedAgentToolParam]]

Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.

minItems0
maxItems2000
Returns
class Agent: …

A reusable agent scoped to the caller’s project.

id: str

The ID of the reusable agent.

minLength0
created_at: int

The Unix timestamp, in seconds, when the agent was created.

formatint64
instructions: Optional[str]

Custom instructions appended to the agent’s default base instructions.

minLength0
metadata: Dict[str, str]

Custom string key-value pairs attached to the agent.

model: str

The requested model name used for inference.

minLength0
multi_agent: MultiAgentConfig

The resolved configuration for creating and coordinating subagents.

name: Optional[str]

A human-readable name for the agent, or null if it is unnamed.

minLength0
object: Literal["agent"]

The object type. Always agent.

reasoning: AgentReasoning

The resolved reasoning configuration, including the model default for an omitted effort.

service_tier: Literal["auto", "default", "flex", 3 more]

The resolved service-tier policy used for model requests.

text: AgentText

The resolved configuration for text generated by the agent.

tools: List[PersistedAgentTool]

Tools available to the agent.

minItems0
maxItems2000
updated_at: int

The Unix timestamp, in seconds, when the agent was last updated.

formatint64
compaction: Optional[Compaction]

The effective context compaction settings.

experimental: Optional[Experimental]

The effective experimental settings for the agent.

Update an agent

from openai import OpenAI

client = OpenAI()
agent_id = "your-agent-id"

# 1. Omit reasoning: keep its current settings while renaming the agent.
client.beta.agents.update(agent_id, name="Renamed")

# 2. Python's None sends JSON null: reset reasoning to the model's defaults.
client.beta.agents.update(agent_id, reasoning=None)

# 3. Send an object: replace the entire reasoning configuration, without merging.
# The agent's model must support the "low" reasoning effort.
client.beta.agents.update(agent_id, reasoning={"effort": "low"})
200 — Example
{
  "id": "id",
  "created_at": 0,
  "instructions": "instructions",
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 1
  },
  "name": "name",
  "object": "agent",
  "reasoning": {
    "effort": "none",
    "summary": "concise"
  },
  "service_tier": "auto",
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "tools": [
    {
      "defer_loading": true,
      "description": "description",
      "name": "name",
      "parameters": {
        "foo": "bar"
      },
      "type": "function",
      "async": true
    }
  ],
  "updated_at": 0,
  "compaction": {
    "async": true
  },
  "experimental": {
    "time_awareness": true
  }
}
Returns Examples
200 — Example
{
  "id": "id",
  "created_at": 0,
  "instructions": "instructions",
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 1
  },
  "name": "name",
  "object": "agent",
  "reasoning": {
    "effort": "none",
    "summary": "concise"
  },
  "service_tier": "auto",
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "tools": [
    {
      "defer_loading": true,
      "description": "description",
      "name": "name",
      "parameters": {
        "foo": "bar"
      },
      "type": "function",
      "async": true
    }
  ],
  "updated_at": 0,
  "compaction": {
    "async": true
  },
  "experimental": {
    "time_awareness": true
  }
}