POST
/agents/{agent_id}Update an agent
Updates a reusable agent. See agent configuration.
- RetriesRetries up to 2×, 500ms backoff, 30s timeout.
agent_idstringrequired
The ID of the reusable agent.
modelstringoptional
The model to use for the agent. The requested model name is preserved.
reasoningobjectoptional
Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort.
textobjectoptional
Configuration for text generated by the agent.
service_tierstringoptional
The service tier used for model requests.
instructionsstringoptional
Additional instructions appended to the agent's default base instructions. Omit to leave unchanged.
multi_agentobjectoptional
Configuration for creating and coordinating subagents.
metadataobjectoptional
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.
namestringoptional
A replacement name. Omit to leave unchanged, or pass null to clear it.
toolsarrayoptional
Tools available to the agent.
200The updated agent.
idstringrequired
The ID of the reusable agent.
objectstringrequired
The object type. Always `agent`.
created_atintegerrequired
The Unix timestamp, in seconds, when the agent was created.
updated_atintegerrequired
The Unix timestamp, in seconds, when the agent was last updated.
namestringrequired
A human-readable name for the agent, or null if it is unnamed.
metadataobjectrequired
Custom string key-value pairs attached to the agent.
modelstringrequired
The requested model name used for inference.
reasoningobjectrequired
The resolved reasoning configuration, including the model default for an omitted effort.
textobjectrequired
The resolved configuration for text generated by the agent.
service_tierstringrequired
The resolved service-tier policy used for model requests.
instructionsstringrequired
Custom instructions appended to the agent's default base instructions.
toolsarray<object>required
Tools available to the agent.
multi_agentobjectrequired
The resolved configuration for creating and coordinating subagents.
400The request was invalid.
errorobjectrequired
The error returned by the API.
401Authentication or project context was missing.
errorobjectrequired
The error returned by the API.
404The requested session or event was not found.
errorobjectrequired
The error returned by the API.
409The request conflicted with the current session state.
errorobjectrequired
The error returned by the API.
500An internal error occurred.
errorobjectrequired
The error returned by the API.
503The service is temporarily unavailable.
errorobjectrequired
The error returned by the API.
Error handling
A 400 is returned: The request was invalid. A 401 is returned: Authentication or project context was missing. A 404 is returned: The requested session or event was not found. A 409 is returned: The request conflicted with the current session state. A 500 is returned: An internal error occurred. A 503 is returned: The service is temporarily unavailable.