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

> Create, version, and retire agents — client.agents, one method per route.

The agent is the durable, versioned configuration a [session](/docs/sdk/sessions) runs. Nine methods, one per route; objects parse with the core `AgentSchema`. API detail: [Agents](/docs/api/agents).

## create

```ts theme={"system"}
client.agents.create(body: AgentCreate): Promise<Agent>
```

`POST /v1/agents`. `AgentCreate` requires `name` and `model`; everything else on the agent config (`system`, `window`, `effort`, budgets, `harness`, …) is optional. `harness` selects the agent loop — `pi` is the only one in Phase 1, and the default.

```ts theme={"system"}
const agent = await client.agents.create({ name: "support", model: "..." });
```

## list

```ts theme={"system"}
client.agents.list(query?: ListQuery): Promise<Page<Agent>>
```

`GET /v1/agents`, cursor-paginated. See [Pagination](/docs/sdk/pagination).

## get

```ts theme={"system"}
client.agents.get(id: string): Promise<Agent>
```

`GET /v1/agents/{id}`.

## update

```ts theme={"system"}
client.agents.update(id: string, body: AgentPatch): Promise<Agent>
```

`PATCH /v1/agents/{id}`. Every config field is optional; a successful patch **mints a new version** rather than editing the current one. Pass `expected_version` for optimistic concurrency — a mismatch is a `409 conflict`.

## listVersions

```ts theme={"system"}
client.agents.listVersions(id: string): Promise<Page<AgentVersion>>
```

`GET /v1/agents/{id}/versions`. History is immutable and never rewritten.

## getVersion

```ts theme={"system"}
client.agents.getVersion(id: string, version: number): Promise<AgentVersion>
```

`GET /v1/agents/{id}/versions/{version}`.

## rollback

```ts theme={"system"}
client.agents.rollback(id: string, body: { to_version: number; expected_version?: number }): Promise<Agent>
```

`POST /v1/agents/{id}/rollback`. Mints a **new** version cloning `to_version` — a rollback is itself a versioned change, so history stays linear and auditable.

## spend

```ts theme={"system"}
client.agents.spend(id: string, query?: { by?: "component" }): Promise<AgentSpend>
```

`GET /v1/agents/{id}/spend` — metered spend for the agent's current budget period, integer micro-USD:

```json theme={"system"}
{ "agent_id": "agt_01H...", "period": "month", "period_start": "2026-08-01T00:00:00Z", "spent_micro_usd": 1250000 }
```

`by: "component"` adds a `by_component` breakdown — `model` (the five token tiers summed), `computer`, `search`, `media`, and `other` for anything a debit did not itemise. A component with no spend is absent, and the breakdown always sums to `spent_micro_usd`. Absent unless asked for.

## delete

```ts theme={"system"}
client.agents.delete(id: string): Promise<Deleted>
```

`DELETE /v1/agents/{id}`. Answers the standard `{ id, object, deleted: true }` acknowledgement.