Agent
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. |