Update an agent
beta.agents.update(stragent_id, AgentUpdateParams**kwargs) -> Agent
POST/agents/{agent_id}
Updates a reusable agent. See agent configuration.
Parameters
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
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"})
{
"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"
}
],
"updated_at": 0
}Returns Examples
{
"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"
}
],
"updated_at": 0
}