Skip to navigation

Update agent

Update an existing agent. Supports partial updates — only provided fields are changed. Both config and externalConfig are merged onto the stored values, so a partial write preserves keys it omits (notably externalConfig.protocol and externalConfig.cachedAgentCard). To REMOVE a value, send it explicitly as null: a null field clears that field, and externalConfig: null clears the whole object. Nested values replace atomically — sending auth replaces the entire auth block, so switching auth type cannot reuse the previous credential. Agent management responses return a configured auth.credentials value as <redacted>; echoing that placeholder on an update preserves the stored credential only when auth.type is unchanged. Repointing an A2A external agent (endpoint, agentCardUrl, protocol, transport or deviceId) re-fetches and caches the agent card from its new location, as create does, and rejects the update with 400 or 502 when no card can be fetched; an explicitly sent cachedAgentCard is kept as sent, and switching to the runtype-stream protocol discards the card. Moving externalConfig.endpoint to a different host additionally requires re-sending externalConfig.auth: a stored credential is never carried to a host it was not configured against, so a repoint that omits auth is rejected with 400.

Authentication

AuthorizationBearer
API key or Clerk session token

Path parameters

idstringRequired

Headers

if-matchstringOptional
The updatedAt value last loaded. A stale revision returns 409 without saving.

Request

This endpoint expects an object.
agentTypeenumOptional
Allowed values:
capabilityChangesobjectOptional

Capability additions and removals committed with the definition and its draft snapshot. If-Match guards the entire save.

claudeManagedConfigobjectOptional
configobjectOptional
descriptionstringOptional
externalConfigobject or nullOptional
iconstringOptional<=50 characters
maxTurnsintegerOptional1-100
namestringOptional>=1 character
primaryFlowIdanyOptionalDeprecated

primaryFlowId is retired: primary-flow agents were removed (ADR 0024). Attach the flow to the agent as a runtime tool ({ toolType: ‘flow’, flowId }) or dispatch the flow directly via POST /v1/dispatch.

Response

Agent updated
agentTypestring
claudeManagedConfigmap from strings to any or null
configmap from strings to any or null
configHashstring or null
createdAtstring
descriptionstring or null
draftVersionIdstring or null
externalConfigmap from strings to any or null

External-agent configuration. Configured auth.credentials values are write-only and returned as <redacted>, never plaintext.

healthStatusstring or null
iconstring or null
idstring
lastHealthCheckAtstring or null
lastModifiedSourcestring or null
namestring
organizationIdstring or null
publishedVersionIdstring or null
savedVersionIdstring or null
The snapshot committed with this update, or the current draft snapshot for an unchanged definition. Save repairs a missing snapshot without changing the definition revision. Definition, capability, and snapshot failures roll back together.
statusstring
updatedAtstring
userIdstring
_warningslist of stringsOptional
dashboardUrlstringOptional
sandboxCapabilityIssueslist of objectsOptional

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
500
Internal Server Error