Agent Registry

Field	Value
Document ID	ASCEND-AGENT-005
Version	1.0.0
Last Updated	December 19, 2025
Author	Ascend Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 12 minutes | Skill Level: Intermediate

Overview

The Agent Registry is the central repository for all AI agents in your organization. Every agent must be registered before it can execute governed actions.

Registration

Basic Registration

from ascend import AscendClient, AgentAction

client = AscendClient(
    api_key="owkai_...",
    agent_id="my-agent-001",
    agent_name="Data Processing Agent"
)

# Registration happens automatically on first action
# Or explicitly:
registration = client.register(
    agent_type="supervised",
    capabilities=["database.query", "api.read"],
    metadata={
        "owner": "data-team@company.com",
        "environment": "production"
    }
)

REST API Registration

curl -X POST "https://pilot.owkai.app/api/agents/registry" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "financial-agent-001",
    "display_name": "Financial Advisor Bot",
    "description": "Processes financial transactions and queries",
    "agent_type": "supervised",

    "allowed_action_types": [
      "database.query",
      "api.read",
      "transaction.process"
    ],
    "allowed_resources": ["postgresql", "banking_api"],
    "blocked_resources": ["production_secrets"],

    "default_risk_score": 50,
    "auto_approve_below": 30,
    "max_risk_threshold": 80,
    "requires_mfa_above": 70,

    "alert_on_high_risk": true,
    "alert_recipients": ["security@company.com"],
    "webhook_url": "https://hooks.company.com/ascend",

    "tags": ["finance", "customer-facing"],
    "metadata": {
      "owner": "finance-team@company.com",
      "cost_center": "CC-1234"
    }
  }'

Configuration Options

Agent Identification

Field	Type	Required	Description
agent_id	string	Yes	Unique identifier (3-64 chars, alphanumeric with dashes)
display_name	string	Yes	Human-readable name
description	string	No	Agent purpose description
agent_type	enum	No	autonomous, supervised, advisory, mcp_server, custom
tags	array	No	Categorization tags
metadata	object	No	Custom key-value pairs

Agent ID Format

# Source: services/agent_registry_service.py:655
# Validation regex
import re

# Valid: alphanumeric, dashes, underscores, 3-64 chars
pattern = r'^[a-zA-Z0-9][a-zA-Z0-9\-_]{2,63}$'

# Valid examples
"my-agent-001"       # OK
"data_processor"     # OK
"FinanceBot-v2"      # OK

# Invalid examples
"a"                  # Too short
"-invalid"           # Starts with dash
"agent with spaces"  # Contains spaces

Risk Configuration

Field	Type	Default	Description
default_risk_score	int	50	Default risk for unclassified actions (0-100)
auto_approve_below	int	30	Auto-approve actions with risk below this
max_risk_threshold	int	80	Escalate actions above this threshold
requires_mfa_above	int	70	Require MFA for risk above this

Autonomous Agent Thresholds

# Source: models_agent_registry.py:183
# Autonomous agents use stricter thresholds by default

# Supervised agent (default)
auto_approve_below = 30
max_risk_threshold = 80

# Autonomous agent (stricter)
autonomous_auto_approve_below = 40  # Higher bar for auto-approve
autonomous_max_risk_threshold = 60  # Lower ceiling before escalation

Capabilities Configuration

{
  "allowed_action_types": [
    "database.query",
    "database.read",
    "api.read",
    "api.create"
  ],
  "allowed_resources": [
    "postgresql",
    "redis",
    "customer_api"
  ],
  "blocked_resources": [
    "production_secrets",
    "admin_api",
    "financial_db"
  ]
}

Autonomous Agent Governance

Rate Limiting

{
  "max_actions_per_minute": 100,
  "max_actions_per_hour": 1000,
  "max_actions_per_day": 10000
}

