Runtime Steering

Runtime Steering lets an application change the direction of an active direct-chat or Project Loop Run without interrupting an in-flight tool. Polpo accepts the instruction durably, then the active agent node consumes it at its next safe boundary. The response is a receipt. Admission and delivery are separate:

accepted means Polpo persisted the instruction;
delivered means the runtime added it to a later model turn;
rejected means the effective node, Loop, or agent policy refused it;
too_late means the Run had crossed its final safe boundary;
duplicate means the same idempotency key was already seen.

Configure a policy

Set a default on an agent:

{
  "name": "support",
  "steering": {
    "acceptance": "best_effort",
    "outcomes": {
      "rejected": {
        "action": "reply",
        "messages": {
          "en": "This Run cannot accept changes now.",
          "it": "Questa esecuzione non può accettare modifiche ora."
        }
      },
      "too_late": {
        "action": "return",
        "messages": {
          "en": "The Run has already finished."
        }
      }
    }
  }
}

accept, reject, and best_effort are configuration values. too_late is a runtime outcome. Project Loop defaults and individual agent nodes can override the agent policy. English is the deterministic fallback for localized outcome messages; keys use BCP 47 language tags.

Send an instruction

Use the active Run id returned in x-polpo-run-id or exposed by the SDK:

const result = await polpo.steerRun(runId, {
  id: crypto.randomUUID(),
  mode: "steer",
  locale: "it-IT",
  content: { text: "Mantieni lo schema esistente e aggiungi solo l'indice." },
});

console.log(result.receipt.admission); // accepted

Use mode: "follow_up" when the instruction should run only after the current work would otherwise finish. Reuse the same id when retrying an uncertain request; reusing an id with different content is rejected. Read the terminal receipt later:

const receipt = await polpo.getSteeringReceipt(runId, messageId);

Abort remains a separate explicit command:

await polpo.abortRun(runId, "Cancelled by the application");

Steering carries application context attached to the Run, but Polpo authenticates the project and environment API key. Keep the Run id associated with the external user in your application when you need user-level authorization.

API

curl -X POST "$POLPO_API_URL/v1/runs/$RUN_ID/steering" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "change-42",
    "mode": "steer",
    "locale": "it-IT",
    "content": { "text": "Usa il database esistente." }
  }'

Query GET /v1/runs/{runId}/steering/{messageId} for its receipt, or call POST /v1/runs/{runId}/abort with an optional JSON reason. Managed Cloud stores admission and receipts in the selected Development or Production environment. The OSS runtime exposes the same contracts; a distributed self-hosted deployment must provide a durable SteeringRunRegistry.

Getting Started

Platform

Agents

Orchestration

Runtime Steering

Configure a policy

Send an instruction

API

​Configure a policy

​Send an instruction

​API

Configure a policy

Send an instruction

API