Agent Registration Guide

Overview

This guide walks through the complete process of registering an AI agent with the Ascend governance platform. Agent registration is required before any agent can submit actions for authorization review.

Key Capabilities

Self-Service Registration: Register agents via API, SDK, or dashboard
Draft-to-Active Workflow: Multi-stage registration with admin approval
Risk Profile Configuration: Define agent-specific risk thresholds
Capability Declaration: Specify allowed action types and resources
Version Tracking: Automatic versioning of all configuration changes

How It Works

Registration Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│                        AGENT REGISTRATION WORKFLOW                          │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Create Registration
┌───────────────────┐
│  Developer/Admin  │──── POST /api/registry/agents ────>
│  initiates        │
└───────────────────┘

Step 2: Agent Created (DRAFT)
                                    ┌───────────────────┐
                          <────────│   Agent Record    │
                                    │   status: draft   │
                                    │   version: 1.0.0  │
                                    └───────────────────┘

Step 3: Configure Policies
┌───────────────────┐
│  Add policies,    │──── POST /api/registry/agents/{id}/policies ────>
│  risk thresholds  │
└───────────────────┘

Step 4: Admin Approval
┌───────────────────┐
│  Admin reviews    │──── POST /api/registry/agents/{id}/activate ────>
│  and activates    │
└───────────────────┘

Step 5: Agent Active
                                    ┌───────────────────┐
                          <────────│   Agent Record    │
                                    │   status: active  │
                                    │   approved_by: X  │
                                    └───────────────────┘

Step 6: Submit Actions
┌───────────────────┐
│  Agent submits    │──── POST /api/v1/actions/submit ────>
│  actions via SDK  │
└───────────────────┘

Required Fields

Field	Type	Description	Constraints
`agent_id`	string	Unique identifier for the agent	3-64 characters, alphanumeric with dashes
`display_name`	string	Human-readable name	Max 255 characters
`organization_id`	integer	Organization scope (auto-populated from auth)	From API key or session

Optional Fields

Field	Type	Default	Description
`description`	string	null	Detailed agent description
`agent_type`	string	"supervised"	One of: autonomous, supervised, advisory, mcp_server, custom
`default_risk_score`	integer	50	Base risk score (0-100)
`max_risk_threshold`	integer	80	Maximum allowed risk score
`auto_approve_below`	integer	30	Auto-approve actions below this score
`requires_mfa_above`	integer	70	Require MFA above this score
`allowed_action_types`	array	[]	Permitted action types
`allowed_resources`	array	[]	Permitted resource targets
`blocked_resources`	array	[]	Explicitly denied resources
`is_mcp_server`	boolean	false	Whether this is an MCP server
`mcp_server_url`	string	null	MCP server endpoint URL
`mcp_capabilities`	object		MCP tools, prompts, resources
`alert_on_high_risk`	boolean	true	Send alerts for high-risk actions
`alert_recipients`	array	[]	Email addresses for alerts
`webhook_url`	string	null	Webhook for notifications
`tags`	array	[]	Organizational tags
`metadata`	object		Custom key-value pairs

Configuration

Environment Variables

The SDK and API clients use these environment variables:

# Required
ASCEND_API_KEY=your-api-key-here

# Optional
ASCEND_API_BASE_URL=https://api.ascend.security
ASCEND_TIMEOUT_SECONDS=30
ASCEND_RETRY_COUNT=3

SDK Configuration

from ascend import AscendClient, AscendConfig

config = AscendConfig(
    api_key="your-api-key",
    base_url="https://api.ascend.security",
    timeout=30,
    retry_count=3,
    verify_ssl=True
)

client = AscendClient(config=config)

Usage Examples

Basic Registration (Python SDK)

from ascend import AscendClient

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

# Register a basic supervised agent
result = client.agents.register(
    agent_id="my-first-agent",
    display_name="My First Agent",
    description="A simple test agent for learning the platform"
)

print(f"Agent ID: {result.agent_id}")
print(f"Status: {result.status}")  # "draft"
print(f"Version: {result.version}")  # "1.0.0"
print(f"Next steps: {result.next_steps}")

Full Registration with Risk Configuration (Python SDK)

from ascend import AscendClient, AgentType

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

