# Agents

Choose a runtime and model, select agent settings on each turn, and understand what survives a sandbox replacement.

Source: https://docs.cloud.vampikez.fun/concepts/agents/

Choose an agent from `GET /v1/capabilities`, then put its selection on the
session or on a new turn. Runtime availability and model access belong to the
organization behind your credential.

## Runtime and model

| Kind | `modelSource` | Example `runtime` | Session `model` |
|---|---|---|---|
| Native WAMP | `catalog` | `wamp` (also the default when omitted) | Optional; defaults to the resolved agent slot |
| Vendor ACP | `runtime` | `claude-code`, `codex`, `grok-build` | Omit |
| Host-funded ACP | `host` | `pi` | Omit |

WAMP uses its own agent loop and a catalog model. Vendor ACP runtimes run their
own agent loop on an enrolled subscription. A host-funded runtime runs its own
loop on WAMP's metered model plane and needs no vendor account.

Discover the current choices:

```bash
export WAMP_API=https://api.vampikez.fun
# WAMP_TOKEN is your backend's installation credential.
curl --fail-with-body -sS "$WAMP_API/v1/capabilities" \
  -H "Authorization: Bearer $WAMP_TOKEN" \
  | jq '.capabilities | {runtimes, models}'
```

Read these fields instead of hardcoding the examples:

| Field | Use |
|---|---|
| `runtimes[].id` | Stable runtime identifier to send and store |
| `runtimes[].label` | Display text |
| `runtimes[].modelSource` | Whether the session uses the catalog or runtime-owned model selection |
| `runtimes[].availability` | `available`, or `temporarily_unavailable` with `retryAt` |
| `runtimes[].configCatalog` | Observed agent-owned settings and allowed values, when available |
| `models.items` | Models this deployment can route for the organization with tool use, which every native Run requires |
| `models.defaults.slots.agent` | Resolved default model for the native agent |

`wamp` and host-funded runtimes are listed without a vendor account. A vendor
runtime appears only after the organization enrolls an account. Its temporary
unavailability means the pool has no currently leasable account. Availability
can change between discovery and dispatch.

An empty `models.items` and absent default slot mean no catalog model can be
selected. Do not guess a model from `defaults.enabled`: that list can include
models the deployment cannot route. Discovery itself requires
`wamp.cloud.sessions:create`.

## Create a session

A native session uses the resolved agent slot default when `model` is omitted.
Send an explicit catalog model only to override it. The selected model is stored
on the Session and its initial Turn; exact retries keep that choice even after
the default changes. A runtime-managed session sends `runtime` and omits `model`.

```bash
set -eu
SESSION_ID=$(uuidgen | tr 'A-Z' 'a-z')
TURN_ID=$(uuidgen | tr 'A-Z' 'a-z')
BODY=$(jq -nc --arg t "$TURN_ID" \
  '{initialTurn:{id:$t,message:"Create hello.txt containing hello."}}')

curl --fail-with-body -sS -X PUT "$WAMP_API/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $WAMP_TOKEN" \
  -H 'Content-Type: application/json' -d "$BODY"
```

Keep the IDs and body before sending in a production integration. Retrying
with the same IDs and immutable input returns the existing work. The complete
Shell and TypeScript flow is in [Integrate Cloud](/start/integrate/).

The server normalizes `runtime: "wamp"` to its native representation; native
session responses omit `runtime`. An unknown runtime is
`400 cloud_agent_configuration_invalid`; an unavailable catalog model is
`400 cloud_agent_model_unavailable`. The same code applies when the organization
has no agent slot to default to.

## Select the next turn

Session metadata and turn selection have different rules:

| Operation | Agent selection |
|---|---|
| Create Session | Omit both for the native default, or select an initial `runtime` and `model` |
| Session `PATCH` before any Turn exists | Change runtime/model while idle |
| Session `PATCH` after a Turn exists | Changing runtime/model returns `409 cloud_agent_locked` |
| Submit a new Turn | Omit runtime/model to inherit, or explicitly select the next agent |
| Reply to an Interaction | Inherit the opening Turn's configuration; conflicting overrides return `409 cloud_interaction_conflict` |

A turn accepts `message`, optional `replyTo`, and optional `runtime`, `model`,
`thinkingLevel` or `runtimeConfig`. Its accepted configuration is immutable and
part of exact retry identity. A new ordinary turn cannot bypass an open
Interaction; answer it first. Only one executing run is admitted per session.

For native WAMP, `thinkingLevel` defaults to `low`. For ACP agents, omit
`thinkingLevel` and use `runtimeConfig`, a map of setting IDs to option values
from the observed `configCatalog`. These settings belong to the turn; omission
uses agent defaults. A model the catalog's model setting no longer offers, sent as
`model` or in `runtimeConfig`, is `400 cloud_agent_model_unavailable` when the
turn is submitted; before any catalog is observed the agent decides, and a model
it does not offer fails the run with `runtime_error` and a last message naming
the models it does. A transition
to `wamp` from ACP needs an explicit catalog model. Selecting an ACP runtime omits
the WAMP model.

Switching runtimes hands over the platform's conversation and workspace. It
does not convert one vendor's private session into another vendor's format.
Use separate sessions when you need independent attempts or concurrent work.
The exact input fields are in the [Turns reference](/api/operations/tags/turns-and-runs/).

## What survives sandbox replacement

The runtime's discovery `continuation` declares supported fidelity. The
session's `continuation` reports what was actually retained: read that field
before offering a follow-up after compute disappears.

Cloud retains the portable conversation and workspace at a completed boundary.
For ACP agents it can also retain native session files when the runtime declares
continuation roots and supports ACP resume/load. On restoration the engine tries
that native continuation first. Missing or incompatible native state falls back
to a new agent session seeded from WAMP's portable history.

`conversation.fidelity: "exact"` describes the retained WAMP conversation. It
is not a guarantee that every vendor tool result or internal reasoning state
survived. Optional native continuation improves fidelity for the same runtime;
it is private restore data, never a downloadable public Artifact. See
[Sandboxes](/concepts/sandboxes/) and [Artifacts](/concepts/artifacts/).

## Vendor accounts

A human with `wamp.cloud.accounts:manage` enrolls subscriptions through the
Cloud web app's Settings under **Agent accounts**. Enrollment runs the vendor's sign-in in a
live workspace; app installations cannot enroll accounts through `/v1`.

Dispatch reserves an organization account for the run. Cloud brokers its
credential through a Run-scoped ticket, preserves Session affinity, and saves
rotated credentials after turns. Your integration never receives the credential.
On a subscription limit the engine tries another usable account; it replays a
prompt only before visible output or a tool/interaction side effect. A transient
provider throttle does not rotate the account.

When discovery omits a vendor runtime, ask the organization's account manager
to connect one. When it reports `temporarily_unavailable`, use `retryAt` and
back off. Handle `503 cloud_runtime_account_unavailable` if availability changes
between selection and execution. See [Errors](/reference/errors/) for other
admission and runtime failures.