Agents & Identity

In TheWARDN, an agent is any AI system that submits actions for governance. Agents must be registered before they can interact with the governance pipeline. Registration establishes identity, and identity is the foundation of all governance -- every action must be traceable to a specific, verified agent.

Agent Registration

To register an agent, submit a registration request:

POST /agents
Content-Type: application/json

{
  "name": "deploy-bot",
  "description": "Automated deployment agent for the payment service team"
}

Response:

{
  "agent_id": "agt_abc123def456",
  "name": "deploy-bot",
  "description": "Automated deployment agent for the payment service team",
  "status": "active",
  "created_at": "2026-04-10T12:00:00Z",
  "stats": {
    "total_governed": 0,
    "total_cleared": 0,
    "total_held": 0,
    "total_blocked": 0
  }
}

Field	Description
agent_id	Unique, immutable identifier assigned by TheWARDN. Cannot be changed after creation (SGP-16).
name	Human-readable name for the agent. Can be updated.
description	Description of the agent's purpose. Can be updated.
status	Current lifecycle status. Starts as active.
created_at	Registration timestamp. Immutable.
stats	Running governance statistics. Updated with every governed action.

TIP

Use descriptive names and descriptions for agents. These appear in audit records, escrow queues, and compliance reports. A reviewer seeing "agt_abc123" with name "deploy-bot" and description "Automated deployment agent for the payment service team" can make faster, better decisions than seeing an opaque ID alone.

Agent Status Lifecycle

Agents move through a defined status lifecycle:

                  +--------+
                  | active |<------ (reactivation by admin)
                  +--------+        
                      |             
                      v             
                  +--------+        
                  | paused |<------ (admin pauses agent)
                  +--------+        
                      |             
                      v             
                  +---------+       
                  | blocked |<----- (policy violation or admin action)
                  +---------+       
                      |             
                      v             
              +--------------+      
              | deregistered |<---- (admin deregisters)
              +--------------+      
                      |             
                      v             
            +------------------+    
            | identity_revoked |    (permanent, irreversible)
            +------------------+

Status	Can Submit Actions	Description
active	Yes	Normal operating state. Agent can submit actions to /govern.
paused	No	Temporarily suspended. All actions return BLOCKED with reason agent_paused. Admin can reactivate.
blocked	No	Blocked due to policy violations or administrative decision. All actions return BLOCKED with reason agent_blocked. Admin can unblock and return to active or escalate to deregistered.
deregistered	No	Permanently decommissioned. All actions return BLOCKED with reason agent_deregistered. Agent can be re-registered (new agent ID assigned).
identity_revoked	No	Permanent and irreversible. The agent ID can never be reused. All actions return BLOCKED with reason identity_revoked. This status is reserved for compromised agents or agents involved in SGP violations.

Status Transitions

# Pause an agent
PUT /agents/:agent_id/status
{ "status": "paused", "reason": "Maintenance window -- pausing all deployment agents" }

# Reactivate an agent
PUT /agents/:agent_id/status
{ "status": "active", "reason": "Maintenance complete" }

# Block an agent
PUT /agents/:agent_id/status
{ "status": "blocked", "reason": "Agent exceeded rate limits 5 times in 1 hour" }

# Deregister an agent
PUT /agents/:agent_id/status
{ "status": "deregistered", "reason": "Agent retired -- replaced by deploy-bot-v2" }

# Revoke identity (irreversible)
PUT /agents/:agent_id/status
{ "status": "identity_revoked", "reason": "Agent compromised -- credentials exposed" }

WARNING

identity_revoked is a one-way door. Once an agent's identity is revoked, there is no path back. The agent ID is permanently retired. This is enforced by SGP-16 (Immutable Identity). Use this status only when an agent is confirmed compromised or has committed a Tier X violation.

Every status transition is recorded in the audit trail.

Governance Statistics

Every agent maintains running statistics that are updated with each governed action:

Stat	Description
total_governed	Total number of actions submitted to /govern
total_cleared	Number of actions that received CLEARED verdict
total_held	Number of actions that received HELD verdict
total_blocked	Number of actions that received BLOCKED verdict

These statistics provide a quick health check for any agent:

GET /agents/:agent_id

{
  "agent_id": "agt_abc123def456",
  "name": "deploy-bot",
  "status": "active",
  "stats": {
    "total_governed": 1247,
    "total_cleared": 1089,
    "total_held": 142,
    "total_blocked": 16
  }
}

Reading the stats:

• A healthy agent has a high cleared rate (typically 70-90%).
• A blocked rate above 5% suggests the agent is frequently hitting policy boundaries and may need reconfiguration.
• A held rate is determined by the tier configuration -- if most of the agent's actions are Tier B, a high held rate is expected.

