Skip to main content

​
Overview

PF-125 wraps the in-stack agentic loop in a durable, resumable, checkpointed run-state machine. Authoritative state lives in four organization-scoped tables under FORCE row-level security (pf_agent_runs, pf_agent_tasks, pf_agent_run_checkpoints, pf_agent_run_events). Runs act under a scoped AgentPrincipal (PF-30-EN-01 pf_agent_can) — never service_role, never auth.uid() impersonation. This guide covers the controls a tenant administrator owns. For step-by-step incident handling, see the operator runbook in docs/runbooks/pf-125-agent-runs.md.

​
Activation gate (PF-45 flag)

Interactive agent tool use is gated by the feature flag pf.agents.interactive_tools_enabled, seeded off. Flipping it on in production is a human decision, not a deploy step, and it is not a substitute for the guardrail spine — both must hold before any tool reaches a model. Enable it per organization (never globally as a first step): turn it on for one pilot org, drive a single read-only run, watch the Run Timeline audit trail end to end, then widen. To roll back, set the flag to false; tool use stops on the next request because the gate is evaluated per request.

​
Guardrail spine prerequisites

An agent’s tools reach a model only when the full spine holds and the flag is on, on every path identically:
  1. a scoped AgentPrincipal is bound to the run,
  2. redaction is active (PF-27-EN-01),
  3. a budget check is available (PF-111),
  4. injection screening is enabled (PF-126).
In the current release, redaction and injection screening are not yet built, so the spine is unsatisfiable and tools are withheld fail-closed. A write-capable run that reaches the boundary off-spine is refused outright and advanced to failed — never silently downgraded. Confirm all four prerequisites are live before you consider enabling the flag.

​
Permissions

  • pf.agents.runs.view — see the Run Timeline panel.
  • pf.agents.runs.manage — Cancel and Resume runs.
Grant these through the standard role/permission administration screens. Both are organization-scoped; a user only ever sees runs for their own organization under FORCE RLS.

​
Monitoring

The Run Timeline panel (Settings → Platform → Agents → Runs) is the primary monitoring surface. The lifecycle event types are registered in the workflow-events catalog (pf_agent_run_started, pf_agent_run_checkpointed, pf_agent_run_completed, pf_agent_run_failed, pf_agent_run_budget_exceeded; owning_core: pf, category: platform) so downstream automation and dashboards can subscribe — the runtime emitters land with the flag-on rollout, not in Phase 1.

​
Emergency stop

  1. Set pf.agents.interactive_tools_enabled to false for the affected org (or all orgs) — new requests get zero tools on the next call.
  2. Cancel each non-terminal run from the panel, or via pf_agent_run_advance(<id>, 'cancelled', '<reason>').
  3. Review the pf_agent_run_events audit trail for the affected runs and correlate with pf_agent_can grants if a scope looks wrong.
Never bypass the state machine with a direct SQL UPDATE: a BEFORE-UPDATE trigger rejects any direct write to lifecycle_state (even by service_role), and doing so would break the audit trail. State changes go only through the governed RPCs.

​
Auditing & data handling

  • Every run, task, checkpoint, and event is organization_id-scoped under FORCE RLS.
  • No PHI is written to prompts, logs, code, or tests; redaction must be live before the flag is enabled.
  • Checkpoints may carry working state and honor a retention expiry; the audit event trail is append-only.
  • User guide
  • Operator runbook: docs/runbooks/pf-125-agent-runs.md
  • ADR: docs/architecture/decisions/ADR-026*.md
  • Source spec: specs/pf/specs/PF-125*.md