Interventions API

Overview

Interventions are records of when Agent Sentinel’s policy engine actively prevented or modified agent actions. The Interventions API provides:

Query endpoints for intervention history
Statistics showing “blast radius” avoided
Cost prevention metrics
Risk analysis

Endpoints

List interventions

GET /api/v1/interventions

Query parameters:

type (optional): Filter by intervention type
- hard_block, approval_required, rate_limited, budget_exceeded, downgrade, warning
outcome (optional): Filter by outcome
- blocked, escalated, approved_after_review, rejected_after_review, modified, warned
action_name (optional): Filter by action name (exact match)
agent_id (optional): Filter by agent ID
run_id (optional): Filter by run ID
policy_id (optional): Filter by policy that triggered intervention
risk_level (optional): Filter by risk level
- critical, high, medium, low, minimal
start_date (optional): Filter by date range start (ISO 8601)
end_date (optional): Filter by date range end (ISO 8601)
skip (optional): Pagination offset (default: 0)
limit (optional): Page size (default: 50, max: 1000)

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "$AGENT_SENTINEL_URL/api/v1/interventions?type=hard_block&risk_level=critical"

Response:

{
  "interventions": [
    {
      "id": "int_abc123",
      "type": "hard_block",
      "outcome": "blocked",
      "action_name": "delete_production_database",
      "description": "Attempted to delete production database",
      "agent_id": "cleanup-bot",
      "run_id": "run_xyz789",
      "policy_id": "policy_123",
      "policy_name": "Production Safety",
      "risk_level": "critical",
      "estimated_cost_usd": 0.0,
      "actual_cost_usd": 0.0,
      "cost_prevented_usd": 0.0,
      "blast_radius": "Prevented deletion of 1M+ customer records",
      "reason": "Action 'delete_production_database' is on the denied list",
      "agent_intent": "Cleanup old test data",
      "original_inputs": {
        "database": "production",
        "table": "customers"
      },
      "modified_inputs": null,
      "timestamp": "2024-12-28T14:30:00Z",
      "organization_id": "org_123",
      "created_at": "2024-12-28T14:30:00Z"
    }
  ],
  "total": 145,
  "skip": 0,
  "limit": 50
}

Get intervention details

GET /api/v1/interventions/{id}

Returns detailed information about a specific intervention.

Intervention statistics

GET /api/v1/interventions/stats

Returns aggregate statistics showing platform value:

{
  "total_interventions": 1456,
  "by_type": {
    "hard_block": 890,
    "approval_required": 234,
    "rate_limited": 156,
    "budget_exceeded": 120,
    "downgrade": 45,
    "warning": 11
  },
  "by_outcome": {
    "blocked": 1012,
    "escalated": 234,
    "approved_after_review": 156,
    "rejected_after_review": 78,
    "modified": 45,
    "warned": 11
  },
  "cost_prevented_usd": 12456.78,
  "high_risk_blocks": 123,
  "time_series": [
    {
      "date": "2024-12-27",
      "interventions": 48,
      "cost_prevented_usd": 456.78
    },
    {
      "date": "2024-12-28",
      "interventions": 52,
      "cost_prevented_usd": 523.12
    }
  ],
  "top_blocked_actions": [
    {
      "action_name": "send_bulk_email",
      "count": 234,
      "cost_prevented_usd": 4567.89
    },
    {
      "action_name": "delete_user_data",
      "count": 189,
      "cost_prevented_usd": 0.0
    }
  ],
  "top_triggering_policies": [
    {
      "policy_id": "policy_123",
      "policy_name": "Production Safety",
      "count": 456
    },
    {
      "policy_id": "policy_456",
      "policy_name": "Cost Control",
      "count": 234
    }
  ]
}

Create intervention (SDK)

POST /api/v1/interventions

Interventions are primarily created automatically by the SDK when policies trigger, but can also be created manually:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hard_block",
    "outcome": "blocked",
    "action_name": "dangerous_operation",
    "description": "Attempted dangerous operation",
    "agent_id": "my-agent",
    "run_id": "run_123",
    "policy_id": "policy_456",
    "risk_level": "high",
    "estimated_cost_usd": 10.0,
    "blast_radius": "Could have corrupted user data",
    "reason": "Action blocked by safety policy",
    "original_inputs": {"target": "production"}
  }' \
  "$AGENT_SENTINEL_URL/api/v1/interventions"

Redact intervention

POST /api/v1/interventions/{id}/redact

Interventions are audit records - there is no delete endpoint. Superusers can redact free-text fields (action_description, reason, agent_intent) on a record, replacing them with [redacted], without removing the row. The redaction is itself recorded on the intervention’s context field as redacted_by (the superuser’s user ID) and redacted_at (a UTC timestamp):

curl -X POST \
  -H "Authorization: Bearer $SUPERUSER_TOKEN" \
  "$AGENT_SENTINEL_URL/api/v1/interventions/int_abc123/redact"

