Agents

An agent is a reusable, versioned configuration: a model, a system prompt, a set of tools and skills, a completion window, and a budget. Sessions and deployments run against an agent. Every update is captured as an immutable agent version with optimistic concurrency.

The agent object

string

Unique id (e.g. agt_01H...).

string

Always agent.

string

Human-readable name.

string

The harness — the agent loop. GET /v1/harnesses publishes the set, what each one can be admitted for, and whether it holds a sandbox between turns.

string

Model identifier, e.g. zai-org/GLM-5.2-FP8. See the model router.

string

Default completion window: immediate | priority | loose.

string

System prompt.

object

The toolset configuration. See Tools.

Show tools

object

Default { permission } applied to every tool unless overridden. permission ∈ allow (run silently) · ask (pause → tool.confirm event) · deny (tool is not offered to the model at all).

object

Per-tool overrides keyed by tool name — a built-in (bash, browser, web_search, generate_image, …) or a namespaced <server>.<tool>. Each entry is { enabled, permission, config? }.

object[]

Attached MCP servers the agent may call.

string[]

Attached skill references. Each entry is a slug or id, optionally suffixed @version to pin an immutable version (e.g. refund-policy@3). An unpinned reference resolves to the skill’s latest version at session start.

boolean

Whether the agent may coordinate sub-agents.

object

Required spend controls.

Show budget

integer

Ceiling for the period, in micro-USD.

integer

Ceiling for a single session/task, in micro-USD.

string

Reset window: day | week | month.

object | null

Optional JSON Schema the agent’s final result must satisfy. Sessions inherit it as their default and may override it per run. See Structured outputs.

boolean

Whether a run that cannot produce an object conforming to output_schema is a failure rather than a plain-text answer. Sessions inherit it and may override it per run.

string | null

Optional longer description.

object

Arbitrary key/value pairs you attach.

integer

Monotonic version counter. Pass this as expected_version on update for optimistic concurrency.

string

Creation timestamp.

Create an agent

POST /v1/agents → 201 Created.

string

required

Human-readable name.

string

required

Model identifier.

object

required

Spend controls (cap_micro_usd, max_task_micro_usd, period). Agents cannot be created without a budget.

string

Defaults to "pi". A harness the deploy cannot run is refused when the session starts, naming the field — see harnesses.

string

Default completion window (immediate | priority | loose). Defaults to immediate.

string

System prompt.

object

Toolset config — a default_config plus per-tool configs. See the toolset schema.

object[]

MCP servers to attach.

string[]

Skills to attach. Each entry is a slug/id, optionally @version to pin (e.g. refund-policy@3).

boolean

Enable sub-agent coordination. Defaults to false.

object

JSON Schema the final result must satisfy. Defaults to null. See Structured outputs.

boolean

Treat a non-conforming result as a failure rather than answering in prose. Defaults to false; needs an output_schema.

string

Longer description. Defaults to null.

object

Arbitrary metadata.

curl -fsSL https://api.vetta.sh/v1/agents \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "name": "Refunder",
    "model": "zai-org/GLM-5.2-FP8",
    "window": "immediate",
    "system": "You process refunds.",
    "tools": {
      "default_config": { "permission": "allow" },
      "configs": {
        "browser": { "enabled": true, "permission": "ask", "config": { "allowed_domains": ["*.example.com"] } }
      }
    },
    "skills": ["refund-policy@3"],
    "budget": { "cap_micro_usd": 50000000, "max_task_micro_usd": 5000000, "period": "month" }
  }'

{
  "id": "agt_01H8XK...",
  "object": "agent",
  "name": "Refunder",
  "harness": "pi",
  "model": "zai-org/GLM-5.2-FP8",
  "window": "immediate",
  "system": "You process refunds.",
  "tools": {
    "default_config": { "permission": "allow" },
    "configs": {
      "browser": { "enabled": true, "permission": "ask", "config": { "allowed_domains": ["*.example.com"] } }
    }
  },
  "mcp_servers": [],
  "skills": ["refund-policy@3"],
  "multiagent": false,
  "budget": { "cap_micro_usd": 50000000, "max_task_micro_usd": 5000000, "period": "month" },
  "output_schema": null,
  "description": null,
  "metadata": {},
  "current_version": 1,
  "created_at": "2026-08-20T17:00:00Z"
}

Retrieve an agent

GET /v1/agents/{id} → 200 OK with the current configuration, including current_version.

curl -fsSL https://api.vetta.sh/v1/agents/agt_01H8XK... \
  -H "authorization: Bearer sk_live_..."

List agents

GET /v1/agents → 200 OK, cursor-paginated. See Pagination.

Response

{
  "data": [ { "id": "agt_01H...", "name": "Refunder", "current_version": 3 } ],
  "has_more": false,
  "next_cursor": null
}

Update an agent

PATCH /v1/agents/{id} → 200 OK. Applies a partial update and creates a new immutable version. A no-op update creates no new version. Updates use optimistic concurrency: pass the expected_version you read. If it no longer matches current_version, the API returns 409 with code version_conflict and applies nothing. Omitting expected_version performs an unconditional, last-write-wins apply — use this for declarative CI that reconciles an .agent.yaml toward a desired state.

integer