Agent-Scoped Configuration

Agents can have individual configuration that overrides tenant-wide defaults:

Tier Override

Force all of an agent's actions to a minimum tier:

PUT /agents/:agent_id/config
Content-Type: application/json

{
  "tier_override": "B",
  "reason": "New agent -- requiring human review until trust is established"
}

When tier_override is set to B, every action from this agent is classified as at least Tier B, regardless of the action type's default tier mapping. This is useful for:

• New agents: Start with Tier B override, remove it after the agent has proven reliable.
• Incident response: Temporarily escalate an agent to Tier B during an incident investigation.
• Compliance: Some regulatory frameworks require human review for all AI actions in certain contexts.

The override acts as a floor, not a ceiling. If an action would normally be Tier C or X, it stays at that higher tier.

Confidence Floor

Set a minimum confidence threshold for the agent:

PUT /agents/:agent_id/config
Content-Type: application/json

{
  "confidence_floor": {
    "incident": 0.85,
    "fix": 0.90,
    "containment": 0.95
  }
}

If the agent submits an action with confidence below these floors, the action's tier is escalated (A to B, B to C).

Agent-Scoped Policies

CHAM policies can be scoped to individual agents:

{
  "type": "rate_limit",
  "scope": "agent",
  "agent_id": "agt_abc123def456",
  "config": {
    "windows": [
      { "period": "1m", "max": 30 },
      { "period": "1h", "max": 500 }
    ],
    "on_exceed": "block"
  }
}

Agent-scoped policies take precedence over tenant-wide policies of the same type.

Listing Agents

GET /agents

Response:

{
  "agents": [
    {
      "agent_id": "agt_abc123def456",
      "name": "deploy-bot",
      "status": "active",
      "stats": {
        "total_governed": 1247,
        "total_cleared": 1089,
        "total_held": 142,
        "total_blocked": 16
      },
      "created_at": "2026-04-10T12:00:00Z"
    },
    {
      "agent_id": "agt_xyz789ghi012",
      "name": "monitor-agent",
      "status": "active",
      "stats": {
        "total_governed": 8421,
        "total_cleared": 8390,
        "total_held": 28,
        "total_blocked": 3
      },
      "created_at": "2026-04-08T09:30:00Z"
    }
  ],
  "total": 2
}

Filter by status:

GET /agents?status=blocked

WHO_I_AM Identity Concept

At a deeper architectural level, TheWARDN implements a concept called WHO_I_AM that originates from the Sentinel engine. WHO_I_AM is an immutable identity payload that is cryptographically verified before every governance evaluation.

For agents, WHO_I_AM manifests as:

1. Immutable core identity: The agent_id, created_at, and registering user cannot be changed after creation (SGP-16).
2. Identity verification on every action: Every POST /govern request is verified against the agent registry. Unregistered or revoked agents are immediately BLOCKED (SGP-15).
3. Cross-agent isolation: One agent's governance context never leaks to another agent's evaluation (SGP-20). An agent cannot see, modify, or influence another agent's escrow records, policies, or statistics.

The WHO_I_AM concept ensures that identity in TheWARDN is not just an authentication token -- it is a governance primitive that carries rights, restrictions, history, and accountability.

Agent Identity and Audit

Every audit record includes the agent_id of the submitting agent. This creates a permanent, hash-chained record of every action every agent has ever submitted and every verdict it has received.

This means:

• You can reconstruct the complete governance history of any agent at any time.
• You can prove (via the hash chain) that the history has not been tampered with.
• You can export an agent's complete governance record for regulatory review.

GET /audit?agent_id=agt_abc123def456&format=pdf

Best Practices

1. One agent per purpose: Register separate agents for separate functions (deployment, monitoring, data access) rather than using a single agent for everything. This provides clearer audit trails and more granular policy control.

2. Start with Tier B override: When onboarding a new agent, set a Tier B override so all actions require human review. Remove the override after the agent has demonstrated reliable behavior over a meaningful number of actions.

3. Use descriptive names: Agent names and descriptions appear throughout the platform -- in audit records, escrow queues, dashboards, and compliance reports. Invest in clear naming.

4. Monitor blocked rates: An agent with a rising blocked rate is either misconfigured or misbehaving. Investigate before the blocked rate triggers automatic status changes.

5. Revoke compromised agents immediately: If an agent's credentials are exposed or the agent exhibits unexpected behavior, revoke its identity first and investigate second. Identity revocation is instant and irreversible -- this is a feature, not a limitation.