Agents

After this page you can choose which agent executes a session’s work, know whether you also have to choose a model, know why that choice is permanent once the first turn lands, and know which of the failures you will see are about the agent’s credentials rather than about your request.

Two kinds of agent

WAMP Cloud runs a session’s work with an agent runtime, selected by the runtime field. There are two kinds, and the difference that matters to a caller is where the model comes from.

Kind	runtime	modelSource	You supply model
The native WAMP agent	wamp (the default)	catalog	Yes, required
A vendor coding agent	e.g. claude-code, codex	runtime	No — omit it

The native agent is WAMP’s own harness, driven by a model from the WAMP catalog that your organization is entitled to. A vendor coding agent is the vendor’s own harness — its own loop, its own tools, its own prompt — running inside the sandbox and driven by the model that agent ships with.

The server today trusts exactly two vendor runtime ids, claude-code and codex. Do not hardcode that list: read it from discovery, because an organization sees only the runtimes it can actually use.

Discover before you select

curl -sS "$WAMP_API/v1/capabilities" -H "Authorization: Bearer $WAMP_TOKEN"

{
  "capabilities": {
    "runtimes": [
      {
        "id": "wamp",
        "label": "WAMP",
        "modelSource": "catalog",
        "continuation": { "live": "exact", "checkpoint": "exact" },
        "availability": { "state": "available" }
      },
      {
        "id": "claude-code",
        "label": "Claude Code",
        "modelSource": "runtime",
        "continuation": { "live": "exact", "checkpoint": "result_only" },
        "availability": { "state": "temporarily_unavailable", "retryAt": "2026-08-11T10:30:00.000Z" }
      }
    ],
    "models": { "items": [], "defaults": { "slots": {}, "enabled": [] } }
  }
}

Four things to read out of each entry:

• id — the value you send as runtime. This is the stable identifier.
• modelSource — catalog means you pick the model, runtime means the agent brings its own.
• availability.state — available, or temporarily_unavailable with an ISO retryAt. Offer only what is available; a temporarily_unavailable runtime means every vendor account in the organization is currently in use or cooling down, and retryAt is the earliest one comes back.
• continuation — how much survives a lost sandbox for that runtime. Vendor runtimes report checkpoint: "result_only", so a session that has to be restored from a checkpoint resumes with the outcome of earlier work rather than the exact conversation. The native agent reports exact. See Sandboxes.

wamp is always listed and always available. If the organization has no vendor accounts enrolled, wamp is the only entry — an empty vendor list is a configuration state, not an outage.

label is display text, not an identifier

The label for a vendor runtime is currently derived from a two-branch condition — claude-code yields Claude Code and everything else yields Codex — so a third runtime would arrive mislabeled. Treat label as untrusted display text and never map it, compare it, or persist it as a key. id is the contract.

Discovery requires wamp.cloud.sessions:create. An installation consented only for reading cannot call it, which is worth knowing before you build a runtime picker that depends on it.

How runtime and model interact

The rule is enforced when you create the session:

• No runtime, or runtime: "wamp" → model is required. Omitting it is 400 invalid_request with the error path pointing at model. Pick an id from capabilities.models.items[].id, or use the organization’s default from capabilities.models.defaults.
• A vendor runtime → omit model. The agent supplies its own default, and the WAMP model catalog does not describe it. model is not the knob that steers a vendor agent; leave it unset so nothing in your record implies otherwise.

runtime: "wamp" and omitting runtime are the same request. The server normalizes wamp to “no vendor runtime”, so a session created either way reports no runtime field back.

The runtime value itself is validated only as a shape: lowercase letters, digits and hyphens, starting with a letter or digit, 1–64 characters. A syntactically valid id that no sandbox can actually provide is accepted at submission and fails when the work is dispatched — which is the reason to read discovery rather than to guess a name.

The choice settles with the first turn

A session’s agent is part of its identity, because a conversation cannot be handed mid-flight from one harness to another and still be the same conversation.

