Human-in-the-Loop

Send a mid-run steering message to a live agent stage of a running run: the stage stage names, or the run's one live agent stage. Without interrupt, the text is guidance for the stage's session, run as a follow-up turn once its current answer is reached. With interrupt=true, the stage's current model turn (the model request and the tool calls it is running) is stopped first, the session is kept, and the text is the stage's next input. The control is forwarded to the run's worker, and the worker's answer is this response: 202 with outcome: delivered (and the stage's label) once the worker delivered it, 409 with the refusal's code when the worker or Petri refused it, and 202 with outcome: pending when the worker gave no answer within the wait (5 s). A refused control is also a run.notice record on the run's event stream under the same code (steer_refused, no_live_turn, no_such_stage, interrupt_refused).

post/api/v1/runs/{id}/steer

Request

  • The document declares no server URL.
  • Auth
    • HTTP bearer
    • or API key in cookie __fabro_session

Path parameters

idstring required

Unique run identifier (ULID).

Request body

textstring required

The steering message text to deliver as a user turn.

interruptboolean

When true, stop the stage's current model turn first and make this text its next input, in one control. When false (default), the text is guidance the agent runs as a follow-up turn once its current answer is reached.

stagestring

The agent stage to steer: its stage identifier (node_id@visit) or its node name. Omit it to steer the run's one live agent stage; a run with several live agent stages then refuses the steer with a run.notice record.

Example request

{
  "text": "Try a different approach",
  "stage": "code@2"
}

Response

Steer forwarded to the worker: delivered, or pending when the worker gave no answer within the wait.

outcome'delivered' | 'pending' required

What became of a forwarded control: delivered once the worker delivered it to its stage; pending when the worker gave no answer within the wait, in which case the run's event stream says what became of it (a run.notice record on refusal).

stagestring

The label of the stage the control was delivered to (node@visit, or node/e<execution>@visit); absent when the outcome is pending.

Changes

    • info

      added the media type application/json for the response with the status

    • info

      added the new optional request property

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status