Agents¶

The Agents page lets you view, register, and manage AI agents within your tenant. Every policy check, audit log, and anomaly report is associated with a registered agent.

Agent List¶

The agents table displays all registered agents with pagination:

Column	Description
Name	Human-readable agent identifier
Type	Agent category (`llm`, `rag`, `action`, `orchestrator`, …)
Predicted	ML predicted type from embeddings (capabilities + recent actions)
Risk	Embedding risk score rollup from recent audit risk
Status	`active`, `inactive`, or `error` (from last heartbeat)
Version	Declared agent version
Last Seen	Time since last heartbeat
Actions	View / delete

Click an agent row to open the Agent Details view.

Search¶

Server-side semantic search is available via GET /api/v1/agents/search?q=... (hashed embeddings over name, type, capabilities, and recent actions). The header search and Agents page filter navigate to /agents?q=... and call this endpoint when the query is non-empty.

Embeddings are upserted on register, refreshed on heartbeat (if stale), and best-effort after audit writes.

Shadow AI Discovery¶

Route: /discovery

Unregistered activity (orphan anomaly reports, webhooks without a known agent_id, LangChain/OpenAI discovery fallback) can surface as discovery candidates:

Action	Endpoint	Description
List	`GET /api/v1/discovery/candidates`	Pending candidates with score + evidence
Ingest	`POST /api/v1/discovery/ingest`	Single event
Batch	`POST /api/v1/discovery/ingest/batch`	Batch + optional cluster merge
Cluster	`POST /api/v1/discovery/cluster`	Async merge of similar pending candidates
Confirm	`POST /api/v1/discovery/candidates/{id}/confirm`	HITL → register agent + link fingerprint
Dismiss	`POST /api/v1/discovery/candidates/{id}/dismiss`	Close without registering

Confirming registers a new agent and links fingerprint history. Metrics: shadow_candidates_total, shadow_time_to_confirm_seconds; alerts ShadowAICandidateBacklog.

Registering an Agent¶

Via the API¶

curl -X POST http://localhost:8000/api/v1/agents/register \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-bot",
    "type": "llm",
    "capabilities": ["observe", "track", "respond"],
    "permissions": {"max_risk": 0.7}
  }'

Via the Python SDK¶

from aegisai.sdk import AegisAIClient

async with AegisAIClient(
    api_key="your-api-key",
    agent_name="customer-support-bot",
) as client:
    registration = await client.register(
        capabilities=["observe", "track"],
    )
    print(f"Registered: {registration.id}")

Agent ID

Save the returned id (UUID). It is required for policy checks, audit logging, and HITL requests.

Heartbeats¶

Agents should send periodic heartbeats to maintain active status:

curl -X POST http://localhost:8000/api/v1/agents/<agent-id>/heartbeat \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Agents without recent heartbeats may appear as inactive in the dashboard.

Agent Details¶

The detail view (/agents/:id) shows:

Full agent metadata (name, type, capabilities, permissions)
Predicted type + confidence and embedding risk from agent_embeddings
Registration and last heartbeat timestamps
Recent audit log entries for this agent
Associated anomaly reports

Managing Agents¶

Action	Method	Endpoint	Required Role
List	`GET`	`/api/v1/agents`	Developer+
Get	`GET`	`/api/v1/agents/{id}`	Developer+
Details	`GET`	`/api/v1/agents/{id}/details`	Developer+
Update	`PUT`	`/api/v1/agents/{id}`	Developer+
Delete	`DELETE`	`/api/v1/agents/{id}`	Admin+
Heartbeat	`POST`	`/api/v1/agents/{id}/heartbeat`	API key

Agent Types¶

Type	Description
`llm`	Large language model agent
`tool`	Tool-calling or function agent
`workflow`	Multi-step orchestration agent
`custom`	Other agent architectures

Best Practices¶

Recommendations

Register before operating — unregistered agents cannot pass policy checks
Send heartbeats every 60s — keeps status accurate in the dashboard
Declare capabilities honestly — used in policy evaluation context
One agent per logical service — simplifies audit and anomaly correlation
Use descriptive names — e.g., prod-billing-llm not agent-1

Python SDK — programmatic agent integration
Policies — attach policies to agent actions
Audit — view agent action history