Host
TS: supports await using (Symbol.asyncDispose calls stop).
Python: an async context manager (aenter calls ready, aexit calls stop).
Properties
fetch(request: Request) => Promise<Response>requiredTypeScript only. Mount in Next, Hono, Bun.serve.
asgistarlette.types.ASGIApprequiredPython only. Mount in FastAPI or any ASGI server.
channelsreadonly string[]requiredThe host({channels}) keys; threads dev prints each one's webhook URL, /channels/<key>/events.
Methods
startRun / start_run
POST /v1/runs. Makes the user_input durable together with the idempotency key and returns; the run proceeds in the host. The key binds tenant, the full principal (issuer, tenant, subject), the operation and the request hash: the same key, principal and request replays the same receipt and starts nothing; a different request is idempotency_key_reused; a different principal in the same tenant is idempotency_key_principal_mismatch, and never sees the other principal's receipt.
startRun(request: StartRunRequest, options: {
principal: Principal;
idempotencyKey: string;
}): Promise<Result<RunAccepted>>requestStartRunRequestrequiredWhat to run: the host agent's key and the input, and optionally the thread and branch to continue and a run budget.
principalPrincipalrequiredThe authenticated caller, never the local-operator default.
idempotencyKey / idempotency_keystringrequiredThe client's key for this request, 1 to 255 characters (the Idempotency-Key header over HTTP). Retrying with the same key, principal and request returns the first receipt and starts nothing new.
Returns an error value with one of these codes: forbidden, invalid_request, not_found, branch_busy, branch_not_runnable, idempotency_key_reused, idempotency_key_principal_mismatch.
subscribe
GET /v1/threads/{thread_id}/runs/{run_id}/events. Follows one run from the log: its stream events, then one result message naming run_id. Takes no input and starts nothing.
subscribe(threadId: ThreadId, runId: EventId, options: {
principal: Principal;
afterSeq?: Int;
}): Promise<Result<AsyncIterable<SseMessage>>>threadId / thread_idThreadIdrequiredThe thread the run belongs to.
runId / run_idEventIdrequiredThe run to follow: run_id from startRun's receipt (its user_input event id). A run not found in this tenant's thread is not_found.
principalPrincipalrequiredThe authenticated caller. It must belong to the thread's tenant; another tenant's thread is not_found.
afterSeq / after_seqIntdefault 0Resume after this seq (SSE Last-Event-ID).
Returns an error value with one of these codes: forbidden, not_found.
ready
Confirms bindings. Sends nothing, starts no run.
ready(): Promise<void>Throws ConfigError for a definition that can't run.
stop
Drains in-flight intake and releases leases.
stop(): Promise<void>