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:

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.

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.

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.

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 and 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 for other admission and runtime failures.