The current_version you last read. Omit for an unconditional apply.

string

Any subset of the mutable fields (name, system, model, window, tools, mcp_servers, skills, multiagent, budget, output_schema, structured_output_required, description, metadata). Renaming is deliberately not a config change: a patch that only sets name mints no new version.

curl -fsSL -X PATCH https://api.vetta.sh/v1/agents/agt_01H8XK... \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "expected_version": 1, "system": "You process refunds. Confirm the order first." }'

Returns the full agent object at its new version:

Response

{ "id": "agt_01H8XK...", "object": "agent", "current_version": 2, "system": "You process refunds. Confirm the order first." }

Version conflict (409)

If another writer advanced the version, you get:

409 Conflict

{
  "error": {
    "type": "conflict",
    "code": "version_conflict",
    "message": "expected_version 1 does not match current_version 2.",
    "request_id": "req_01H9ZZ...",
    "param": "expected_version"
  }
}

Refetch the agent, re-apply your change against the fresh current_version, and retry.

The agent-version object

Each update snapshots the full config into an immutable agent version. Versions never change once written.

integer

Monotonic version number.

string

When this version was created.

object

The principal that created the version — { "type": "user" | "key" | "system", "id": "..." }.

string

Model identifier at this version.

string

System prompt at this version.

string

Completion window at this version.

object

Toolset config at this version.

object[]

MCP servers at this version.

string[]

Skill references at this version.

boolean

Sub-agent coordination flag at this version.

object

Budget at this version.

object | null

Output schema at this version.

boolean

Whether a conforming object was required at this version.

string | null

Description at this version.

object

Metadata at this version.

List versions

GET /v1/agents/{id}/versions → 200 OK. The full immutable version history in one page: this list is not paginated — limit and after are ignored, and the reply always carries has_more: false, next_cursor: null. Each row is a whole agent-version object; versions are addressed by their version number, not by an id.

Response

{
  "data": [
    { "version": 2, "created_at": "2026-08-20T18:00:00Z", "created_by": { "type": "user", "id": "usr_01H..." }, "system": "You process refunds. Confirm the order first." },
    { "version": 1, "created_at": "2026-08-20T17:00:00Z", "created_by": { "type": "user", "id": "usr_01H..." }, "system": "You process refunds." }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a version

GET /v1/agents/{id}/versions/{n} → 200 OK with the full agent-version object for version n. Use it to inspect or diff a past configuration.

curl -fsSL https://api.vetta.sh/v1/agents/agt_01H8XK.../versions/1 \
  -H "authorization: Bearer sk_live_..."

Response

{
  "version": 1,
  "created_at": "2026-08-20T17:00:00Z",
  "created_by": { "type": "user", "id": "usr_01H..." },
  "model": "zai-org/GLM-5.2-FP8",
  "system": "You process refunds.",
  "window": "immediate",
  "tools": { "default_config": { "permission": "allow" }, "configs": {} },
  "mcp_servers": [],
  "skills": ["refund-policy@3"],
  "multiagent": false,
  "budget": { "cap_micro_usd": 50000000, "max_task_micro_usd": 5000000, "period": "month" },
  "output_schema": null,
  "structured_output_required": false,
  "description": null,
  "metadata": {}
}

Roll back to a version

POST /v1/agents/{id}/rollback → 200 OK. Creates a new version whose config equals an earlier one — history is never rewritten. Returns the full agent object at that new version.

integer

required

The version whose config to restore.

integer

The current_version you last read, for optimistic concurrency. Omit for an unconditional rollback.

curl -fsSL https://api.vetta.sh/v1/agents/agt_01H8XK.../rollback \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "to_version": 1, "expected_version": 2 }'

Response

{ "id": "agt_01H8XK...", "object": "agent", "current_version": 3 }

Spend

GET /v1/agents/{id}/spend → 200 OK. Metered spend for the current budget period, in micro-USD, optionally broken down by component with ?by=component.

Response

{
  "agent_id": "agt_01H8XK...",
  "period": "month",
  "spent_micro_usd": 12418700,
  "by_component": { "model": 11902000, "computer": 481000, "search": 6474, "media": 390000 }
}

Delete an agent

DELETE /v1/agents/{id} → 200 OK. Removes the agent. Version history is retained for existing sessions.

curl -fsSL -X DELETE https://api.vetta.sh/v1/agents/agt_01H8XK... \
  -H "authorization: Bearer sk_live_..."

Response

{ "id": "agt_01H8XK...", "object": "agent", "deleted": true }

Run an agent

Create a session to run an agent directly.

Introduction

Core resources

Platform

Identity

The agent object

Create an agent

Retrieve an agent

List agents

Update an agent

Version conflict (409)

The agent-version object

List versions

Retrieve a version

Roll back to a version

Spend

Delete an agent

Run an agent

​The agent object

​Create an agent

​Retrieve an agent

​List agents

​Update an agent

​Version conflict (409)

​The agent-version object

​List versions

​Retrieve a version

​Roll back to a version

​Spend

​Delete an agent

Run an agent

The agent object

Create an agent

Retrieve an agent

List agents

Update an agent

Version conflict (409)

The agent-version object

List versions

Retrieve a version

Roll back to a version

Spend

Delete an agent