Definition schema
Create accepts a strict Agent definition. Revise and preflight embed that same schema underdefinition.
Tool names must be unique. Harness must support requested initialization/Tools. Saved binding IDs are checked for tenant ownership and appropriate kinds; configuration validity is not a live execution receipt. Optional-at-start Tools still require their bindings when creating a Session. Agent tools are declarations in an array, whereas Session tools are name-to-connection mappings.
Create, list and read
POST /v1/agents returns 201 with id, name, definition, env_names, revision, archived_at, created_at, updated_at. Environment values are saved separately and not returned in definition. The initial revision is also recorded in revision history.
Save this minimal definition as agent-definition.json. It intentionally omits connection defaults:
GET /v1/agents returns 200, {agents:[...]}, ordered by creation time ascending, including archived templates, without pagination. Entries have the creation response fields. GET /v1/agents/{id} returns 200, the same fields plus revisions, ordered by revision descending. Each historical entry contains revision, name, definition, env_names and created_at. Missing/foreign Agent returns 404 agent_not_found.
/v1 and a suitable backend token. Creation has no idempotency key; repeated requests create separate templates. Inspect the list after a lost response before creating another.
Preflight an unsaved definition
POST /v1/agents/preflight accepts strict {definition,bindings}. The top-level bindings object requires sandbox_connection_id and model_connection_id UUIDs, with tools/connections maps defaulting to empty. It evaluates the definition using those explicit bindings; do not assume any definition.bindings automatically supplies them.
Save as agent-preflight.json, replacing both placeholder connection IDs:
Revise with optimistic concurrency
PUT /v1/agents/{id} accepts strict {expected_revision:positive_integer,definition:AgentDefinition}. Supply the latest observed revision and a complete replacement definition. This is not a field-wise PATCH. Omitted non-environment fields receive schema defaults rather than inheriting the previous definition.
Environment is the exception: omitting both variables and env preserves the old values; supplying either replaces the entire map; an explicit empty map clears it. The response reveals only names. Save the complete intended update as agent-revision.json:
409 agent_revision_changed; re-read and reconcile instead of blindly changing expected_revision. A lost successful response can cause that conflict on retry. Archived templates return 409 agent_archived. Existing Sessions retain their pinned revision and effective environment.
Copy a template
POST /v1/agents/{id}/copy accepts strict {name:string} of length 1–200. Success returns 201, a newly created Agent object with its own initial history. It copies the current source definition and decrypted effective environment into the new Agent; it does not return plaintext environment values. The new name replaces the source name. Current implementation permits copying an archived source, subject to current definition/binding validation.
Archive a template
POST /v1/agents/{id}/archive takes no required body and returns 200, {id,revision,archived_at}. Repetition preserves the first archive timestamp; it does not increment revision. No unarchive or hard-delete endpoint is defined here.
400 invalid_request; missing/foreign templates return 404 agent_not_found. Validation may fail before template lookup, so clients must inspect the actual error code. Other compatibility, environment, initialization and binding failures follow the shared definition/Session rules. Sources: Agent schemas and operations, routes and role checks. These are source-reviewed contracts, not fresh HTTP/database acceptance. Next: template workflow, HTTP overview.