Agents

An agent is a reusable, versioned configuration. It bundles the model, harness, system prompt, tools, skills, computer, and budget that shape how the agent behaves during a session. You create an agent once and reference it by ID each time you start a session — the agent is the definition, the session is a single run of it.

Create an agent

vetta agent create \
  --name "Refunder" \
  --model zai-org/GLM-5.2-FP8 \
  --harness pi \
  --computer box \
  --skill refund-policy \
  --budget-usd 50 --max-task-usd 5 --budget-period month \
  --window immediate \
  --system "You process refunds."

const computer = await vetta.computers.create({ name: "box", size: "medium" });

const agent = await vetta.agents.create({
  name: "Refunder",
  model: "zai-org/GLM-5.2-FP8",
  harness: "pi",
  computer: computer.id,
  skills: ["refund-policy"],
  budget: { capMicroUsd: "50000000", maxTaskMicroUsd: "5000000", period: "month" }, // $50 / $5
  window: "immediate",
  system: "You process refunds.",
});

curl -fsSL https://api.vetta.sh/v1/agents \
  -H "authorization: Bearer $VETTA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Refunder",
    "model": "zai-org/GLM-5.2-FP8",
    "harness": "pi",
    "computer": "cmp_...",
    "skills": ["refund-policy"],
    "budget": { "cap_micro_usd": 50000000, "max_task_micro_usd": 5000000, "period": "month" },
    "window": "immediate",
    "system": "You process refunds."
  }'

The response echoes your configuration and adds id, current_version, created_at, updated_at, and archived_at. current_version starts at 1 and increments each time an update changes the agent.

Define an agent as a file

An agent is a declarative configuration, so the recommended way to manage it is a checked-in .agent.yaml file. The whole config — model, harness, prompt, tools, budget, policies — lives in one file you can review, diff, and version-control alongside your code. The CLI reads it on create, update, and apply.

refunder.agent.yaml

name: Refunder
description: Processes customer refunds within policy and escalates edge cases.
model:
  id: zai-org/GLM-5.2-FP8
  effort: medium
harness: pi
window: immediate
system: |
  You process refunds. Always confirm the order first, then apply the
  refund-policy skill. Escalate anything ambiguous rather than guessing.
# Or keep the prompt in its own file:
# system_file: ./refunder.system.md
computer: box            # a computer name or id
skills:
  - refund-policy
  - escalation-matrix
tools:
  default_config:
    permission: allow
  configs:
    bash:   { enabled: true, permission: ask }
    remove: { enabled: true, permission: ask }
budget:
  # authored in dollars for readability; the CLI converts to integer micro-USD on the wire
  cap_usd: 50
  max_task_usd: 5
  period: month
policies:
  primitives: { computer: true, browser: true, files: true }
  connections: { mode: allowlist, list: [crm, tracker] }
on_idle: https://acme.dev/hooks/refunder-idle
metadata:
  team: support

# from a file, or piped over stdin
vetta agent create -f refunder.agent.yaml
vetta agent create < refunder.agent.yaml

# create-or-update by name; omits version → last write wins.
# Ideal for a CI job that syncs checked-in agent definitions.
vetta agent apply -f refunder.agent.yaml

# round-trip: write the live config back out as YAML
vetta agent show Refunder --format yaml > refunder.agent.yaml

apply is the GitOps path. It upserts by name and omits version, so the checked-in file is the source of truth (last write wins) — exactly what a CI apply loop wants. For interactive edits where you don’t want to clobber a concurrent change, use update with --expected-version (a mismatch is a 409). See versioning below.

Agent, session, run

An agent is a durable definition; work happens in sessions that reference it. One agent backs many sessions and cron deployments, each independently budgeted, streamed, and controlled.

Versioning

Every change to an agent’s configuration produces a new immutable version. A version is a frozen snapshot of the whole config — model, system prompt, tools, skills, window, budget, and metadata — identified by an integer that increments from 1. Nothing about a past version ever mutates, which is what lets a long-running session or a scheduled deployment keep behaving exactly as it did the day it started.

