> ## 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](https://vetta.sh/docs/concepts/agents.md) — 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 <id>` | Show an agent's current configuration (`--format yaml` to export). |
| `vetta agent update <id>` | Update an agent from flags or a file; creates a new version. |
| `vetta agent versions <id>` | List version history, newest first. `--limit <n>` keeps the newest n; there is no cursor, so read an older one with `agent version`. |
| `vetta agent version <id> <n>` | The full immutable config of one version. |
| `vetta agent rollback <id>` | Roll back to an earlier version (creates a **new** version with its config). |
| `vetta agent tools <id>` | Enable, disable, or configure **one** tool on a live agent. |
| `vetta agent identities <id>` | List personas granted to this agent. |
| `vetta agent delete <id>` | Delete an agent. |
| `vetta agent spend <id>` | Show metered spend, optionally by component. |
| `vetta agent computer <id>` | Show the agent's computer, or `null` before any session has needed one. |

`<id>` is the agent's `agt_` id, which `create` and `list` print. A name is not looked up; only `apply` (and `team --member`) match an agent by `name`.

## create

```bash theme={"system"}
vetta agent create \
  --name Refunder \
  --model z-ai/glm-5.3-flash \
  --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](https://vetta.sh/docs/concepts/model-router.md). |
| `--harness` | The [harness](https://vetta.sh/docs/how-managed-agents-is-built.md#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`](https://vetta.sh/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](https://vetta.sh/docs/concepts/budgets.md). |
| `--system` | System prompt. |
| `--window` | Default completion window: `immediate` \| `priority` \| `loose`. Only some models serve the non-default windows — check with [`vetta models list --window`](https://vetta.sh/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`](https://vetta.sh/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). |

> [!NOTE]
>
> **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](https://vetta.sh/docs/concepts/agents.md#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 agt_01j8rf6tq2m4vz9xkp3n7c5hwd --format yaml > refunder.agent.yaml
vetta agent update agt_01j8rf6tq2m4vz9xkp3n7c5hwd -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 agt_01j8rf6tq2m4vz9xkp3n7c5hwd --system "You process refunds. Confirm the order first."
vetta agent update agt_01j8rf6tq2m4vz9xkp3n7c5hwd -f refunder.agent.yaml
vetta agent versions agt_01j8rf6tq2m4vz9xkp3n7c5hwd --human
vetta agent version agt_01j8rf6tq2m4vz9xkp3n7c5hwd 4         # full immutable config of version 4
vetta agent rollback agt_01j8rf6tq2m4vz9xkp3n7c5hwd --to 4   # new version whose config == version 4
```

Pass `--expected-version <n>` 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.

`version <id> <n>` 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 agt_01j8rf6tq2m4vz9xkp3n7c5hwd --tool web_fetch --allow-domain docs.example.com --max-content-tokens 2000
vetta agent tools agt_01j8rf6tq2m4vz9xkp3n7c5hwd --tool generate_video --model bytedance/seedance-2.5 --permission ask
vetta agent tools agt_01j8rf6tq2m4vz9xkp3n7c5hwd --tool browser --disable
```

| Flag | Description |
| - | - |
| `--tool <name>` | **Required.** A [built-in](https://vetta.sh/docs/capabilities/tools.md#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 <p>` | `allow`, `ask`, or `deny`. `deny` means the tool is never offered to the model. |
| `--allow-domain <d>` | Repeatable. The closed list for `web_search` / `web_fetch`; nothing outside it is reachable. |
| `--block-domain <d>` | Repeatable. Always wins over `--allow-domain`. |
| `--max-content-tokens <n>` | How much of a fetched page may enter the context. |
| `--model <id>` | 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.<tool>.config`; see [Tools](https://vetta.sh/docs/capabilities/tools.md).

## spend

```bash theme={"system"}
vetta agent spend agt_01j8rf6tq2m4vz9xkp3n7c5hwd --by component
```

```json theme={"system"}
{
  "agent_id": "agt_01H...",
  "period": "month",
  "spent_micro_usd": 12418700,
  "period_start": "2026-08-01",
  "by_component": { "model": 11902000 }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.