Skip to main content

Agent Policies — Governed Autonomy

An Agent Policy is a versioned authority boundary for an agent. It sits on top of the existing real-world action governance flow and decides, for each proposed action, whether the agent may execute it automatically or must hand it to a human. A policy can only ever narrow autonomy — the strongest verdict it hands out is "allow auto", and it only reaches that when every rule is satisfied and the policy explicitly opts in.

Scenario: An agent proposes to push a doc change and to run a database migration. The agent's policy auto-approves the low-risk doc change (its rubric score clears the auto-execute threshold) but holds the migration for human review — migrations are on the policy deny list.

How it relates to Action Proposals

FleetQ already governs autonomous side effects through Action Proposals: when an agent wants to do something in the real world it creates an ActionProposal (status pending), which a deterministic five-dimension DecisionRubric scores. Agent Policies add a versioned, per-agent layer on top of that rubric: the policy reads the rubric score plus the proposal's risk and target, and returns a verdict. The proposal then ends executed (auto), waits for a human, or is rejected.

Policies are backward-compatible and opt-in. With the feature flag off, or when no enabled policy resolves for an agent, nothing changes — the existing approval behavior is preserved.

Versioned, rollback-able rules

An AgentPolicy row is just a current-pointer; the authoritative rules live on a pinned AgentPolicyVersion. Changing a policy mints a new version rather than mutating in place, so every change is an immutable, auditable, rollback-able event. A policy is either active or archived.

Policy resolution (precedence)

AgentPolicyResolver picks the effective policy for a (team, agent) pair by precedence:

  1. The agent-specific active + enabled policy, if one exists;
  2. otherwise the team-default policy (one with a null agent_id);
  3. otherwise none — the caller keeps its legacy behavior.

What the evaluator checks

PolicyEvaluator is pure and deterministic. It walks the resolved version's rules in order; anything uncertain falls back to "require human":

Rule Effect
Denied target types Hard deny — e.g. migrations are never auto-runnable.
Allow list When set, anything outside it is held for review (not denied).
Sensitive paths Raise the effective risk and force review — "be careful", not a hard block.
Spend / frequency caps Exceeding the per-window cap holds for review; it never auto-drops the action.
Risk ceiling Risk above the policy's ceiling → review. Critical risk always requires a human.
Auto-execute opt-in Auto only when explicitly enabled and the rubric total clears the policy threshold.

Proposal explain & faithful replay

Because the policy version in force is pinned onto the proposal, ProposalExplainResolver can reconstruct a reproducible "why" record long after the policy changes or is rolled back. The explain payload returns the proposal details, the rubric breakdown, the exact policy verdict, the pinned version's rules, and the proposal's lineage — so an auditor sees precisely the rules that produced the decision. This is surfaced via the action_proposal_explain MCP tool.

In the UI

  • Policies lists policies with their status, scope (agent or team-default), and current version.
  • Create defines a new policy and its first rule set.
  • The policy detail page shows version history and lets you roll back to an earlier version.
  • Proposed actions and their verdicts appear in the Approval Inbox.

MCP tools

Tool Description
agent_policy_list List policies for the team.
agent_policy_get Fetch a policy with its current version rules.
agent_policy_create Create a policy and its first version.
agent_policy_update Mint a new version with revised rules.
agent_policy_rollback Roll the current pointer back to an earlier version.
action_proposal_list / _get / _approve / _reject / _explain Inspect and decide the proposals a policy governs, and explain any verdict.

Related concepts