Update an agent
POST/agents/{agent_id}
Updates a reusable agent. See agent configuration.
Body ParametersJSON
instructions: optional string or null
Additional instructions appended to the agent’s default base instructions. Omit to leave unchanged.
minLength0
maxLength1048576
metadata: optional map[string] or null
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 string
The model to use for the agent. The requested model name is preserved.
minLength0
maxLength1048576
Update an agent
# 1. Omit reasoning: keep its current settings while renaming the agent.
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: agents=v1" \
-d '{"name": "Renamed"}'
# 2. Send null: reset reasoning to the model's defaults.
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: agents=v1" \
-d '{"reasoning": null}'
# 3. Send an object: replace the entire reasoning configuration, without merging.
# The agent's model must support the "low" reasoning effort.
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: agents=v1" \
-d '{"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
}
