Workflow: Agent Registration

Every AI agent that operates under TheWARDN governance must be registered first. Registration gives the agent a unique identity, allows policies to be scoped to it, and enables full audit tracking.

Overview

Agent registration is the first step to governed AI. Without registration, an agent cannot send /govern requests and cannot operate within your tenant.

Registration Flow

POST /agents
     |
     v
Agent Created
- Unique agent_id assigned
- Status: active
- Audit record created
     |
     v
Assign Policies (optional)
- Scope CHAM policies to agent
- Set confidence floor
- Set tier override
     |
     v
Agent Starts Operating
- Sends POST /govern for each action
- All actions evaluated by Sentinel
- Full audit trail maintained

Step 1: Register the Agent

Send a POST /agents request with the agent's name and description:

curl -X POST https://api.thewardn.ai/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Assistant",
    "description": "Handles customer email responses and follow-ups"
  }'

Response:

{
  "agent_id": "agent_abc123",
  "name": "Email Assistant",
  "description": "Handles customer email responses and follow-ups",
  "status": "active",
  "created_at": "2026-04-10T14:00:00.000Z"
}

TIP

Store the agent_id -- your agent must include it in every /govern request.

Step 2: Configure the Agent (Optional)

After registration, you can configure agent-specific governance settings.

Set a Confidence Floor

A confidence floor requires the agent to meet a minimum confidence threshold for all actions:

curl -X PATCH https://api.thewardn.ai/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "confidence_floor": 0.70
  }'

Any action where any confidence dimension falls below 0.70 will be automatically HELD for human review.

Assign Policies

Scope specific CHAM policies to the agent:

curl -X POST https://api.thewardn.ai/agents/agent_abc123/policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "pol_no_pii_external"
  }'

Set a Tier Override

Override the default tier classification for the agent's actions:

curl -X PATCH https://api.thewardn.ai/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tier_override": "B"
  }'

Step 3: Agent Starts Operating

Once registered, the agent includes its agent_id in every governance request:

curl -X POST https://api.thewardn.ai/govern \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "action": "send_email",
    "parameters": { "to": "customer@example.com" },
    "confidence": { "overall": 0.87 }
  }'

Agent Status Lifecycle

Agents have four possible statuses. Status changes are immediate and affect all subsequent /govern requests.

                  +--------+
          +------>| active |<------+
          |       +--------+      |
          |         |    |        |
     reactivate     |    |    reactivate
          |      pause  block     |
          |         |    |        |
          v         v    v        |
     +---------+  +--------+     |
     | paused  |  | blocked|     |
     +---------+  +--------+     |
          |            |         |
     deregister   deregister     |
          |            |         |
          v            v         |
     +--------------+            |
     | deregistered |---re-register
     +--------------+

Status Behaviors

Status	Govern Behavior	Use Case
active	Normal governance evaluation	Agent is operating normally
paused	All actions automatically HELD	Temporary halt for investigation or maintenance
blocked	All actions automatically BLOCKED	Agent is misbehaving and must be stopped
deregistered	403 Forbidden -- cannot call /govern	Agent is retired or revoked

Changing Agent Status

# Pause an agent
curl -X PATCH https://api.thewardn.ai/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

# Block an agent
curl -X PATCH https://api.thewardn.ai/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "blocked"}'

# Reactivate an agent
curl -X PATCH https://api.thewardn.ai/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

# Deregister an agent
curl -X DELETE https://api.thewardn.ai/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

WARNING

Blocking an agent creates a violation record for every subsequent action attempt. Use paused if you want to hold actions for review rather than reject them outright.

Identity Revocation

Deregistering an agent revokes its identity entirely:

• The agent can no longer call /govern
• All pending escrow items for the agent are automatically KILLED
• The agent's history remains in the audit trail (never deleted)
• The agent_id is permanently retired and cannot be reused

curl -X DELETE https://api.thewardn.ai/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Re-Registration

A deregistered agent can be re-registered, but it receives a new agent_id. The old identity and audit trail are preserved separately.

curl -X POST https://api.thewardn.ai/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Assistant",
    "description": "Handles customer email responses and follow-ups (re-registered)",
    "previous_agent_id": "agent_abc123"
  }'

The previous_agent_id field links the new registration to the old one for audit continuity.

TIP

Re-registration does not restore old policies or configuration. You must reassign policies and set confidence floors again.

Listing Agents

# List all agents
curl https://api.thewardn.ai/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by status
curl https://api.thewardn.ai/agents?status=active \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

1. Use descriptive names -- Agent names appear throughout the console and audit logs. Make them meaningful.
2. Set confidence floors early -- A floor of 0.70 is a reasonable starting point for most agents.
3. Start with AUDIT_ONLY mode -- Register agents and let them operate in audit mode before switching to ENFORCED.
4. Pause before blocking -- If an agent is misbehaving, pause it first to hold actions for review. Block only if you are certain the agent should be stopped.
5. Document re-registrations -- Use the description field to note why an agent was deregistered and re-registered.

Next Steps

• Govern an Action -- What happens when a registered agent sends a governance request
• Policy Evaluation -- How to assign and evaluate policies for agents
• Incident Response -- What to do when an agent triggers violations