Update agent
Update an agent’s settings. Only fields in the body change; metadata merges section by section (objects merge, arrays and scalars replace), except metadata.model_settings, which replaces the saved object whole. Send every model-settings field you want to keep.
Which changes have their own endpoints?
Which changes have their own endpoints?
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.To change incognito enforcement, use Set agent incognito. This endpoint rejects top-level incognito with 400 invalid_request and cannot change enforcement through metadata.
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
A personal API key or an OAuth 2.0 access token. Personal API keys also require the x-auth-key header with your user ID.
Path Parameters
Body
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.
Response
The updated agent.