Optimistic concurrency. Supply expected_version to apply the update only if nothing else changed it in the meantime; a mismatch returns 409 with code: "version_conflict". Omit it to apply unconditionally (last write wins) — the path a declarative apply loop uses.
Omitted fields are preserved. Send only what you want to change.
Array fields (tools, skills, identity) are fully replaced by the new array.
No-op detection. If an update produces no change, no new version is created.
Sessions and deployments pin a version. A running session keeps the config it started with; a deployment can pin a specific agent_version for staged rollout. New versions apply only to new work.

Each version is retrievable in full, so you can read or diff exactly what a past run used, and you can roll back by promoting a past version — rollback creates a new version whose config equals the target, rather than mutating history.

vetta agent update Refunder --system "You process refunds. Always confirm the order first."
vetta agent versions Refunder                 # full history, newest first
vetta agent versions Refunder --version 2     # the full config snapshot of v2
vetta agent rollback Refunder --to 2          # creates a new version equal to v2

const updated = await vetta.agents.update(agent.id, {
  expectedVersion: agent.current_version,     // 409 version_conflict on a stale value
  system: "You process refunds. Always confirm the order first.",
});

const v2 = await vetta.agents.getVersion(agent.id, 2); // immutable snapshot
await vetta.agents.rollback(agent.id, { toVersion: 2 });

Lifecycle

Operation	Behavior
Update	Generates a new version when the configuration changes; optimistic-concurrency via `expected_version`.
List versions	Returns the full version history, newest first.
Get version	Returns the immutable config snapshot of a specific version.
Roll back	Creates a new version whose config equals a past version.
Archive	Makes the agent read-only. Existing sessions keep running; new sessions cannot reference it.
Spend	Returns the agent’s metered spend, optionally broken down by component.

Configuration reference

string

required

A human-readable name for the agent.

string | object

required

The model that powers the agent. A model ID string, or an object such as { "id": "zai-org/GLM-5.2-FP8", "effort": "high" }. See Model router & inference.

string

default:"pi"

The harness — the agent loop that drives each turn. pi is the only value today and the default. The runtime beneath it (durability, tools, budget, policy) is the same whichever harness you pick.

object

required

Spend limits, in integer micro-USD on the wire. An agent cannot be created without one. See Budgets.

Show budget

integer

required

Total cap for the budget period, in micro-USD.

integer

required

Per-task ceiling, in micro-USD; a single session cannot exceed this.

string

required

day, week, or month.

string

A system prompt that defines the agent’s behavior and persona. Distinct from the user messages that describe the work.

string

default:"immediate"

Default completion window: immediate, priority, or loose. Overridable per session.

string

ID of a computer the agent runs on.

string[]

Skills that supply domain context with progressive disclosure.

object

The tools available to the agent, as a single toolset object: a default_config plus per-tool configs, each entry { enabled, permission } where permission is allow, ask, or deny. See Policies. Built-ins are enabled by capability; MCP and connection tools register under the same keys.

object[]

MCP servers the agent can reach, referenced by mcp_toolset.

string[]

One or more identities the agent can act as.

object

Phase 3. A coordinator declaration listing the agents this agent can delegate to.

object

A default JSON Schema for a structured result. When set, a session goes idle carrying a typed structured_output; a session can override it per run.

string

A description of what the agent does.

object

Arbitrary key-value pairs for your own tracking.

Next: runtime & durability

How the harness drives each turn, and how the runtime makes it durable.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Create an agent

Define an agent as a file

Agent, session, run

Versioning

Lifecycle

Configuration reference

Next: runtime & durability

​Create an agent

​Define an agent as a file

​Agent, session, run

​Versioning

​Lifecycle

​Configuration reference

Next: runtime & durability

Create an agent

Define an agent as a file

Agent, session, run

Versioning

Lifecycle

Configuration reference