Update an agent
/api/v1/agents/{agent_id}Update selected fields of an agent configuration. Omitted fields are unchanged. Collection fields such as configured_tools and mcp_server_ids replace the complete collection when present; send an empty collection to clear one.
Send expected_updated_at from the latest agent response to protect a read-modify-write cycle. A stale value answers 409; retrieve the current configuration and reconcile instead of blindly retrying. Every successful change creates a new immutable configuration revision.
Required access
Credentials: service principal, delegated token, user session
Scope: agents:edit
A delegated token may update only an agent owned by its user. A service principal may update an organization-shared agent when its scope and optional resource allowlist cover that agent; it cannot update a private agent.
An organization-owned automation key, prefixed gsmc_sk_. Already bound to one organization, so it needs no X-Org-Id header. It carries no user identity: it never reaches a private resource however it is scoped, and a run it starts has no user for an interactive tool to reach.
In: header
Path Parameters
uuidHeader Parameters
Selects the active organization for a credential that belongs to more than one. Service-principal keys are bound to a single organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request body for updating an agent.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/api/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "system_prompt": "Return blockers with file and line evidence.", "thinking_level": "high", "expected_updated_at": "2026-08-12T09:30:00Z" }'{ "agent": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d", "visibility": "org_shared", "name": "string", "description": "string", "executor_type": "claude", "model": "string", "system_prompt": "string", "thinking_level": "none", "temperature": 0.1, "execution_environment": "guest_vm", "computer_use_enabled": false, "environment_config": {}, "input_schema": {}, "output_schema": {}, "is_active": true, "auto_respond": false, "owning_team_id": "1e618706-c399-4dc7-864c-009ddf950b84", "allowed_invocables": [ "string" ], "knowledge_scope": { "folder_ids": [ "c9c54c2c-7793-4b70-8b93-7e3771bbc0c0" ], "file_ids": [ "1c0f12fe-c5bf-4fbd-ba1b-466cb232eca5" ] }, "avatar_blob_name": "string", "avatar_sas_url": "string", "avatar_expires_at": "2019-08-24T14:15:22Z", "configured_tools": [ { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true } ], "hidden_configured_tool_count": 0, "allowed_tools": [ "string" ], "mcp_server_ids": [ "6645753c-0a13-4667-8dd3-d80a8e4fd76f" ], "tool_approval_modes": { "property1": "auto", "property2": "auto" }, "unattended_preapproved_tools": [ "string" ], "config_revision": 0, "config_digest": "0000000000000000000000000000000000000000000000000000000000000000", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}