> ## Documentation Index > Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Agents > Create, version, run, and inspect reusable agent configurations. An **agent** is a reusable, versioned configuration: a model, a system prompt, a set of tools and skills, a completion window, and a budget. Sessions and deployments run against an agent. Every update is captured as an immutable [agent version](#versioning) with optimistic concurrency. ## The agent object Unique id (e.g. `agt_01H...`). Always `agent`. Human-readable name. The [harness](/docs/how-vetta-is-built#the-three-layers) — the agent loop. [`GET /v1/harnesses`](/docs/api/harnesses) publishes the set, what each one can be admitted for, and whether it holds a sandbox between turns. Model identifier, e.g. `zai-org/GLM-5.2-FP8`. See [the model router](/docs/concepts/model-router). Default [completion window](/docs/concepts/completion-window): `immediate | priority | loose`. System prompt. The toolset configuration. See [Tools](/docs/capabilities/tools). Default `{ permission }` applied to every tool unless overridden. `permission` ∈ `allow` (run silently) · `ask` (pause → `tool.confirm` [event](/docs/api/events)) · `deny` (tool is not offered to the model at all). Per-tool overrides keyed by tool name — a [built-in](/docs/capabilities/tools#built-in-tools) (`bash`, `browser`, `web_search`, `generate_image`, …) or a namespaced `.`. Each entry is `{ enabled, permission, config? }`. Attached MCP servers the agent may call. Attached [skill](/docs/api/skills) references. Each entry is a slug or id, optionally suffixed `@version` to pin an immutable version (e.g. `refund-policy@3`). An unpinned reference resolves to the skill's latest version at session start. Whether the agent may coordinate sub-agents. Required spend controls. Ceiling for the period, in micro-USD. Ceiling for a single session/task, in micro-USD. Reset window: `day | week | month`. Optional JSON Schema the agent's final result must satisfy. Sessions inherit it as their default and may override it per run. See [Structured outputs](/docs/capabilities/structured-outputs). Whether a run that cannot produce an object conforming to `output_schema` is a failure rather than a plain-text answer. Sessions inherit it and may override it per run. Optional longer description. Arbitrary key/value pairs you attach. Monotonic version counter. Pass this as `expected_version` on update for optimistic concurrency. Creation timestamp. ## Create an agent `POST /v1/agents` → `201 Created`. Human-readable name. Model identifier. Spend controls (`cap_micro_usd`, `max_task_micro_usd`, `period`). Agents cannot be created without a budget. Defaults to `"pi"`. A harness the deploy cannot run is refused when the session starts, naming the field — see [harnesses](/docs/api/harnesses). Default completion window (`immediate | priority | loose`). Defaults to `immediate`. System prompt. Toolset config — a `default_config` plus per-tool `configs`. See [the toolset schema](/docs/capabilities/tools). MCP servers to attach. Skills to attach. Each entry is a slug/id, optionally `@version` to pin (e.g. `refund-policy@3`). Enable sub-agent coordination. Defaults to `false`. JSON Schema the final result must satisfy. Defaults to `null`. See [Structured outputs](/docs/capabilities/structured-outputs). Treat a non-conforming result as a failure rather than answering in prose. Defaults to `false`; needs an `output_schema`. Longer description. Defaults to `null`. Arbitrary metadata. ```bash cURL theme={"system"} curl -fsSL https://api.vetta.sh/v1/agents \ -H "authorization: Bearer sk_live_..." \ -H "content-type: application/json" \ -H "idempotency-key: $(uuidgen)" \ -d '{ "name": "Refunder", "model": "zai-org/GLM-5.2-FP8", "window": "immediate", "system": "You process refunds.", "tools": { "default_config": { "permission": "allow" }, "configs": { "browser": { "enabled": true, "permission": "ask", "config": { "allowed_domains": ["*.example.com"] } } } }, "skills": ["refund-policy@3"], "budget": { "cap_micro_usd": 50000000, "max_task_micro_usd": 5000000, "period": "month" } }' ``` ```json Response theme={"system"} { "id": "agt_01H8XK...", "object": "agent", "name": "Refunder", "harness": "pi", "model": "zai-org/GLM-5.2-FP8", "window": "immediate", "system": "You process refunds.", "tools": { "default_config": { "permission": "allow" }, "configs": { "browser": { "enabled": true, "permission": "ask", "config": { "allowed_domains": ["*.example.com"] } } } }, "mcp_servers": [], "skills": ["refund-policy@3"], "multiagent": false, "budget": { "cap_micro_usd": 50000000, "max_task_micro_usd": 5000000, "period": "month" }, "output_schema": null, "description": null, "metadata": {}, "current_version": 1, "created_at": "2026-08-20T17:00:00Z" } ``` ## Retrieve an agent `GET /v1/agents/{id}` → `200 OK` with the current configuration, including `current_version`. ```bash theme={"system"} curl -fsSL https://api.vetta.sh/v1/agents/agt_01H8XK... \ -H "authorization: Bearer sk_live_..." ``` ## List agents `GET /v1/agents` → `200 OK`, cursor-paginated. See [Pagination](/docs/api/pagination). ```json Response theme={"system"} { "data": [ { "id": "agt_01H...", "name": "Refunder", "current_version": 3 } ], "has_more": false, "next_cursor": null } ``` ## Update an agent `PATCH /v1/agents/{id}` → `200 OK`. Applies a partial update and creates a new immutable version. A no-op update creates no new version. Updates use **optimistic concurrency**: pass the `expected_version` you read. If it no longer matches `current_version`, the API returns `409` with code `version_conflict` and applies nothing. **Omitting `expected_version`** performs an unconditional, last-write-wins apply — use this for declarative CI that reconciles an `.agent.yaml` toward a desired state. The `current_version` you last read. Omit for an unconditional apply. Any subset of the mutable fields (`name`, `system`, `model`, `window`, `tools`, `mcp_servers`, `skills`, `multiagent`, `budget`, `output_schema`, `structured_output_required`, `description`, `metadata`). Renaming is deliberately not a config change: a patch that only sets `name` mints no new version. ```bash theme={"system"} curl -fsSL -X PATCH https://api.vetta.sh/v1/agents/agt_01H8XK... \ -H "authorization: Bearer sk_live_..." \ -H "content-type: application/json" \ -d '{ "expected_version": 1, "system": "You process refunds. Confirm the order first." }' ``` Returns the full [agent object](#the-agent-object) at its new version: ```json Response theme={"system"} { "id": "agt_01H8XK...", "object": "agent", "current_version": 2, "system": "You process refunds. Confirm the order first." } ``` ### Version conflict (409) If another writer advanced the version, you get: ```json 409 Conflict theme={"system"} { "error": { "type": "conflict", "code": "version_conflict", "message": "expected_version 1 does not match current_version 2.", "request_id": "req_01H9ZZ...", "param": "expected_version" } } ``` Refetch the agent, re-apply your change against the fresh `current_version`, and retry. ## The agent-version object Each update snapshots the full config into an immutable **agent version**. Versions never change once written. Monotonic version number. When this version was created. The principal that created the version — `{ "type": "user" | "key" | "system", "id": "..." }`. Model identifier at this version. System prompt at this version. Completion window at this version. Toolset config at this version. MCP servers at this version. Skill references at this version. Sub-agent coordination flag at this version. Budget at this version. Output schema at this version. Whether a conforming object was required at this version. Description at this version. Metadata at this version. ## List versions `GET /v1/agents/{id}/versions` → `200 OK`. The full immutable version history in one page: this list is **not** paginated — `limit` and `after` are ignored, and the reply always carries `has_more: false`, `next_cursor: null`. Each row is a whole [agent-version object](#the-agent-version-object); versions are addressed by their `version` number, not by an id. ```json Response theme={"system"} { "data": [ { "version": 2, "created_at": "2026-08-20T18:00:00Z", "created_by": { "type": "user", "id": "usr_01H..." }, "system": "You process refunds. Confirm the order first." }, { "version": 1, "created_at": "2026-08-20T17:00:00Z", "created_by": { "type": "user", "id": "usr_01H..." }, "system": "You process refunds." } ], "has_more": false, "next_cursor": null } ``` ## Retrieve a version `GET /v1/agents/{id}/versions/{n}` → `200 OK` with the full [agent-version object](#the-agent-version-object) for version `n`. Use it to inspect or diff a past configuration. ```bash theme={"system"} curl -fsSL https://api.vetta.sh/v1/agents/agt_01H8XK.../versions/1 \ -H "authorization: Bearer sk_live_..." ``` ```json Response theme={"system"} { "version": 1, "created_at": "2026-08-20T17:00:00Z", "created_by": { "type": "user", "id": "usr_01H..." }, "model": "zai-org/GLM-5.2-FP8", "system": "You process refunds.", "window": "immediate", "tools": { "default_config": { "permission": "allow" }, "configs": {} }, "mcp_servers": [], "skills": ["refund-policy@3"], "multiagent": false, "budget": { "cap_micro_usd": 50000000, "max_task_micro_usd": 5000000, "period": "month" }, "output_schema": null, "structured_output_required": false, "description": null, "metadata": {} } ``` ## Roll back to a version `POST /v1/agents/{id}/rollback` → `200 OK`. Creates a **new** version whose config equals an earlier one — history is never rewritten. Returns the full [agent object](#the-agent-object) at that new version. The version whose config to restore. The `current_version` you last read, for optimistic concurrency. Omit for an unconditional rollback. ```bash theme={"system"} curl -fsSL https://api.vetta.sh/v1/agents/agt_01H8XK.../rollback \ -H "authorization: Bearer sk_live_..." \ -H "content-type: application/json" \ -d '{ "to_version": 1, "expected_version": 2 }' ``` ```json Response theme={"system"} { "id": "agt_01H8XK...", "object": "agent", "current_version": 3 } ``` ## Spend `GET /v1/agents/{id}/spend` → `200 OK`. Metered spend for the current budget period, in micro-USD, optionally broken down by component with `?by=component`. ```json Response theme={"system"} { "agent_id": "agt_01H8XK...", "period": "month", "spent_micro_usd": 12418700, "by_component": { "model": 11902000, "computer": 481000, "search": 6474, "media": 390000 } } ``` ## Delete an agent `DELETE /v1/agents/{id}` → `200 OK`. Removes the agent. Version history is retained for existing sessions. ```bash theme={"system"} curl -fsSL -X DELETE https://api.vetta.sh/v1/agents/agt_01H8XK... \ -H "authorization: Bearer sk_live_..." ``` ```json Response theme={"system"} { "id": "agt_01H8XK...", "object": "agent", "deleted": true } ``` Create a session to run an agent directly.