Agent Management

The agent registry is the foundation of SidClaw. Every AI agent that interacts with your systems must be registered with an identity, authority model, and lifecycle state. Policies are evaluated against agent identities, and all actions are traced back to the originating agent.

Creating an agent

curl -X POST https://api.agentidentity.dev/api/v1/agents \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Handles tier-1 customer support inquiries",
    "owner_name": "Jane Smith",
    "owner_role": "Engineering Lead",
    "team": "Customer Success",
    "environment": "prod",
    "authority_model": "delegated",
    "identity_mode": "delegated_identity",
    "delegation_model": "on_behalf_of_user",
    "autonomy_tier": "medium",
    "authorized_integrations": [
      {
        "name": "zendesk",
        "resource_scope": "tickets/*",
        "data_classification": "confidential",
        "allowed_operations": ["read_ticket", "update_ticket", "add_comment"]
      },
      {
        "name": "knowledge_base",
        "resource_scope": "*",
        "data_classification": "internal",
        "allowed_operations": ["search", "read"]
      }
    ],
    "next_review_date": "2026-06-21T00:00:00Z",
    "created_by": "[email protected]"
  }'

Agent fields

Field	Type	Description
`name`	`string`	Human-readable name for the agent.
`description`	`string`	What the agent does.
`owner_name`	`string`	Person or team responsible for the agent.
`owner_role`	`string`	Role of the owner (e.g., "Engineering Lead").
`team`	`string`	Team that owns the agent.
`environment`	`string`	Deployment environment: `dev`, `test`, or `prod`.
`authority_model`	`string`	How the agent derives authority: `self`, `delegated`, or `hybrid`.
`identity_mode`	`string`	Identity type: `service_identity`, `delegated_identity`, or `hybrid_identity`.
`delegation_model`	`string`	Who the agent acts on behalf of: `self`, `on_behalf_of_user`, `on_behalf_of_owner`, or `mixed`.
`autonomy_tier`	`string`	Level of autonomous operation: `low`, `medium`, or `high`.
`lifecycle_state`	`string`	Current state: `active`, `suspended`, or `revoked`. Set automatically.
`authorized_integrations`	`array`	List of integrations the agent is authorized to use.
`metadata`	`object \| null`	Arbitrary metadata for custom fields.
`next_review_date`	`string`	When the agent's registration should be reviewed.
`created_by`	`string`	Who registered the agent.

Lifecycle management

Agents follow a strict lifecycle state machine. Transitions are validated -- invalid transitions return an error.

active  ──→  suspended  ──→  revoked
  │                              ▲
  └──────────────────────────────┘

active: The agent can invoke tools and have actions evaluated.
suspended: The agent is temporarily disabled. Evaluation requests for suspended agents will be denied. Can be reactivated.
revoked: The agent is permanently disabled. This is a terminal state -- revoked agents cannot be reactivated.

Suspend an agent

curl -X POST https://api.agentidentity.dev/api/v1/agents/{id}/suspend \
  -H "Authorization: Bearer $API_KEY"

Revoke an agent

curl -X POST https://api.agentidentity.dev/api/v1/agents/{id}/revoke \
  -H "Authorization: Bearer $API_KEY"

Reactivate a suspended agent

curl -X POST https://api.agentidentity.dev/api/v1/agents/{id}/reactivate \
  -H "Authorization: Bearer $API_KEY"

All lifecycle changes create an audit trace with a lifecycle_changed event, recording the previous state, new state, and who made the change.

Listing and filtering agents

curl "https://api.agentidentity.dev/api/v1/agents?environment=prod&lifecycle_state=active&limit=20&offset=0" \
  -H "Authorization: Bearer $API_KEY"

Query parameters:

Parameter	Type	Description
`environment`	`string`	Filter by environment (`dev`, `test`, `prod`).
`lifecycle_state`	`string`	Filter by state (`active`, `suspended`, `revoked`).
`authority_model`	`string`	Filter by authority model (`self`, `delegated`, `hybrid`).
`autonomy_tier`	`string`	Filter by autonomy tier (`low`, `medium`, `high`).
`search`	`string`	Search by agent name or owner name (case-insensitive).
`limit`	`number`	Maximum results per page (default: 20, max: 100).
`offset`	`number`	Number of results to skip for pagination.

Response:

{
  "data": [ ... ],
  "pagination": { "total": 42, "limit": 20, "offset": 0 }
}

Agent detail

Retrieve a single agent with its recent activity statistics.

curl https://api.agentidentity.dev/api/v1/agents/{id} \
  -H "Authorization: Bearer $API_KEY"

The detail response includes:

All agent fields
Stats: policy counts by effect, pending approvals, traces in the last 7 days, last activity timestamp
Recent traces: the 10 most recent audit traces
Recent approvals: the 5 most recent approval requests

Updating an agent

Update agent metadata with a PATCH request. Lifecycle state cannot be changed via PATCH -- use the lifecycle endpoints above.

curl -X PATCH https://api.agentidentity.dev/api/v1/agents/{id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "autonomy_tier": "high",
    "next_review_date": "2026-09-21T00:00:00Z"
  }'

Dashboard

In the SidClaw dashboard, the Agents page provides:

A searchable, filterable table of all registered agents
Lifecycle state badges (green for active, amber for suspended, red for revoked)
Click-through to agent detail with activity stats, recent traces, and policy summary
Lifecycle action buttons (Suspend, Revoke, Reactivate) with confirmation dialogs
Environment and autonomy tier filters

Agent Management

On this page