> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime Steering

> Send durable instructions to an active Run at safe agent boundaries

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:

```json theme={null}
{
  "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:

```ts theme={null}
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:

```ts theme={null}
const receipt = await polpo.getSteeringReceipt(runId, messageId);
```

Abort remains a separate explicit command:

```ts theme={null}
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

```bash theme={null}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.