Agent Discovery

Overview

The Agent Discovery service automatically registers and tracks agents as they send telemetry to the platform. No manual configuration required - agents are discovered from run data and enriched with real-time metrics.

Automatic registration

When an agent sends its first run via the ingest endpoint, the platform automatically:

Creates an agent record with agent_id from the run
Tracks first seen and last seen timestamps
Begins calculating metrics (runs, actions, costs, success rates)
Monitors intervention and approval rates

Agent endpoints

List agents

GET /api/v1/agents

Query parameters:

agent_id (optional): Filter by agent ID (partial match)
sort_by (optional): Sort field - last_seen, first_seen, total_runs, total_cost, intervention_rate
sort_order (optional): asc or desc (default: desc)

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "$AGENT_SENTINEL_URL/api/v1/agents?sort_by=total_cost&sort_order=desc"

Response:

{
  "agents": [
    {
      "agent_id": "trading-bot",
      "display_name": "Trading Bot",
      "description": "Automated trading agent",
      "organization_id": "org_123",
      "first_seen": "2024-12-01T10:00:00Z",
      "last_seen": "2024-12-28T14:30:00Z",
      "total_runs": 1234,
      "total_actions": 45678,
      "total_cost_usd": 567.89,
      "success_rate": 0.95,
      "intervention_rate": 0.02,
      "is_active": true,
      "created_at": "2024-12-01T10:00:00Z",
      "updated_at": "2024-12-28T14:30:00Z"
    }
  ]
}

Get agent details

GET /api/v1/agents/{agent_id}

Returns detailed agent information including calculated metrics.

Get agent statistics

GET /api/v1/agents/{agent_id}/stats

Returns comprehensive statistics:

{
  "agent_id": "trading-bot",
  "display_name": "Trading Bot",
  "description": "Automated trading agent",
  "total_runs": 1234,
  "total_actions": 45678,
  "total_cost_usd": 567.89,
  "success_rate": 0.95,
  "avg_cost_per_run": 0.46,
  "avg_actions_per_run": 37.0,
  "intervention_rate": 0.02,
  "interventions_count": 912,
  "approval_metrics": {
    "total_approvals": 45,
    "pending_approvals": 2,
    "approval_rate": 0.89,
    "avg_decision_time_seconds": 180.5
  },
  "recent_activity": {
    "last_24h": {
      "runs": 48,
      "actions": 1776,
      "cost_usd": 22.34
    },
    "last_7d": {
      "runs": 334,
      "actions": 12358,
      "cost_usd": 154.89
    },
    "last_30d": {
      "runs": 1234,
      "actions": 45678,
      "cost_usd": 567.89
    }
  },
  "days_active": 28,
  "first_seen": "2024-12-01T10:00:00Z",
  "last_seen": "2024-12-28T14:30:00Z"
}

Update agent metadata

PATCH /api/v1/agents/{agent_id}

Update display name and description (agents cannot be manually created or deleted):

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Production Trading Bot",
    "description": "High-frequency trading agent for production environment"
  }' \
  "$AGENT_SENTINEL_URL/api/v1/agents/trading-bot"

Only display_name and description can be updated. All other fields are automatically calculated from run data.

Calculated metrics

The platform automatically calculates:

Activity metrics

Total runs: Count of all runs
Total actions: Count of all actions across runs
Total cost: Sum of costs (USD)
Success rate: Percentage of successful actions
Average cost per run: Mean cost per run
Average actions per run: Mean actions per run

Intervention metrics

Intervention rate: Percentage of actions that triggered interventions
Interventions count: Total number of interventions
High-risk blocks: Count of critical/high-risk interventions prevented

Approval metrics

Total approvals: Count of approval requests
Pending approvals: Currently pending approval requests
Approval rate: Percentage of approvals granted
Average decision time: Mean time to approve/reject (seconds)

Recent activity

Last 24 hours: Runs, actions, cost
Last 7 days: Runs, actions, cost
Last 30 days: Runs, actions, cost

Temporal data

Days active: Count of unique days with activity
First seen: Timestamp of first run
Last seen: Timestamp of most recent run