Intervention types

Type	Description	SDK trigger
`HARD_BLOCK`	Action completely denied	Denied action list, allowlist violation, kill switch
`APPROVAL_REQUIRED`	Escalated for human approval	`requires_human_approval=True`
`RATE_LIMITED`	Blocked due to rate limiting	Rate limit exceeded
`BUDGET_EXCEEDED`	Blocked due to budget constraints	Session/run/action budget exceeded
`PII_BLOCKED`	Action arguments contained PII	PII guardrail
`CONTENT_BLOCKED`	Action arguments triggered moderation	Moderation guardrail
`LOOP_DETECTED`	Same `(action, args)` repeated past threshold inside the window	Loop guardrail
`IDEMPOTENT_REPLAY`	Duplicate call returned a cached result instead of executing	Idempotency guardrail
`DOWNGRADE`	Action parameters modified/reduced	Custom policy logic
`WARNING`	Allowed but flagged as risky	Soft policy violations

Guardrail context payloads

For guardrail blocks, the SDK populates intervention.context with a versioned, typed payload so the console can render a dedicated detail panel:

{
  "guardrail_schema_version": 1,
  "guardrail": "pii",
  "matches": [
    { "category": "email", "field_path": "user.email", "matched_text": "al****@e****.com" }
  ],
  "categories": ["email"],
  "fields": ["user.email"]
}

The guardrail discriminator is one of pii, moderation, loop, or idempotency. See Console → Interventions for how each panel renders.

Enriched fields

After ingest, the platform rewrites the following fields with plain-English versions (the original strings are preserved on the intervention’s audit trail):

reason — one or two sentences explaining the policy concern
agent_intent — what the agent was likely trying to accomplish
risk_level — reassessed severity
remediation_payload.suggested_rewrite — how the agent could safely retry, or null

Enrichment runs out-of-band, so the SDK’s POST /api/v1/ingest/ returns immediately and the enriched fields stream into the console asynchronously. If enrichment is unavailable, the original fields are kept. See SDK → LLM integrations.

Intervention outcomes

Outcome	Description
`BLOCKED`	Action was not executed
`ESCALATED`	Sent for human review via approval inbox
`APPROVED_AFTER_REVIEW`	Human approved after escalation
`REJECTED_AFTER_REVIEW`	Human rejected after escalation
`MODIFIED`	Action parameters were changed before execution
`WARNED`	Action executed with warning logged

Risk levels

Level	Description
`CRITICAL`	Catastrophic impact if allowed (data loss, financial harm)
`HIGH`	Severe impact (production changes, high costs)
`MEDIUM`	Moderate impact (workflow disruption, moderate costs)
`LOW`	Minor impact (logging, low costs)
`MINIMAL`	Negligible impact

Use cases

Platform value demonstration

Show stakeholders what disasters were prevented:

# Get cost prevented this month
curl -H "Authorization: Bearer $TOKEN" \
  "$AGENT_SENTINEL_URL/api/v1/interventions/stats?start_date=2024-12-01"

Security monitoring

Monitor attempted policy violations:

# Get all critical-risk blocks
curl -H "Authorization: Bearer $TOKEN" \
  "$AGENT_SENTINEL_URL/api/v1/interventions?risk_level=critical&outcome=blocked"

Policy tuning

Identify policies that trigger frequently (may need adjustment):

# Get interventions by policy
curl -H "Authorization: Bearer $TOKEN" \
  "$AGENT_SENTINEL_URL/api/v1/interventions?policy_id=policy_123&limit=100"

Agent behavior analysis

Understand which agents are most frequently blocked:

# Get interventions for specific agent
curl -H "Authorization: Bearer $TOKEN" \
  "$AGENT_SENTINEL_URL/api/v1/interventions?agent_id=rogue-bot"

Web console

View interventions in the web console:

Navigate to Interventions page
See dashboard with:
- Total interventions
- Cost saved
- High-risk blocks
- Blocked actions count
Filter by type, outcome, risk level
Click intervention for details including blast radius analysis
Link to adjust triggering policy

Best practices

Review interventions regularly: High intervention rates may indicate overly restrictive policies or misbehaving agents.

Use blast radius field: Document what would have happened if the action was allowed - this demonstrates platform ROI.

Track cost prevented: Even if estimated_cost_usd is 0, interventions prevent non-monetary harm (data loss, reputation damage).

Don’t rely solely on interventions: Some actions may slip through if policies aren’t comprehensive. Use interventions as defense-in-depth.

Getting started

Concepts

SDK (Python)

AI tools

Platform API

Web Console

Overview

Endpoints

List interventions

Get intervention details

Intervention statistics

Create intervention (SDK)

Redact intervention

Intervention types

Guardrail context payloads

Enriched fields

Intervention outcomes

Risk levels

Use cases

Platform value demonstration

Security monitoring

Policy tuning

Agent behavior analysis

Web console

Best practices

See also