Agent

Start one interactive agent-kernel turn

Drives ToolPiper's native AgentLoopKernel for one turn on a session (creating the session when session_id is absent). Provider-first: the body carries NO model name — the route resolves to a configuration through a three-layer ladder, the caller's optional endpoint_config_id, then the authenticated token's endpoint-config binding, then the local active model. Returns immediately; the turn's events (token deltas, tool-call proposals, tool results, cost frames, terminal turn-ended marker) ride GET /v1/agent/stream.

A session belongs to the client that opened it. Continuing, cancelling, answering, streaming or reading one another client opened is refused with 403 naming the owning client; the person at the Mac is always admitted. A conversation saved before sessions recorded their owner is open to the person and to ToolPiper's web app, and the first of them to continue it becomes its owner.

post/v1/agent/turn

Request

  • Base URL: http://localhost:9998
  • URL: http://localhost:9998/v1/agent/turn
  • Auth: HTTP bearer

Request body

messagestring required

The user message for this turn

session_idstring

The chat this turn runs (1-128 chars of [A-Za-z0-9_-]); omitted mints a new session. ToolPiper resolves what the turn may do without asking from that chat, never from the body: reads inside the pinned folders, the folders its project allowed and those of the code workbenches open in it, and the tool families its open workbenches trust. Reads auto-approve only in a chat a renderer journals: a session whose record holds no journal (a headless caller's) or no record at all reads nothing without asking.

systemstring

System prompt, applied only on a session's first turn

endpoint_config_idstring

The caller's chosen provider, as an EndpointConfig id (tp-<uuid>; alphanumerics, - and _, at most 64 characters). This is a configuration reference, not a model name — provider-first is intact, and ToolPiper still resolves and injects the model server-side. Layer 1 of the route ladder: it wins over the calling token's endpoint-config binding, because a pick expressed in the request outranks a stored auth-scoped default. An id that no longer exists is a hard 503, never a silent fall-through to a different provider. Omit to resolve server-side from the token binding or the local active model — every headless / voice / worker caller does.

tools_enabledboolean

Per-turn tools switch. Absent (or JSON null) defaults to true, so every existing headless / voice / worker caller is byte-unchanged. When false the turn advertises NO tools at all — the surface set, the retrieval set and the request_tools escape hatch alike — and the kernel runs a plain single-completion turn. Present-but-not-boolean is a deterministic 400 (tools_enabled must be a boolean).

backgroundboolean

Make this turn a background run. Losing every GET /v1/agent/stream subscriber never cancels it, and a parked approval waits out its 300 s idle timeout instead of resolving as a disconnect, so a client that reattaches can answer it. Absent (or JSON null) keeps the five-second disconnect grace. Anything but a JSON boolean is a 400 (background must be a boolean).

Response

Turn accepted and running

oktrue
session_idstring
turninteger

1-based turn index within the session

run_idstring

This turn's run. Name it as run_id on cancel and approve so a reply meant for a finished run can never land on a later one; read it back from GET /v1/agent/run.

streamstring

Path of the session's SSE stream

last_event_idinteger

The session frame ring's head id before this turn appends anything. A client that kept its replay cursor across a Stop fast-forwards to it, so a cancelled turn's unseen tail (including its terminal frame) never replays into the new turn's stream subscription.

Changes

No recorded changes to this operation across all 1 revision of this API.