When	How to set or change it
At creation	runtime in the PUT /v1/sessions/{sessionId} body.
Before the first turn	PATCH /v1/sessions/{sessionId} with { "runtime": "…" }.
After the first turn	Not possible. PATCH with a different runtime is 409 cloud_agent_locked.

Turns inherit the settled runtime. Omit runtime on PUT /v1/sessions/{sessionId}/turns/{turnId} — that is the recommended form. If you do send it, it must equal the settled value (with wamp and “absent” treated as equal); a different value is 409 cloud_agent_locked rather than a silent switch.

To run the same task with a different agent, create a new session. That is not a workaround — a second session is the honest representation of a second attempt by a different agent, and it keeps both event logs readable.

Where an agent’s credentials come from

The native wamp runtime needs nothing from you: model access is metered through the organization, and choosing a model is the whole configuration.

A vendor coding agent signs in with the vendor’s own account — a subscription login to that vendor, not an API key you hold. WAMP Cloud stores those logins as an organization-wide pool and leases one to a run:

1. An administrator enrolls the account. A human with the account-management capability connects a vendor account inside the WAMP Cloud web app. The capability is grantable to people only, so an app installation can never enroll an account — there is no programmatic enrollment endpoint for an integration to call, and there will not be one at this authority level.
2. A run leases an account. When a session’s turn starts, the sandbox is handed one of the organization’s enrolled accounts for the life of that sandbox. Your request never carries a vendor credential, and no vendor credential is ever returned to you.
3. Exhaustion is handled and reported. When a vendor’s own quota refuses a turn, the account is benched until the vendor says it recovers and another account takes over. When there is nothing left to lease, the runtime reports temporarily_unavailable with retryAt in discovery.

For your integration this reduces to two rules: check availability before offering a vendor agent, and tell the customer to have an administrator connect an account when the list is empty. You cannot fix an empty pool from the API, and a session pointed at a runtime with no account will not produce work.

The failures worth handling

Status	Code	What it means
400	invalid_request	Most often: model omitted on a wamp session, or an unknown key in the body.
409	cloud_agent_locked	The request would change the agent a session has settled on. Create a new session instead.
503	cloud_runtime_account_unavailable	No vendor account is currently leasable. Retry later; check retryAt in discovery.
503	cloud_runtime_outdated	The runtime available in the sandbox cannot serve this session as configured. Surface it; retrying immediately will not help.

Everything else about a run’s outcome — a failing test, a refused tool, a budget stop — arrives as a normal run status and stopReason, not as an agent error. See Errors.

A worked selection

Pick the first available vendor runtime, fall back to the native agent, and create the session accordingly:

CAPS=$(curl -sS "$WAMP_API/v1/capabilities" -H "Authorization: Bearer $WAMP_TOKEN")

RUNTIME=$(printf '%s' "$CAPS" | jq -r '
  .capabilities.runtimes
  | map(select(.modelSource == "runtime" and .availability.state == "available"))
  | (.[0].id // "wamp")')

SESSION_ID=$(uuidgen | tr 'A-Z' 'a-z')

if [ "$RUNTIME" = "wamp" ]; then
  MODEL=$(printf '%s' "$CAPS" | jq -r '.capabilities.models.items[0].id')
  BODY=$(jq -nc --arg m "$MODEL" \
    '{task:"Fix T-142 and summarize the result.", title:"T-142", model:$m}')
else
  BODY=$(jq -nc --arg r "$RUNTIME" \
    '{task:"Fix T-142 and summarize the result.", title:"T-142", runtime:$r}')
fi

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

Note what the two branches do not share: the vendor branch sends no model, and the native branch sends no runtime. Turns after this send neither.

Related

• Sessions, turns, runs — what a turn does with the settled runtime.
• Sandboxes and environments — the continuation fidelities a runtime advertises.
• Capabilities operations — the generated reference for the discovery document.
• Sessions operations — where runtime and model are accepted, and Errors for the codes above.