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

> A reusable, versioned configuration that defines an agent's persona and capabilities.

An **agent** is a reusable, versioned configuration. It bundles the model, [harness](https://vetta.sh/docs/how-managed-agents-is-built.md#the-three-layers), system prompt, tools, skills, [computer](https://vetta.sh/docs/computer/index.md), and [budget](https://vetta.sh/docs/concepts/budgets.md) that shape how the agent behaves during a [session](https://vetta.sh/docs/concepts/sessions.md). 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

```bash CLI theme={"system"}
vetta agent create \
  --name "Refunder" \
  --model z-ai/glm-5.3-flash \
  --harness pi \
  --skill refund-policy \
  --budget-usd 50 --max-task-usd 5 --budget-period month \
  --window immediate \
  --system "You process refunds."
```

```typescript TypeScript theme={"system"}
const agent = await vetta.agents.create({
  name: "Refunder",
  model: "z-ai/glm-5.3-flash",
  harness: "pi",
  skills: ["refund-policy"],
  budget: { capMicroUsd: "50000000", maxTaskMicroUsd: "5000000", period: "month" }, // $50 / $5
  window: "immediate",
  system: "You process refunds.",
});
```

```bash cURL theme={"system"}
curl -fsSL https://api.vetta.sh/v1/agents \
  -H "authorization: Bearer $VETTA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Refunder",
    "model": "z-ai/glm-5.3-flash",
    "harness": "pi",
    "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 — lives in one file you can review, diff, and version-control alongside your code. The CLI reads it on `create`, `update`, and `apply`.

```yaml refunder.agent.yaml theme={"system"}
name: Refunder
description: Processes customer refunds within policy and escalates edge cases.
model: z-ai/glm-5.3-flash
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
skills:
  - refund-policy
  - escalation-matrix
tools:
  default_config:
    permission: allow
  configs:
    bash:    { enabled: true, permission: ask }
    browser: { enabled: true, permission: allow, config: { allowed_domains: [shop.example.com], allow_writes: true } }
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
# who it may hand work to (default true = any agent of the organization)
handoffs: [escalations-desk]
metadata:
  team: support
```

```bash Create from file theme={"system"}
# from a file, or piped over stdin
vetta agent create -f refunder.agent.yaml
vetta agent create < refunder.agent.yaml
```

```bash Apply (declarative) theme={"system"}
# 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
```

```bash Export to file theme={"system"}
# round-trip: write the live config back out as YAML
vetta agent show agt_01j8rf6tq2m4vz9xkp3n7c5hwd --format yaml > refunder.agent.yaml
```

> [!NOTE]
>
> **`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](#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](https://vetta.sh/docs/capabilities/deployments.md), each independently budgeted, streamed, and controlled.

Versions are immutable snapshots; a running session pins the version it started on.

## 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](https://vetta.sh/docs/capabilities/deployments.md) 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.

```bash CLI theme={"system"}
vetta agent update agt_01j8rf6tq2m4vz9xkp3n7c5hwd --system "You process refunds. Always confirm the order first."
vetta agent versions agt_01j8rf6tq2m4vz9xkp3n7c5hwd          # full history, newest first
vetta agent version agt_01j8rf6tq2m4vz9xkp3n7c5hwd 2         # the full config snapshot of v2
vetta agent rollback agt_01j8rf6tq2m4vz9xkp3n7c5hwd --to 2   # creates a new version equal to v2
```

```typescript TypeScript theme={"system"}
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

**name** `string` *required*

A human-readable name for the agent.

**model** `string | object` *required*

The model that powers the agent. A model ID string, or an object such as `{ "id": "z-ai/glm-5.3-flash", "effort": "high" }`. See [Model router & inference](https://vetta.sh/docs/concepts/model-router.md).

**harness** `string` (default: pi)

The [harness](https://vetta.sh/docs/how-managed-agents-is-built.md#the-three-layers) — 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.

**budget** `object` *required*

Spend limits, in integer micro-USD on the wire. An agent cannot be created without one. See [Budgets](https://vetta.sh/docs/concepts/budgets.md).

**budget**

**cap\_micro\_usd** `integer` *required*

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

**max\_task\_micro\_usd** `integer` *required*

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

**period** `string` *required*

`day`, `week`, or `month`.

**system** `string`

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

**window** `string` (default: immediate)

Default [completion window](https://vetta.sh/docs/concepts/completion-window.md): `immediate`, `priority`, or `loose`. Overridable per session.

**computer** `string`

ID of a [computer](https://vetta.sh/docs/computer/index.md) the agent runs on.

**skills** `string[]`

[Skills](https://vetta.sh/docs/capabilities/skills.md) that supply domain context with progressive disclosure.

**tools** `object`

The [tools](https://vetta.sh/docs/capabilities/tools.md) 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](https://vetta.sh/docs/concepts/policies.md#per-tool-permission-policy). Built-ins are enabled by capability; [MCP](https://vetta.sh/docs/capabilities/tools.md#mcp-connector) and [connection](https://vetta.sh/docs/identity/connections.md) tools register under the same keys.

**mcp\_servers** `object[]`

MCP servers the agent can reach, referenced by [`mcp_toolset`](https://vetta.sh/docs/capabilities/tools#mcp-connector).

**identity** `string[]`

One or more [identities](https://vetta.sh/docs/identity/overview.md) the agent can act as.

**multiagent** `object`

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

**handoffs** `boolean | "team" | string[]`

Who the agent may [send work to](https://vetta.sh/docs/capabilities/tools.md#handoffs) with `send_to_agent`: `true` (any agent in the organization — the default), `false` (nobody; it is offered neither `send_to_agent` nor `list_agents`), `"team"` (only its `multiagent` roster), or a list of agent names.

**output\_schema** `object`

A default JSON Schema for a [structured result](https://vetta.sh/docs/concepts/sessions.md#structured-results). When set, a session goes idle carrying a typed `structured_output`; a session can override it per run.

**description** `string`

A description of what the agent does.

**metadata** `object`

Arbitrary key-value pairs for your own tracking.

> [card] [Next: runtime & durability](https://vetta.sh/docs/concepts/runtime.md)
>
> How the harness drives each turn, and how the runtime makes it durable.


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