vetta agent

Manage 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 <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.
`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.

create

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.
`--harness`	The harness — 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`, which publishes every loop with what it can be admitted for.
`--budget-usd` / `--max-task-usd` / `--budget-period`	Budget (all required). See 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`.
`--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`, 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 for the full schema.

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

vetta agent apply -f refunder.agent.yaml            # one agent
vetta agent apply -f ./agents/                        # every *.agent.yaml in a dir

update, versions & rollback

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 <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. versions --version <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.

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 <name>`	Required. A built-in, 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.

spend

vetta agent spend Refunder --by component

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

Getting started

Building & running

Organization

Identity

Commands

create

Config as a file

apply (declarative / CI)

update, versions & rollback

tools

spend

​Commands

​create

​Config as a file

​apply (declarative / CI)

​update, versions & rollback

​tools

​spend

Commands

create

Config as a file

apply (declarative / CI)

update, versions & rollback

tools

spend