Update agent
Update an agent’s settings. Only fields in the body change; metadata merges section by section (objects merge, arrays and scalars replace), so send only the sections you want to change.
Collections have their own endpoints and one item changes per call: skills, connectors, knowledge sources, subagents, triggers and abilities. tools is still accepted and replaces the whole list; metadata.subagent.allowed_gummie_ids is ignored here.
Send version from your last read to make the update conditional: if anyone saved the agent in between, the response is 409 agent_version_conflict with the current version. Omit it to let the last write win.
Platform agents (gumball, analytics) answer 400 agent_not_customizable.
is_active: false is not a pause switch. It retires the agent: the agent disappears from GET /agents, and both GET and PATCH /agents/{agent_id} return 404 afterwards, so you cannot set it back to true through the API. To stop an agent from running on its own while keeping it fully reachable, disable its triggers instead. To remove it, use DELETE /agents/{agent_id}.
Authorizations
Path Parameters
ID of the agent to update. Also accepts the reserved aliases gumball and analytics.
Body
ID of the LLM the agent runs on. Use GET /models to discover valid values.
"anthropic/claude-sonnet-4"
"Researches enterprise accounts and drafts outreach"
When provided, replaces the agent's whole tool list. Prefer the abilities and connector endpoints.
When provided, replaces the agent's resource list.
Agent settings, grouped as the agent panel groups them. On PATCH, objects merge and arrays and scalars replace, so send only the sections you want to change. Unknown keys are dropped.
Setting this to false retires the agent: it disappears from GET /agents, and GET/PATCH /agents/{agent_id} return 404, so it cannot be reactivated through the API. This is not a pause switch — to stop an agent from running while keeping it reachable, disable its triggers instead.
When provided, transfers ownership of the agent to this team.
The version you last read. The update is refused with 409 agent_version_conflict if the agent changed since.
4
Response
The updated agent.
An agent and its whole configuration. Single-agent reads and every configuration write return this shape; the list endpoint omits the inlined collections.