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

# Agent

> Vetta's core primitive — a versioned config of model, harness, prompt, tools, skills, and budget that runs as durable sessions.

An **agent** is a reusable, versioned *configuration*: a model (and effort), a system prompt, a [toolset](/docs/capabilities/tools), [skills](/docs/capabilities/skills), a required [budget](/docs/concepts/budgets), and a default [completion window](/docs/concepts/completion-window) — plus the `harness` field that picks the agent loop. Define it once, run it as many [sessions](/docs/concepts/sessions) — each a durable execution that can pause for hours at storage cost and resume exactly where it left off.

<Card title="Agent reference" icon="robot" href="/docs/concepts/agents">
  The full agent object, versioning, sessions, harness, completion window, budgets, and policies.
</Card>

## One agent, many runs

The agent is the *definition*; a [session](/docs/concepts/sessions) is a single *run* of it. One agent backs many sessions and cron [deployments](/docs/capabilities/deployments), each independently budgeted, streamed, and controlled.

<img src="https://mintcdn.com/vetta/rjfQyQrWaQ5bFTTq/images/agent-sessions.svg?fit=max&auto=format&n=rjfQyQrWaQ5bFTTq&q=85&s=c98e8bdc806ddc567a8e6b3c2c41e38b" alt="One versioned agent definition fanning out to independently budgeted sessions and a cron deployment" width="900" height="400" data-path="images/agent-sessions.svg" />

## Create one

<CodeGroup>
  ```bash CLI theme={"system"}
  vetta agent create --name Refunder \
    --model zai-org/GLM-5.2-FP8 --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: "zai-org/GLM-5.2-FP8",
    harness: "pi",
    skills: ["refund-policy"],
    budget: { capUsd: 50, maxTaskUsd: 5, period: "month" },
    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": "zai-org/GLM-5.2-FP8",
      "harness": "pi",
      "budget": { "cap_usd": 50, "max_task_usd": 5, "period": "month" },
      "window": "immediate",
      "system": "You process refunds."
    }'
  ```
</CodeGroup>

No computer in the config — sessions provision their own sandbox when needed.

## Fields at a glance

| Field                   | What it sets                                                                                             |
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
| `name` · `system`       | The agent's name and system prompt.                                                                      |
| `model` · `effort`      | Which model runs each turn, and at what effort.                                                          |
| `harness`               | The agent loop — `pi` is the default. See [How Vetta works](/docs/how-vetta-is-built#the-harness-harness).    |
| `tools` · `mcp_servers` | What it may use, each gated `allow` / `ask` / `deny`. See [Tools](/docs/capabilities/tools).                  |
| `skills`                | Versioned expertise loaded on demand. See [Skills](/docs/capabilities/skills).                                |
| `budget` *(required)*   | The spend cap every session draws against. See [Budgets](/docs/concepts/budgets).                             |
| `window`                | The default [completion window](/docs/concepts/completion-window) — cost vs. latency per request.             |
| `output_schema`         | A JSON Schema the final result must satisfy. See [Structured outputs](/docs/capabilities/structured-outputs). |

Every edit mints a new immutable version; the full object is in the [agent reference](/docs/concepts/agents).

<Card title="Next: computer" icon="server" href="/docs/capabilities/computer">
  The disposable micro-VM sandbox, filesystem, shell, and browser the agent works in.
</Card>