Agent Registry Overview

Overview

The Agent Registry is the central management system for all AI agents that interact with the Ascend governance platform. It provides enterprise-grade registration, configuration, and lifecycle management for autonomous, supervised, and advisory AI agents operating within your organization.

Every AI agent must be registered before it can submit actions for authorization. The registry enforces multi-tenant isolation, versioning, and compliance requirements across your agent fleet.

Key Capabilities

• Agent Registration: Register AI agents with unique identifiers, risk configurations, and capability definitions
• Lifecycle Management: Manage agent states from draft through active, suspended, and retired
• Version Control: Track configuration changes with full version history and rollback capability
• Risk Configuration: Define per-agent risk thresholds, auto-approval limits, and MFA requirements
• MCP Integration: Native support for Model Context Protocol (MCP) servers and tool governance
• Audit Trail: Immutable logging of all registration and configuration changes
• Multi-Tenant Isolation: Complete separation of agent configurations between organizations

How It Works

Agent Registration Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Register Agent │────>│  Configure Risk │────>│ Admin Approval  │
│    (DRAFT)      │     │   Thresholds    │     │    (ACTIVE)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                                               │
         │                                               v
         │                                    ┌─────────────────┐
         │                                    │  Submit Actions │
         │                                    │   via SDK/API   │
         │                                    └─────────────────┘
         │
         v
┌─────────────────────────────────────────────────────────────────┐
│                    Agent Lifecycle States                        │
│  DRAFT -> PENDING_APPROVAL -> ACTIVE <-> SUSPENDED -> RETIRED   │
└─────────────────────────────────────────────────────────────────┘

Agent Types

Type	Description	Governance Level
autonomous	Fully autonomous decision-making agents	Highest - stricter thresholds, dual approval
supervised	Agents requiring human approval for actions	Standard - configurable thresholds
advisory	Recommendation-only agents with no action execution	Lowest - minimal oversight
mcp_server	Model Context Protocol servers providing tools	Tool-level governance
custom	Custom agent types with organization-defined governance	Configurable

Agent Lifecycle States

State	Description	Allowed Transitions
draft	Agent is being configured, not yet operational	pending_approval, retired
pending_approval	Awaiting administrator approval	active, draft
active	Fully operational and accepting action submissions	suspended, deprecated
suspended	Temporarily disabled (security or policy violation)	active, retired
deprecated	Scheduled for retirement, still operational	retired, active
retired	Permanently decommissioned	None

Configuration

Risk Thresholds

Every registered agent has configurable risk thresholds that determine how actions are processed:

Configuration	Default	Description
default_risk_score	50	Base risk score applied to actions from this agent
max_risk_threshold	80	Actions above this score are blocked
auto_approve_below	30	Actions below this score are auto-approved
requires_mfa_above	70	Actions above this score require MFA verification

Autonomous Agent Overrides (stricter defaults):

Configuration	Default	Description
autonomous_max_risk_threshold	60	Lower threshold for autonomous agents
autonomous_auto_approve_below	40	Higher bar for auto-approval
autonomous_require_dual_approval	false	Require two approvers for high-risk actions

Rate Limiting (SEC-068)

Control agent action throughput to prevent runaway operations:

Configuration	Default	Description
max_actions_per_minute	null	Maximum actions per minute (null = unlimited)
max_actions_per_hour	null	Maximum actions per hour
max_actions_per_day	null	Maximum actions per day

Budget Controls (SEC-068)

Monitor and limit agent operational costs:

Configuration	Default	Description
max_daily_budget_usd	null	Daily budget limit in USD (null = unlimited)
budget_alert_threshold_percent	80	Alert when this percentage is consumed
auto_suspend_on_budget_exceeded	true	Automatically suspend when budget exceeded

Time Window Restrictions

Restrict when agents can operate:

Configuration	Default	Description
time_window_enabled	false	Enable time-based restrictions
time_window_start	"09:00"	Start time (HH:MM format)
time_window_end	"17:00"	End time (HH:MM format)
time_window_timezone	"UTC"	Timezone for time window
time_window_days	[1,2,3,4,5]	Allowed days (1=Monday, 7=Sunday)