# Register a production agent with full configuration
agent = client.agents.register(
    # Identity
    agent_id="finance-invoice-processor-v2",
    display_name="Finance Invoice Processor",
    description="Processes vendor invoices and routes for approval",
    agent_type=AgentType.SUPERVISED,

    # Risk thresholds
    default_risk_score=45,
    max_risk_threshold=75,
    auto_approve_below=25,
    requires_mfa_above=60,

    # Capabilities - what this agent can do
    allowed_action_types=[
        "invoice_read",
        "invoice_create",
        "invoice_update",
        "approval_request"
    ],

    # Resources - where this agent can operate
    allowed_resources=[
        "invoice_db",
        "vendor_api",
        "approval_workflow"
    ],
    blocked_resources=[
        "payment_gateway",      # No direct payments
        "bank_accounts",        # No bank access
        "employee_pii"          # No employee data
    ],

    # Alerting
    alert_on_high_risk=True,
    alert_recipients=[
        "finance-security@company.com",
        "finance-ops@company.com"
    ],
    webhook_url="https://hooks.company.com/ascend-alerts",

    # Metadata for organization
    tags=["finance", "invoicing", "tier-2"],
    metadata={
        "cost_center": "CC-1234",
        "owner": "finance-automation",
        "sla_tier": "business-critical"
    }
)

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

Registration with cURL

# Step 1: Create the agent (DRAFT status)
curl -X POST https://api.ascend.security/api/registry/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sales-lead-qualifier",
    "display_name": "Sales Lead Qualifier",
    "description": "Qualifies inbound sales leads based on scoring criteria",
    "agent_type": "supervised",
    "default_risk_score": 35,
    "max_risk_threshold": 70,
    "auto_approve_below": 30,
    "allowed_action_types": ["lead_read", "lead_update", "lead_score"],
    "allowed_resources": ["salesforce_leads", "hubspot_contacts"],
    "blocked_resources": ["payment_info", "contracts"],
    "alert_on_high_risk": true,
    "alert_recipients": ["sales-ops@company.com"],
    "tags": ["sales", "lead-gen"]
  }'

# Response:
# {
#   "success": true,
#   "created": true,
#   "agent": {
#     "id": 42,
#     "agent_id": "sales-lead-qualifier",
#     "display_name": "Sales Lead Qualifier",
#     "status": "draft",
#     "version": "1.0.0",
#     "agent_type": "supervised"
#   },
#   "next_steps": [
#     "Configure policies using POST /api/registry/agents/{id}/policies",
#     "Activate agent using POST /api/registry/agents/{id}/activate",
#     "Submit actions using POST /api/v1/actions/submit"
#   ]
# }

Add Policies to Agent

# Add a policy that requires approval for high-value leads
curl -X POST https://api.ascend.security/api/registry/agents/sales-lead-qualifier/policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_name": "high-value-lead-approval",
    "policy_description": "Require approval for leads over $100k estimated value",
    "is_active": true,
    "priority": 100,
    "conditions": {
      "action_type": "lead_update",
      "metadata.estimated_value_gt": 100000
    },
    "policy_action": "require_approval",
    "action_params": {
      "escalate_to": "sales-managers",
      "timeout_seconds": 3600
    }
  }'

Activate Agent (Admin Required)

# Admin activates the agent for production use
curl -X POST https://api.ascend.security/api/registry/agents/sales-lead-qualifier/activate \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json"

# Response:
# {
#   "success": true,
#   "message": "Agent activated: sales-lead-qualifier",
#   "agent": {
#     "id": 42,
#     "agent_id": "sales-lead-qualifier",
#     "status": "active",
#     "approved_at": "2026-01-20T14:30:00Z",
#     "approved_by": "admin@company.com"
#   }
# }

Register an Autonomous Agent

from ascend import AscendClient, AgentType

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

# Autonomous agents have stricter defaults
autonomous_agent = client.agents.register(
    agent_id="autonomous-data-classifier",
    display_name="Autonomous Data Classifier",
    description="Automatically classifies incoming data based on content analysis",
    agent_type=AgentType.AUTONOMOUS,

    # Standard thresholds (will be overridden for autonomous)
    default_risk_score=30,
    max_risk_threshold=80,
    auto_approve_below=25,

    # Autonomous-specific overrides (stricter)
    autonomous_max_risk_threshold=60,    # Lower than standard 80
    autonomous_auto_approve_below=15,    # Higher bar than standard 25
    autonomous_require_dual_approval=True,  # Two approvers for high risk

    # Escalation configuration for blocked actions
    autonomous_escalation_webhook_url="https://hooks.company.com/escalations",
    autonomous_escalation_email="data-team@company.com",
    autonomous_allow_queued_approval=True,  # Queue for human review

    allowed_action_types=["classify_read", "classify_write", "classify_update"],
    allowed_resources=["classification_db", "ml_models"],
    blocked_resources=["source_data_raw", "pii_fields"],

    tags=["autonomous", "ml", "classification"]
)