Filtering agents in the UI

In the web console, navigate to Agents page to:

View all discovered agents
Sort by activity, cost, or intervention rate
Click an agent to see detailed statistics
Edit display name and description
View recent runs for an agent
Link to agent’s actions in Activity Ledger

Gateway decisions

GET /api/v1/gateway-decisions

Lists the gateway’s decision rows (every allow, deny and require_approval returned by POST /api/v1/gateway/authorize or an approval redemption), newest first, with each row’s reason code, budget reservation state, budget headroom and per-row integrity. Read-only. Query parameters:

agent_id (optional): Only this agent’s decisions. Ignored for agent-bound API keys.
decision (optional): allow, deny or require_approval
limit (optional): Integer from 1 to 200 (default: 50)
before_seq (optional): Integer ≥ 1. Only rows with seq below this value. Pass the previous page’s next_before_seq.

Any other value is rejected with 422. Scope:

A user session sees its active organization.
An API key sees the key’s organization. A key with no organization sees no decisions.
An agent-bound API key sees only its own agent’s decisions, whatever agent_id is passed.

Example:

curl -H "Authorization: ApiKey $SENTINEL_API_KEY" \
  "$AGENT_SENTINEL_URL/api/v1/gateway-decisions?decision=allow&limit=50"

Response:

{
  "data": [
    {
      "id": "6f1c2a9e-1d7b-4f61-9a43-0c5e2b7d8a10",
      "seq": 1042,
      "timestamp": "2026-10-26T14:30:00",
      "agent_id": "trading-bot",
      "run_id": "a3d9e0b2-6c41-4c2e-8f0e-2b5f7c9d1e44",
      "action_name": "send_email",
      "decision": "allow",
      "reason_code": "advisory_read",
      "policy_id": null,
      "matched_rule": null,
      "approval_request_id": null,
      "redeems_approval_request_id": null,
      "reservation_id": "c7b1e5d4-2f8a-4b9c-9e3d-5a6f1b2c3d4e",
      "reserved_usd": 0.5,
      "reservation_status": "reserved",
      "actual_cost_usd": null,
      "remaining_usd": 9.5,
      "key_id": "prod-2026-10",
      "signed": true,
      "hash_ok": true,
      "signature_ok": true
    }
  ],
  "next_before_seq": 1042
}

reserved_usd, reservation_status (reserved, reconciled or released) and actual_cost_usd come from the decision’s budget reservation in the same organization; they are null when the decision held none.
remaining_usd is the monthly budget headroom recorded at decision time, null when none was recorded (for example, a deny, or no monthly budget).
hash_ok recomputes the row’s hash and compares it with the stored row_hash. signature_ok verifies the row’s signature against the platform key: null for an unsigned row, and false for a signed row when the platform has no signing key configured.
next_before_seq is null on the last page.

Per-row integrity tells you whether a single decision was altered. To verify that no rows were removed or reordered, use whole-chain verification: GET /api/v1/ledger/verify.

Agent scoping

Agents are scoped to organizations - each organization sees only their agents. Use the agent discovery system to:

Monitor agent performance across your fleet
Identify high-cost agents
Track agents with high intervention rates (indicating policy issues)
Analyze approval patterns by agent

Best practices

Use meaningful agent_id values: Agent IDs should be descriptive and unique (e.g., “trading-bot-prod”, “customer-support-agent-v2”).

Add display names: Update agents with human-readable display names and descriptions for easier identification in the UI.

Monitor intervention rates: High intervention rates indicate agents attempting actions blocked by policies - review and adjust either agent logic or policies.

Agent IDs cannot be changed: Once an agent sends its first run, its agent_id is permanent. Plan your naming scheme carefully.

Getting started

Concepts

SDK (Python)

AI tools

Platform API

Web Console

Overview

Automatic registration

Agent endpoints

List agents

Get agent details

Get agent statistics

Update agent metadata

Calculated metrics

Activity metrics

Intervention metrics

Approval metrics

Recent activity

Temporal data

Filtering agents in the UI

Gateway decisions

Agent scoping

Best practices

See also