Usage Examples

Register a New Agent (Python SDK)

from ascend import AscendClient

client = AscendClient(api_key="your-api-key")

# Register a supervised agent
agent = client.agents.register(
    agent_id="customer-support-bot-v1",
    display_name="Customer Support Bot",
    description="Handles customer inquiries and ticket routing",
    agent_type="supervised",

    # Risk configuration
    default_risk_score=40,
    max_risk_threshold=75,
    auto_approve_below=35,
    requires_mfa_above=65,

    # Capabilities
    allowed_action_types=["query", "ticket_create", "ticket_update"],
    allowed_resources=["zendesk", "salesforce", "knowledge_base"],
    blocked_resources=["financial_systems", "pii_database"],

    # Notifications
    alert_on_high_risk=True,
    alert_recipients=["security@company.com"],

    # Metadata
    tags=["customer-facing", "support", "tier-1"]
)

print(f"Agent registered: {agent.agent_id} (status: {agent.status})")

Register an Agent (cURL)

curl -X POST https://api.ascend.security/api/registry/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "data-analysis-agent",
    "display_name": "Data Analysis Agent",
    "description": "Performs analytics queries on business data",
    "agent_type": "supervised",
    "default_risk_score": 50,
    "max_risk_threshold": 80,
    "auto_approve_below": 30,
    "allowed_action_types": ["query", "read", "export"],
    "allowed_resources": ["analytics_db", "reporting_api"],
    "blocked_resources": ["production_db", "pii_tables"],
    "tags": ["analytics", "business-intelligence"]
  }'

Configure Rate Limits (cURL)

curl -X PUT https://api.ascend.security/api/registry/agents/my-agent/rate-limits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_actions_per_minute": 100,
    "max_actions_per_hour": 2000,
    "max_actions_per_day": 10000
  }'

Emergency Agent Suspension (cURL)

curl -X POST https://api.ascend.security/api/registry/agents/my-agent/emergency-suspend \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Security incident: Unusual data access patterns detected"
  }'

Best Practices

Agent Naming Conventions

• Use descriptive, unique identifiers: department-function-version (e.g., finance-invoice-processor-v2)
• Include version numbers for agents that may be upgraded
• Avoid generic names that could conflict across teams

Risk Configuration Guidelines

1. Start Conservative: Begin with lower auto-approve thresholds and increase based on observed behavior
2. Environment Awareness: Configure stricter thresholds for agents accessing production systems
3. Regular Review: Periodically review and adjust thresholds based on action history
4. Autonomous Agents: Always use stricter thresholds for autonomous agents (recommended: max 60, auto-approve below 20)

Operational Best Practices

1. Always Activate via Admin: Never bypass the admin activation step for production agents
2. Configure Alerting: Set up alert recipients before activating high-risk agents
3. Version Your Changes: Use version notes to document configuration changes
4. Monitor Health: Enable heartbeat monitoring for critical agents
5. Set Baselines: After agent behavior stabilizes, set anomaly detection baselines

Security Recommendations

1. Principle of Least Privilege: Only grant the minimum required action types and resources
2. Block Sensitive Resources: Explicitly block access to PII, financial systems, and credentials
3. Enable MFA: Require MFA for actions above moderate risk thresholds
4. Rate Limiting: Configure rate limits to prevent runaway operations
5. Time Windows: Restrict operation hours for non-critical agents

Related

• Agent Registration Guide - Step-by-step registration walkthrough
• Agent Capabilities - Defining and managing agent capabilities
• MCP Server Registration - Registering MCP servers
• Policy Management - Creating policies for agent governance
• Risk Scoring - Understanding the risk scoring system

Compliance

The Agent Registry supports compliance with:

• SOC 2 CC6.1/CC6.2: Logical access controls and user identification
• SOC 2 CC7.1: Security incident management
• PCI-DSS 7.1/8.3: Access control and authentication
• NIST 800-53 AC-2/AC-3: Account management and access enforcement
• HIPAA 164.312: Access controls and audit controls