Anomaly Detection

Anima continuously monitors agent behavior and compares it against learned baselines to detect unusual activity. When anomalies are detected, agents can be automatically quarantined to prevent damage while alerts are sent for human review.

How It Works

Baseline Learning — Anima observes agent behavior over a configurable window to establish normal patterns
Real-Time Monitoring — Every action is compared against the baseline in real time
Detection Rules — Built-in and custom rules flag deviations
Response Actions — Anomalies trigger alerts, require approval, or quarantine the agent

Behavioral Baselines

Baselines are computed per-agent across multiple dimensions:

Dimension	What It Tracks
Email volume	Emails sent/received per hour, day
Recipient patterns	Typical recipients and new-contact frequency
Spending velocity	Transaction frequency and amount patterns
API call rate	Requests per minute by endpoint
Active hours	Typical hours of activity
Data access	Vault secret access patterns
A2A communication	Task delegation frequency and partner agents

Tab Title
Tab Title

import { Anima } from "@anima-labs/sdk";

const anima = new Anima({ apiKey: "ak_..." });

// View an agent's current behavioral baseline
const baseline = await anima.anomalyDetection.getBaseline("ag_8f3k2m9x1n4p7q6r");

console.log(`Baseline period: ${baseline.windowDays} days`);
console.log(`Avg emails/day: ${baseline.emailVolume.avgPerDay}`);
console.log(`Avg spend/day: $${(baseline.spending.avgDailyCents / 100).toFixed(2)}`);
console.log(`Active hours: ${baseline.activeHours.start}-${baseline.activeHours.end}`);

from anima import Anima

anima = Anima(api_key="ak_...")

baseline = anima.anomaly_detection.get_baseline("ag_8f3k2m9x1n4p7q6r")

print(f"Baseline period: {baseline.window_days} days")
print(f"Avg emails/day: {baseline.email_volume.avg_per_day}")
print(f"Avg spend/day: ${baseline.spending.avg_daily_cents / 100:.2f}")

Detection Rules

Built-In Rules

Rule	Trigger	Default Action
`email_volume_spike`	Emails sent exceed 3x baseline in 1 hour	Alert
`new_recipient_burst`	10+ new recipients in 1 hour	Alert
`spending_spike`	Spend exceeds 5x daily baseline	Quarantine
`off_hours_activity`	Activity outside established active hours	Alert
`vault_mass_access`	5+ vault secrets accessed in 1 minute	Quarantine
`api_rate_anomaly`	API calls exceed 10x per-minute baseline	Throttle
`a2a_unknown_agent`	Task sent to never-before-seen agent	Approval

Custom Rules

Define custom detection rules for your specific use case:

Tab Title
Tab Title

await anima.anomalyDetection.rules.create({
  name: "high-volume-email-new-recipient",
  description: "Flag high email volume to recipients never sent to before",
  conditions: [
    { field: "category", operator: "eq", value: "email.send" },
    { field: "metadata.batchSize", operator: "gt", value: 100 },
    { field: "metadata.to", operator: "not_in_baseline", value: true },
  ],
  action: "require_approval",
  severity: "high",
  enabled: true,
});

anima.anomaly_detection.rules.create(
    name="high-volume-email-new-recipient",
    description="Flag high email volume to recipients never sent to before",
    conditions=[
        {"field": "category", "operator": "eq", "value": "email.send"},
        {"field": "metadata.batchSize", "operator": "gt", "value": 100},
        {"field": "metadata.to", "operator": "not_in_baseline", "value": True},
    ],
    action="require_approval",
    severity="high",
    enabled=True,
)

Quarantine

When an agent is quarantined, all its outbound actions are suspended until a human reviews the flagged activity.

// Manually quarantine an agent
await anima.anomalyDetection.quarantine("ag_8f3k2m9x1n4p7q6r", {
  reason: "Unusual spending pattern detected",
});

// Release an agent from quarantine
await anima.anomalyDetection.release("ag_8f3k2m9x1n4p7q6r", {
  reviewedBy: "admin@acme.com",
  notes: "Confirmed legitimate activity -- budget increase approved",
});

// List quarantined agents
const quarantined = await anima.anomalyDetection.listQuarantined();

Anomaly Alerts

Configure how anomaly alerts are delivered:

await anima.anomalyDetection.configureAlerts({
  channels: [
    { type: "webhook", url: "https://acme.com/webhooks/anomaly" },
    { type: "email", address: "security@acme.com" },
    { type: "slack", webhookUrl: "https://hooks.slack.com/..." },
  ],
  minSeverity: "medium", // "low" | "medium" | "high" | "critical"
});

API Reference

Endpoint	Method	Description
`https://api.useanima.sh/api/anomaly-detection/baselines/:agentId`	GET	Get agent behavioral baseline
`https://api.useanima.sh/api/anomaly-detection/rules`	POST	Create a detection rule
`https://api.useanima.sh/api/anomaly-detection/rules`	GET	List detection rules
`https://api.useanima.sh/api/anomaly-detection/rules/:id`	PUT	Update a detection rule
`https://api.useanima.sh/api/anomaly-detection/rules/:id`	DELETE	Delete a detection rule
`https://api.useanima.sh/api/anomaly-detection/alerts`	GET	List recent anomaly alerts
`https://api.useanima.sh/api/anomaly-detection/quarantine`	POST	Quarantine an agent
`https://api.useanima.sh/api/anomaly-detection/quarantine`	GET	List quarantined agents
`https://api.useanima.sh/api/anomaly-detection/release`	POST	Release from quarantine
`https://api.useanima.sh/api/anomaly-detection/alerts/config`	PUT	Configure alert channels

Configuration

Variable	Default	Description
`ANIMA_ANOMALY_BASELINE_WINDOW_DAYS`	`14`	Days of data used to compute baselines
`ANIMA_ANOMALY_SENSITIVITY`	`medium`	Detection sensitivity (low/medium/high)
`ANIMA_ANOMALY_AUTO_QUARANTINE`	`true`	Auto-quarantine on critical anomalies
`ANIMA_ANOMALY_COOLDOWN_MINUTES`	`30`	Cooldown between repeated alerts

Next Steps

Audit Log — Review the events that triggered anomalies
SOC 2 Controls — Map anomaly detection to compliance
Compliance Reporting — Include anomaly metrics in reports

​Anomaly Detection

​How It Works

​Behavioral Baselines

​Detection Rules

​Built-In Rules

​Custom Rules

​Quarantine

​Anomaly Alerts

​API Reference

​Configuration

​Next Steps