Run a sandbox tool in a session
For an app's own tools; not while a turn is running.
applicationKeyAuthorizationBearer <token>An application key of the Tenant (PUT /v1/tenant/keys/{keyId}), or Studio's key, derived from the admin key. With Nylorun-Subject and Nylorun-Scopes, it acts for that person, narrowed to those scopes. Never accepted from a browser (Origin).
sessionId*stringtool*string"bash""read""write""edit""grep""glob"Nylorun-Protocol*stringThe protocol version, 18
application/json- body
The tool's input
[key: string]?unknownThe tool's output, or why it failed
application/json- response
kind*"completed""completed"output?unknownimport { createClient } from "@nylorun/agents";const client = await createClient();const result = await client.session("ses_123").sandbox.bash({ command: "npm test",});{ "kind": "completed", "output": null}Read a turn's trace GET
The turn's spans as OTLP/HTTP JSON (`resourceSpans`), as the Runtime posts them to an OTLP collector: a root span for the turn (`invoke_agent`), a span for each model call (`chat`) and tool call (`execute_tool`), and markers for pauses and answers, ids derived so every read agrees. Egress has no span: a connection is the Environment's, read from its events. Content (`gen_ai.*.messages`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`) is there only when the installation sets `OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT=SPAN_ONLY`, as structured values. Post it to a collector's `/v1/traces` to backfill. A turn still running has no root span yet; a turn the session never had has no spans.
Follow turns as they change GET
The turn index's change feed (Host feature `turns`): each turn's status, times, totals and A2A context and task, in the order the turns changed, a turn again each time it changes. Pass the page's `cursor` as `changedAfter` to read on; it is returned even when no turn changed. With `sessionId`, one session's turns, oldest first. An application key reads the whole Tenant; acting for a person, only theirs.