Agent Governance

Agent governance lets external runtimes route consequential steps through Orlo for policy, validation, approval, and audit decisions.

Core concepts

  • Agent session — one governed trajectory
  • Agent step — one model, tool, retrieval, approval, or decision boundary
  • Governed step envelope — the normalized record Orlo stores for step request, result, citations, timing, policy decision, and state change
  • Tool policy — allow, allow with warning, reject, or require approval; a tool with no matching policy is rejected, and when several match the strictest wins
  • Runtime limit — max steps, tool calls, write actions, external side effects, and inactivity timeout; the narrowest matching limit applies
  • Approval — human checkpoint for gated steps
  • Trace sample — a reviewed trajectory artifact that can later be promoted into evaluation data
  • Trajectory result — path-quality scoring computed from a session or trace sample

Sessions

  • POST /v1/agent-sessions
  • GET /v1/agent-sessions
  • GET /v1/agent-sessions/:session_id
  • PATCH /v1/agent-sessions/:session_id

Create a session before beginning a governed trajectory. Sessions can later be marked completed, failed, cancelled, or timed_out.

Session detail returns:

  • session metadata
  • governed steps
  • lifecycle events
  • trajectory_result
  • trajectory_step_results

Govern steps

POST /v1/agent-sessions/:session_id/steps/govern

Primary governance endpoint for step evaluation.

Typical step types:

  • model_call
  • model_output
  • tool_request
  • tool_result
  • retrieval
  • decision
  • approval_request
  • approval_result
  • state_transition

Each governed step can carry:

  • normalized request payload
  • normalized result payload
  • citations
  • policy decision artifact
  • timing metadata
  • optional state change evidence

POST /v1/agent-sessions/:session_id/tools/check

Fast path for tool authorization checks when a runtime wants a cheaper preflight than full step governance.

Events and streaming

  • GET /v1/agent-sessions/:session_id/events
  • GET /v1/agent-sessions/:session_id/events/stream

Use the polling route for snapshots and the SSE route for live operational views.

The stream emits:

  • one connected event when the stream opens
  • one event per stored session event using its event_type
  • heartbeat comments to keep long-lived connections healthy

Trace import and review

  • POST /v1/agent-sessions/:session_id/traces/import
  • POST /v1/agent-sessions/:session_id/steps
  • POST /v1/agent-sessions/:session_id/steps/:step_id/promote-to-trace-sample
  • GET /v1/trace-samples
  • GET /v1/trace-samples/:id
  • POST /v1/trace-samples/:id/annotations
  • POST /v1/trace-samples/:id/promote-to-dataset

These routes support imported traces, externally recorded steps, reviewed trace samples, and the trace-to-dataset loop.

Annotations require a signed-in member with review access. Orlo records the author from that sign-in; an application key cannot label its own evidence as reviewed.

Trace sample detail returns:

  • the stored trace sample
  • annotations
  • trajectory_result
  • trajectory_step_results

Policies and limits

  • GET /v1/tool-policies (task_id, deployment_id filters; also lists the built-in bookkeeping tools)
  • GET /v1/runtime-limits (returns the rows and the effective base limits)

Configure agent permissions and limits in the console. These changes require a signed-in person with the appropriate access; a runtime key gets 403 PEOPLE_ONLY.

Sessions and skills

POST /v1/agent-sessions takes task_id and optionally external_run_id, goal, framework, risk_tier, autonomy_level, metadata, and skill_versions: up to eight {skill_id, version_id, content_hash} references, which Orlo verifies against published, non-retired versions before the session starts (409 SKILL_VERSION_UNAVAILABLE otherwise). The response includes blocking_step_types, the step types whose decision the runtime must wait for.

GET /v1/agent-steps lists steps across runs since a time (since, limit up to 5,000, task_id), for overviews.

POST /v1/agent-sessions/:session_id/steps/:step_id/add-to-standard adds a step to the task’s examples.

Measured permissions

Tool permissions can include typed argument_conditions. Measured bands use those conditions with shadow observations, independent reviews, and explicit member enablement for one configuration. Start runs with model and application revision metadata.

The console provides historical preview, View evidence and status, lifecycle actions, and independent review. These are member actions; runtime keys cannot create their own reviewed evidence, enable a band, or resume it. See measured permissions.

Action reports

  • POST /v1/agent-sessions/:session_id/actions/:action_id/reports — append an execution or business outcome; requires agent_governance.run.
  • GET /v1/agent-sessions/:session_id/actions/:action_id/reports — latest outcomes and paginated history; requires agent_governance.read.

Use the action_id returned by a governed tool request. Reports record what the application says happened; they do not authorize execution. Request examples, receipts, and retry behavior.

Approvals

  • GET /v1/agent-approvals
  • GET /v1/agent-approvals/:id
  • POST /v1/agent-sessions/:session_id/steps/:step_id/request-approval

An approval is bound to the step’s tool name and arguments and is consumed once. A person with Approver access decides in the console. Orlo records their identity. An approval expires per its timeout and timeout action, and Orlo sends approval.requested, approval.expiring, approval.escalated, approval.expired, approval.approved, and approval.rejected to the organization’s notification endpoints.

Notes

  • Orlo decides; the runtime that runs the tools enforces, through the SDK.
  • The public API is designed to work well with thin wrappers, callbacks, and proxy-based integrations.
  • Trajectory scoring is path-aware. It is not limited to final text quality.

Approval updates

Read one approval with GET /v1/agent-approvals/:id and agent_governance.read. It returns the approval directly, including status, session_id, step_id, deadline fields, decided_at, decided_by, and consumed_at. An unknown ID or an ID in another organization returns 404 APPROVAL_NOT_FOUND. The response is not cached; elapsed approval deadlines are applied before reporting status.

Subscribe to approval.approved, approval.rejected, and approval.expired to wake a waiting worker. Notifications do not execute tools. Read current status and retry the original governed step with unchanged arguments. See Webhooks and approvals.