An agent is a reusable configuration of a model, system prompt, toolkits, and skills. Each update auto-increments the version number; sessions lock to the version that was current when they were created.
Versioning
An agent tracks its configuration history with the integer version field. The behavior is as follows:
-
The update endpoint uses full-replacement semantics. On success,
versionauto-increments by 1. The request body must carry the current value as an optimistic lock; a mismatch returns 409. -
A session locks to the current
versionat creation time and is not affected by later updates. To query a historical version, useGET /agents/{agent_id}?version=N. -
Archive is a soft operation:
archived_atis set to the archive time. An archived agent cannot be used to create new sessions; existing sessions are unaffected.
Agent operations
|
Operation |
Endpoint |
Description |
|
|
Create an agent; initial |
|
|
|
Returns the latest version by default; pass |
|
|
|
Paginated list of agents under the workspace; archived agents are excluded by default. |
|
|
|
Full replacement; the request body must include |
|
|
|
Soft archive; cannot be used to create new sessions, existing sessions are unaffected. |
|
|
|
Paginated list of all historical versions of the agent. |