Edit or archive a saved agent, writing a new revision.

PATCH/o/{org}/agents/{agent}
View .md

If-Match must carry the current revision (the ETag from a read). {"archive": true} archives at the current revision and ignores every other field; there is no unarchive. Otherwise omitted fields keep their current values, the merged config is re-validated against today's catalog (or the catalog_revision sent), and a new revision is written, even when only name/description changed. handle and harness are immutable.

Authenticate with a signed-in session token (an API key cannot call this route).

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

agentstringrequired

The saved agent's id (UUID). Handles are not accepted here.

Format uuid

Headers

If-Matchstringrequired

Current revision as an entity tag ("3", W/"3" or bare 3).

Request body

Any subset. handle or harness present is 422 IMMUTABLE_FIELD.

archivebooleanoptional

true archives and ignores every other field.

namestringoptional
at most 80 characters
descriptionstring | nulloptional

null clears it.

at most 500 characters
instructionsstringoptional
catalog_revisionstringoptional

Defaults to the current catalog revision.

runtimeobject | objectoptional
1 fields
selectionstringrequired
defaultsobjectoptional

Merged key by key over the current defaults.

3 fields
modelSavedAgentModeloptional
2 fields
selectionstringrequired
idstringrequired

A model id the harness lists in GET /o/{org}/agents/available.

at most 200 characters
effortstring | nulloptional
speedstringoptional
One ofstandardfast
connection_refsarray of SavedAgentConnectionRefoptional
2 item fields
kindstringrequired
One ofoauthmcp
idstringrequired
capabilitiesobjectoptional

Merged key by key over the current capabilities.

2 fields
browserbooleanoptional
computerbooleanoptional
toolsobject | objectoptional
1 fields
modestringrequired
networkobject | objectoptional
1 fields
modestringrequired
pluginsarray of objectoptional
1 item fields
catalog_idstringrequired

Responses

200The agent at its new revision (or, for archive, at the unchanged revision with archived: true).
idstringrequired
Format uuid
namestringrequired
handlestringrequired
descriptionstringrequired
harnessstringrequired

Launch-boundary managed harnesses.

One ofclaudecodexopencode
revisionintegerrequired
min 1
archivedbooleanrequired
sourceobject | object | nullrequired
configSavedAgentConfigrequired

The desired configuration stored with one revision.

10 fields
harnessstringrequired

Launch-boundary managed harnesses.

One ofclaudecodexopencode
catalog_revisionstringrequired
runtimeobject | objectrequired
1 fields
selectionstringrequired
defaultsobjectrequired
3 fields
modelSavedAgentModelrequired
2 fields
selectionstringrequired
idstringrequired

A model id the harness lists in GET /o/{org}/agents/available.

at most 200 characters
effortstring | nullrequired
speedstringrequired
One ofstandardfast
instructionsstringrequired
connection_refsarray of SavedAgentConnectionRefrequired
2 item fields
kindstringrequired
One ofoauthmcp
idstringrequired
capabilitiesobjectrequired
2 fields
browserbooleanrequired
computerbooleanrequired
toolsobject | objectrequired
1 fields
modestringrequired
networkobject | objectrequired
1 fields
modestringrequired
pluginsarray of objectrequired
1 item fields
catalog_idstringrequired
resolved_at_saveSavedAgentResolvedrequired

What the config resolved to against the catalog when this revision was saved.

9 fields
modelstringrequired
effortstring | nullrequired
speedstringrequired
One ofstandardfast
harness_versionstring | nullrequired
tool_idsarray of string | nullrequired
pluginsarray of objectrequired
3 item fields
catalog_idstringrequired
versionstringrequired
digeststringrequired
runtime_idstring | nullrequired
catalog_revisionstringrequired
pin_guaranteebooleanrequired
created_atstringrequired
Format date-time
updated_atstringrequired
Format date-time
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such agent for the caller (NOT_FOUND).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
412If-Match is not the current revision, a concurrent write won, or the agent is already archived (STALE_ETAG).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
422Body refused: IMMUTABLE_FIELD (handle or harness sent), or any create-time validation code (see createSavedAgent), including CONNECTION_NOT_OWNED.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
428If-Match missing or unparseable (IF_MATCH_REQUIRED).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional