Build

Invocations

Admit one durable agent turn, read its result, and stop, replace, or steer it while it runs.

An Invocation is one agent turn. It starts with a user input and an immutable execution spec, may make several model and tool calls, and ends in one durable terminal state.

What goes into a turn

POST /v1/invocations accepts:

agent_key, which resolves a lightweight identity anchor;
either a Session ID, a host-owned session_key, or neither for a new anonymous Session;
optional tenant_key and user_key attribution;
an idempotency_key chosen by the host or SDK;
text or multimodal input;
optional host metadata, notification target, and provider-credential choice;
the execution spec.

The spec contains the instructions and model plus any tools, limits, structured output, sampling, reasoning, or outcome review. It is stored as the exact launch snapshot for recovery.

Make admission replayable

Use one idempotency key for one logical turn. If the connection fails before you receive the 202, send the same request and key again.

nvoken compares the material request, not just the key. An equal replay returns the original Invocation. A changed replay returns idempotency_conflict instead of silently changing accepted work.

The SDK facades generate and retain a key automatically. Supply your own when a queue or database record must be able to recreate admission after the original process has disappeared.

Status	Meaning
`queued`	Admitted and waiting for an execution owner
`running`	One owner is executing a model or tool segment
`waiting`	Durable host ToolCalls need results; no execution lease is held
`completed`	The model finished, or the caller interrupted the turn
`incomplete`	A budget stopped coherent work before it became a final answer
`failed`	The turn could not finish; `error` explains why
`cancelled`	The host cancelled it and unfinished work is excluded from later model context

stop_reason adds the useful detail. A completed turn has end_turn or interrupted. An incomplete turn names the budget it reached: max_iterations, deadline, max_output_tokens, or max_estimated_cost.

Treat incomplete as an unfinished answer, not a successful final response. Its coherent messages remain in later Session context, and its provider usage is still real.

Read the result

Use the composed result endpoint when you want one authoritative object:

GET /v1/invocations/{invocation_id}/result

It returns the Invocation, its canonical messages, and output_text when the turn completed with assistant text. Structured output and its provenance are on the Invocation itself.

Assistant messages also have a phase. final_answer marks the message that settled a normal completed turn. Everything else is commentary, including tool-loop narration and output from an interrupted or incomplete turn. Render the phase instead of assuming the last assistant message is the answer.

Stop or replace work

There are three different controls because “stop” can mean different things:

Cancel

POST /v1/invocations/{id}/cancel settles the Invocation as cancelled and excludes its unfinished assistant and tool messages from future model context. It cannot undo a provider charge or external side effect that already happened.

Interrupt

POST /v1/invocations/{id}/interrupt asks the turn to stop at its next safe boundary. It settles completed with stop_reason: interrupted, so later turns build on the work it already produced.

Replace during admission

A new turn in the same Session normally gets session_invocation_active while work is active. Set if_active only when the product action is explicit:

supersede cancels the old turn and admits the replacement atomically.
interrupt keeps the old work, waits for it to settle, then admits the replacement.

Steer a running turn

A nudge appends text for the Invocation to consume at its next execution boundary:

POST /v1/invocations/{invocation_id}/nudge
{
  "content": "Focus on the marine segment.",
  "idempotency_key": "research-42:nudge-1"
}

The current model or tool call is not aborted. If the turn finishes before it takes the nudge, that input becomes expired and never leaks into a later turn.

List staged input with GET /pending-inputs and withdraw an input that is still pending with POST /pending-inputs/{pending_input_id}/cancel. A turn may hold at most eight pending inputs.

Limits are visible after admission

The acknowledgement and Invocation echo the resolved limits. That lets the host see the actual defaults and service ceilings it received.

External host and callback waits are unbounded when waiting_timeout_seconds is omitted. During that wait, deadline_at is null and the active and total clocks are paused. Set a positive waiting limit only when the workflow has a real service deadline.