Autonomy Policy

Declarative trust rules for tool access — allow, deny, or escalate tool calls at runtime.

Quick Start

const agent = defineAgent({
  name: 'governed-agent',
  description: 'Agent with autonomy policy',
  tools: [readTool, writeTool, deleteTool],
  llm,
  systemPrompt: '...',
  policy: {
    defaultPermission: 'allow',
    tools: [
      { pattern: 'delete*', permission: 'escalate', reason: 'Destructive action' },
      { pattern: 'admin_*', permission: 'deny' },
    ],
    onEscalation: async (request) => {
      console.log(`Approval needed: ${request.reason}`);
      return 'approve'; // or 'deny', 'abort', 'pause'
    },
  },
});

agent = define_agent(
    name="governed-agent",
    description="Agent with autonomy policy",
    tools=[read_tool, write_tool, delete_tool],
    llm=llm,
    system_prompt="...",
    policy={
        "default_permission": "allow",
        "tools": [
            {"pattern": "delete*", "permission": "escalate", "reason": "Destructive action"},
            {"pattern": "admin_*", "permission": "deny"},
        ],
    },
)

PolicyConfig

interface PolicyConfig {
  defaultPermission?: ToolPermission;       // Default: 'allow'
  tools?: ToolPolicy[];                      // Per-tool rules
  costEscalationThreshold?: number;          // Escalate at this cost (USD)
  stepEscalationThreshold?: number;          // Escalate at this step count
  onEscalation?: (request: EscalationRequest) => Promise<EscalationDecision>;
}

ToolPolicy

interface ToolPolicy {
  pattern: string;             // Tool name pattern (glob-like)
  permission: ToolPermission;  // 'allow' | 'deny' | 'escalate'
  reason?: string;             // Why this rule exists
  maxCallsPerRun?: number;     // Max calls per run
}

Pattern Matching

Tool policies support glob-like patterns:

Pattern	Matches
`delete-user`	Exact match
`*`	All tools
`delete_*`	Prefix match
`*_admin`	Suffix match
`dangerous`	Contains match

Escalation Flow

When a tool call is escalated:

onEscalation callback is called (if provided)
Callback returns a decision: 'approve', 'deny', 'abort', or 'pause'
On 'pause', the run enters awaiting_approval status

// EscalationRequest
interface EscalationRequest {
  type: 'tool_call' | 'budget_warning' | 'step_limit';
  toolName?: string;
  toolInput?: unknown;
  reason: string;
  context: {
    runId: string;
    stepCount: number;
    estimatedCostUsd?: number;
  };
}

// EscalationDecision
type EscalationDecision = 'approve' | 'deny' | 'abort' | 'pause';

Next Steps

Tool Permissions — permission types
Escalation — escalation handling

Quick Start

PolicyConfig

ToolPolicy

Pattern Matching

Escalation Flow

Next Steps

On this page