Register an MCP Server

from ascend import AscendClient

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

# Register an MCP server for governance
mcp_server = client.mcp_servers.register(
    server_name="file-tools-server",
    display_name="File System Tools Server",
    description="MCP server providing file system operations",
    server_url="http://localhost:3000/mcp",
    transport_type="stdio",

    # Governance settings
    governance_enabled=True,
    auto_approve_tools=["read_file", "list_directory"],  # Low-risk tools
    blocked_tools=["delete_file", "execute_command"],     # High-risk blocked

    # Risk overrides for specific tools
    tool_risk_overrides={
        "write_file": 65,      # Higher risk for writes
        "create_directory": 45,
        "move_file": 55
    }
)

Best Practices

Naming Standards

Recommended Format: {team}-{function}-{version}

Examples:

finance-invoice-processor-v2
support-ticket-router-v1
security-threat-analyzer-v3

Avoid:

Generic names: my-agent, test-agent, agent-1
Names without versioning: invoice-processor
Names that could conflict: data-agent

Risk Configuration Guidelines

Agent Type	Recommended max_risk_threshold	Recommended auto_approve_below
Advisory	90	50
Supervised	80	30
Autonomous	60	15
MCP Server	75	25

Capability Declaration

Be Specific: Declare only the action types and resources the agent actually needs.

# GOOD - Specific capabilities
allowed_action_types=["invoice_read", "invoice_create", "invoice_update"]
allowed_resources=["invoice_db", "vendor_api"]

# BAD - Overly broad
allowed_action_types=["*"]  # Never use wildcards
allowed_resources=["*"]     # Never allow all resources

Blocked Resources

Always explicitly block sensitive resources:

blocked_resources=[
    "credentials_vault",    # Credential storage
    "payment_gateway",      # Payment processing
    "employee_pii",         # Personal information
    "production_db_admin",  # Admin access
    "audit_logs"            # Audit trail (read-only)
]

Pre-Activation Checklist

Before activating an agent for production:

Risk Review: Verify risk thresholds are appropriate for the agent's function
Capability Audit: Confirm allowed_action_types and resources are minimal and necessary
Blocking Review: Ensure sensitive resources are explicitly blocked
Policy Testing: Use dry-run to test policy behavior with realistic scenarios
Alert Configuration: Verify alert recipients are correct and monitored
Documentation: Ensure agent description and metadata are complete
Approval Chain: Confirm the right admin will approve activation

Post-Activation Monitoring

After activation:

Monitor First 24 Hours: Watch for unexpected action patterns
Review Alerts: Address any high-risk alerts immediately
Check Health: Enable heartbeat monitoring for critical agents
Set Baselines: After behavior stabilizes, set anomaly detection baselines
Regular Review: Schedule periodic reviews of agent configuration

Agent Registry Overview - Complete registry documentation
Agent Capabilities - Deep dive into capability management
Policy Management - Creating agent policies
Risk Scoring - Understanding risk calculations
SDK Quick Start - Getting started with the Python SDK

Compliance

Agent registration supports compliance with:

SOC 2 CC6.1: Logical access controls
SOC 2 CC8.1: Change management
PCI-DSS 8.3: User identification and authentication
NIST 800-53 AC-2: Account management
HIPAA 164.312(a): Access control

Overview​

Key Capabilities​

How It Works​

Registration Workflow​

Required Fields​

Optional Fields​

Configuration​

Environment Variables​

SDK Configuration​

Usage Examples​

Basic Registration (Python SDK)​

Full Registration with Risk Configuration (Python SDK)​

Registration with cURL​

Add Policies to Agent​

Activate Agent (Admin Required)​

Register an Autonomous Agent​

Register an MCP Server​

Best Practices​

Naming Standards​

Risk Configuration Guidelines​

Capability Declaration​

Blocked Resources​

Pre-Activation Checklist​

Post-Activation Monitoring​

Related​

Compliance​