# Source: services/agent_registry_service.py:55
# Rate limit check on every action
def check_rate_limit(db, agent):
    """Check if agent is within rate limits."""
    remaining = {
        "minute": agent.max_actions_per_minute - agent.current_minute_count,
        "hour": agent.max_actions_per_hour - agent.current_hour_count,
        "day": agent.max_actions_per_day - agent.current_day_count
    }

    if agent.current_minute_count >= agent.max_actions_per_minute:
        return {"allowed": False, "reason": "Rate limit exceeded"}

    return {"allowed": True, "remaining": remaining}

Budget Controls

{
  "max_daily_budget_usd": 100.00,
  "budget_alert_threshold_percent": 80
}

Time Window Restrictions

{
  "time_window_enabled": true,
  "time_window_start": "09:00",
  "time_window_end": "17:00",
  "time_window_timezone": "America/New_York",
  "time_window_days": [1, 2, 3, 4, 5]
}

Day values: Monday=1, Sunday=7

Data Classification Restrictions

{
  "allowed_data_classifications": ["public", "internal"],
  "blocked_data_classifications": ["pii", "financial", "secret"]
}

Auto-Suspension Triggers

{
  "auto_suspend_enabled": true,
  "auto_suspend_on_error_rate": 0.10,
  "auto_suspend_on_offline_minutes": 30,
  "auto_suspend_on_budget_exceeded": true,
  "auto_suspend_on_rate_exceeded": false
}

Version Control

Automatic Versioning

Configuration changes that affect security automatically create new versions:

# Source: services/agent_registry_service.py:855
# Fields that trigger version bump
version_trigger_fields = {
    "allowed_action_types",
    "allowed_resources",
    "blocked_resources",
    "auto_approve_below",
    "max_risk_threshold",
    "requires_mfa_above",
    "autonomous_auto_approve_below",
    "autonomous_max_risk_threshold",
    "mcp_capabilities",
    "agent_type"
}

List Versions

curl "https://pilot.owkai.app/api/agents/registry/my-agent-001/versions" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "agent_id": "my-agent-001",
  "versions": [
    {
      "version": "1.2.0",
      "is_active": true,
      "version_notes": "Updated: allowed_action_types",
      "created_at": "2025-12-15T10:30:00Z",
      "created_by": "admin@company.com"
    },
    {
      "version": "1.1.0",
      "is_active": false,
      "version_notes": "Added transaction capabilities",
      "created_at": "2025-12-10T14:00:00Z",
      "created_by": "admin@company.com"
    },
    {
      "version": "1.0.0",
      "is_active": false,
      "version_notes": "Initial registration",
      "created_at": "2025-12-01T09:00:00Z",
      "created_by": "admin@company.com"
    }
  ]
}

Rollback to Version

curl -X POST "https://pilot.owkai.app/api/agents/registry/my-agent-001/rollback" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "target_version": "1.1.0",
    "reason": "New permissions caused issues"
  }'

Agent Policies

Add Policy

curl -X POST "https://pilot.owkai.app/api/agents/registry/my-agent-001/policies" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "policy_name": "High-Value Transaction Review",
    "policy_description": "Require approval for transactions over $10,000",
    "is_active": true,
    "priority": 10,
    "conditions": {
      "action_type": "transaction.process",
      "amount_above": 10000
    },
    "policy_action": "require_approval",
    "action_params": {
      "approvers": ["finance-approvers"],
      "timeout_seconds": 3600
    }
  }'

Policy Actions

Action	Description
allow	Auto-approve the action
require_approval	Require human approval
block	Deny the action
escalate	Escalate to specific team

Condition Operators

# Source: services/agent_registry_service.py:1851
# Available condition operators

conditions = {
    "action_type": "transaction.process",  # Exact match
    "risk_above": 60,                      # Greater than
    "risk_below": 30,                      # Less than
    "resource_in": ["db1", "db2"],         # In list
    "resource_not_in": ["secrets"]         # Not in list
}

MCP Server Registration

Register Model Context Protocol servers:

curl -X POST "https://pilot.owkai.app/api/agents/mcp/servers" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "database-server",
    "display_name": "Production Database Server",
    "description": "MCP server for database operations",
    "server_url": "http://localhost:3000",
    "transport_type": "stdio",
    "governance_enabled": true,
    "auto_approve_tools": ["list_tables", "describe_table"],
    "blocked_tools": ["drop_table", "truncate"],
    "tool_risk_overrides": {
      "execute_query": 70,
      "create_table": 60
    }
  }'

Update Agent

curl -X PUT "https://pilot.owkai.app/api/agents/registry/my-agent-001" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Updated Agent Name",
    "allowed_action_types": ["database.query", "database.read", "api.read"],
    "max_risk_threshold": 75,
    "version_notes": "Added read capability for APIs"
  }'

Delete Agent

curl -X DELETE "https://pilot.owkai.app/api/agents/registry/my-agent-001" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Agent decommissioned - replaced by v2"
  }'

List Agents

# List all agents
curl "https://pilot.owkai.app/api/agents/registry" \
  -H "Authorization: Bearer owkai_..."

# Filter by status
curl "https://pilot.owkai.app/api/agents/registry?status=active" \
  -H "Authorization: Bearer owkai_..."

# Filter by type
curl "https://pilot.owkai.app/api/agents/registry?type=autonomous" \
  -H "Authorization: Bearer owkai_..."

# Pagination
curl "https://pilot.owkai.app/api/agents/registry?limit=20&offset=40" \
  -H "Authorization: Bearer owkai_..."

Activity Logs

All agent changes are logged for compliance:

curl "https://pilot.owkai.app/api/agents/registry/my-agent-001/activity" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "agent_id": "my-agent-001",
  "activities": [
    {
      "activity_type": "updated",
      "activity_description": "Agent 'my-agent-001' updated: allowed_action_types",
      "performed_by": "admin@company.com",
      "performed_via": "api",
      "timestamp": "2025-12-15T10:30:00Z",
      "previous_state": {
        "allowed_action_types": ["database.query"]
      },
      "new_state": {
        "allowed_action_types": ["database.query", "api.read"]
      }
    },
    {
      "activity_type": "activated",
      "activity_description": "Agent 'my-agent-001' activated",
      "performed_by": "admin@company.com",
      "performed_via": "dashboard",
      "timestamp": "2025-12-01T09:30:00Z"
    }
  ]
}

Best Practices

1. Use Descriptive IDs

# Good - includes team, purpose, environment
"finance-transaction-processor-prod"
"data-etl-pipeline-staging"
"customer-support-bot-v2"

# Bad - generic, non-descriptive
"agent-1"
"bot"
"processor"

2. Set Appropriate Thresholds

# High-security agent (financial)
{
    "auto_approve_below": 20,
    "max_risk_threshold": 60,
    "requires_mfa_above": 50
}

# Low-risk agent (read-only)
{
    "auto_approve_below": 50,
    "max_risk_threshold": 90,
    "requires_mfa_above": 80
}

3. Use Policies for Fine-Grained Control

# Instead of blocking all high-risk actions,
# create policies for specific scenarios
policies = [
    {
        "policy_name": "After-Hours Review",
        "conditions": {"hour_after": 18, "hour_before": 6},
        "policy_action": "require_approval"
    },
    {
        "policy_name": "PII Access Review",
        "conditions": {"data_classification": "pii"},
        "policy_action": "escalate",
        "action_params": {"team": "privacy-team"}
    }
]

4. Enable Version Control

Always provide version_notes when updating:

curl -X PUT "https://pilot.owkai.app/api/agents/registry/my-agent-001" \
  -d '{
    "allowed_action_types": ["database.query", "api.read"],
    "version_notes": "JIRA-1234: Added API read capability for customer dashboard"
  }'

Next Steps

• Lifecycle Management — State transitions
• Trust Levels — Agent type configuration
• Health Monitoring — Metrics and alerts
• Kill-Switch — Emergency procedures

---

Document Version: 1.0.0 | Last Updated: December 2025