> ## 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. # vetta agent > Create, version, run, and inspect agents. Manage [agents](/docs/concepts/agents) — reusable, versioned configurations. ## Commands | Command | Description | | ------------------------------ | ---------------------------------------------------------------------------- | | `vetta agent create` | Create an agent from flags or a `.agent.yaml` file (requires a budget). | | `vetta agent apply` | Declaratively create-or-update from a file, keyed by `name` (for CI). | | `vetta agent list` | List agents in the org. | | `vetta agent show ` | Show an agent's current configuration (`--format yaml` to export). | | `vetta agent update ` | Update an agent from flags or a file; creates a new version. | | `vetta agent versions ` | List version history. | | `vetta agent version ` | The full immutable config of one version. | | `vetta agent rollback ` | Roll back to an earlier version (creates a **new** version with its config). | | `vetta agent tools ` | Enable, disable, or configure **one** tool on a live agent. | | `vetta agent identities ` | List personas granted to this agent. | | `vetta agent delete ` | Delete an agent. | | `vetta agent spend ` | Show metered spend, optionally by component. | ## create ```bash theme={"system"} vetta agent create \ --name Refunder \ --model zai-org/GLM-5.2-FP8 \ --harness pi \ --skill refund-policy@3 \ --tools bash,browser,read_skill,publish_file \ --budget-usd 50 --max-task-usd 5 --budget-period month \ --window immediate \ --output-schema ./refund.schema.json \ --system "You process refunds." ``` | Flag | Description | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name` | Human-readable name (required). | | `--model` | Model ID (required). See [Model router](/docs/concepts/model-router). | | `--harness` | The [harness](/docs/how-vetta-is-built#the-three-layers) — the agent loop this agent runs: how it manages context, picks tools and resumes a long task. Default `pi`. The harness catalogue is [`GET /v1/harnesses`](/docs/api/harnesses), which publishes every loop with what it can be admitted for. | | `--budget-usd` / `--max-task-usd` / `--budget-period` | Budget (all required). See [Budgets](/docs/concepts/budgets). | | `--system` | System prompt. | | `--window` | Default completion window: `immediate` \| `priority` \| `loose`. Only some models serve the non-default windows — check with [`vetta models list --window`](/docs/cli/models#list). | | `--computer` | Computer ID or name. **Not available yet** — an agent carries no computer on the wire; passing it is an error rather than a silent no-op. | | `--skill` | Attach a skill (repeatable). `slug` floats to latest; `slug@N` pins an immutable version. | | `--tools` | Comma-separated tool names. | | `--output-schema` | Path to a JSON Schema file; the default schema for a session's typed `structured_output`. | | `--identity` | **Not accepted here** — it exits `2`. A persona is granted with [`vetta identity attach`](/docs/cli/identity#granting-a-persona-to-an-agent), not set on the agent. | | `-f`, `--file` | Read the full config from a `.agent.yaml` file instead of flags (also accepts stdin). | **Money.** `--budget-usd` (and `--max-task-usd`) take a decimal-dollar string and are converted client-side to integer micro-USD; the wire field is `cap_micro_usd` (`1 USD = 1_000_000` micro-USD). Amounts in JSON output are integer `*_micro_usd`. ## Config as a file The declarative way to manage an agent is a checked-in **`.agent.yaml`** — the whole config in one reviewable, diffable file. `create`, `update`, and `apply` all read it; `show --format yaml` writes it back out. See [Define an agent as a file](/docs/concepts/agents#define-an-agent-as-a-file) for the full schema. ```bash theme={"system"} # create from a file (or stdin) vetta agent create -f refunder.agent.yaml vetta agent create < refunder.agent.yaml # export the live config to a file, edit, then update vetta agent show Refunder --format yaml > refunder.agent.yaml vetta agent update Refunder -f refunder.agent.yaml ``` ## apply (declarative / CI) `apply` upserts an agent **by `name`**: it creates one if none exists, otherwise updates it, **omitting `--expected-version`** so the file is the source of truth (last write wins). This is the GitOps path — a CI job that syncs your checked-in definitions. ```bash theme={"system"} vetta agent apply -f refunder.agent.yaml # one agent vetta agent apply -f ./agents/ # every *.agent.yaml in a dir ``` ## update, versions & rollback ```bash theme={"system"} vetta agent update Refunder --system "You process refunds. Confirm the order first." vetta agent update Refunder -f refunder.agent.yaml vetta agent versions Refunder --human vetta agent version Refunder 4 # full immutable config of version 4 vetta agent rollback Refunder --to 4 # new version whose config == version 4 ``` Pass `--expected-version ` for optimistic concurrency; a mismatch exits non-zero (HTTP 409, `version_conflict`). Omit it (or use `apply`) for unconditional, last-write-wins updates. `rollback` also accepts `--expected-version` to guard against a concurrent change. `versions --version ` returns the full immutable snapshot (model, system, window, tools, skills, budget, `created_by`, …) so you can diff two versions before rolling back. ## tools `--tools` on `create` declares the whole enabled set. To change **one** tool on an agent that already exists — including the tool's own settings — use `agent tools`. It reads the current configuration and sends it back with that one entry changed, so nothing else is disturbed. ```bash theme={"system"} vetta agent tools Refunder --tool web_fetch --allow-domain docs.example.com --max-content-tokens 2000 vetta agent tools Refunder --tool generate_video --model bytedance/seedance-2.5 --permission ask vetta agent tools Refunder --tool browser --disable ``` | Flag | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `--tool ` | **Required.** A [built-in](/docs/capabilities/tools#built-in-tools), or a namespaced connection/MCP tool such as `tracker.get_issue`. | | `--enable` · `--disable` | Turn the tool on or off. A tool named for the first time is created enabled, at the toolset's default permission. | | `--permission

` | `allow`, `ask`, or `deny`. `deny` means the tool is never offered to the model. | | `--allow-domain ` | Repeatable. The closed list for `web_search` / `web_fetch`; nothing outside it is reachable. | | `--block-domain ` | Repeatable. Always wins over `--allow-domain`. | | `--max-content-tokens ` | How much of a fetched page may enter the context. | | `--model ` | Repeatable. The default model for `generate_image` / `generate_video` (the first named); the agent may still name any model the provider publishes. | Pass at least one of them; a command that would change nothing exits `2` rather than minting an identical version. Config flags **merge** — setting a cap does not clear a domain filter you set earlier. The same settings can be written declaratively in a `.agent.yaml` under `tools.configs..config`; see [Tools](/docs/capabilities/tools). ## spend ```bash theme={"system"} vetta agent spend Refunder --by component ``` ```json theme={"system"} { "agent_id": "agt_01H...", "period": "month", "spent_micro_usd": 12418700, "period_start": "2026-08-01", "by_component": { "model": 11902000 } } ```