Register Your First Agent

This guide walks you through registering your first AI agent with ASCEND. Agent registration establishes identity, declares capabilities, and enables governance.

Prerequisites

Before registering an agent, ensure you have:

Installed the ASCEND SDK (Quick Start)
Your API key from the ASCEND Console
Determined your agent's unique identifier

Understanding Agent Registration

Registration tells ASCEND about your agent:

Information	Purpose	Example
Agent ID	Unique identifier for tracking	`customer-service-bot-001`
Agent Name	Human-readable display name	`Customer Service Bot`
Agent Type	Classification for policy matching	`supervised`, `autonomous`
Capabilities	What the agent can do	`data_access`, `transaction`
Allowed Resources	What resources the agent can access	`customer_db`, `/var/log`

Step 1: Choose Your Agent ID

Your agent ID should be:

Unique within your organization
Descriptive of the agent's purpose
Consistent across deployments

Good examples:

customer-service-bot-prod
data-pipeline-analytics-v2
mcp-database-connector
order-processing-agent

Avoid:

agent1              # Not descriptive
my-agent            # Too generic
test                # Ambiguous

Step 2: Initialize the Client

Python

from ascend import AscendClient, FailMode
import os

# Initialize with environment variables (recommended for production)
client = AscendClient(
    api_key=os.getenv("ASCEND_API_KEY"),
    agent_id="customer-service-bot-001",
    agent_name="Customer Service Bot",
    environment="production",  # production, staging, or development
    fail_mode=FailMode.CLOSED
)

Node.js

import { AscendClient, FailMode } from '@ascend-ai/sdk';

// Initialize with environment variables (recommended for production)
const client = new AscendClient({
    apiKey: process.env.ASCEND_API_KEY,
    agentId: 'customer-service-bot-001',
    agentName: 'Customer Service Bot',
    environment: 'production',  // production, staging, or development
    failMode: FailMode.CLOSED
});

Step 3: Define Capabilities

Capabilities describe what your agent can do. Choose from standard capability types:

Standard Capabilities

Capability	Description	Example Actions
`data_access`	Read data from sources	SELECT queries, API reads
`data_modification`	Create, update, delete data	INSERT, UPDATE, DELETE
`data_export`	Export data outside the system	CSV export, API sharing
`transaction`	Financial transactions	Payments, refunds, transfers
`file_operations`	File system operations	Read, write, delete files
`system_operation`	System configuration	Config changes, restarts
`communication`	External communications	Email, SMS, notifications
`api_call`	External API invocations	Third-party integrations

Example Capability Definitions

Customer Service Bot:

capabilities = [
    "data_access",        # Look up customer information
    "data_modification",  # Update customer records
    "transaction",        # Process refunds
    "communication"       # Send confirmation emails
]

Data Pipeline Agent:

capabilities = [
    "data_access",        # Read from data sources
    "data_modification",  # Write to data warehouse
    "data_export"         # Generate reports
]

MCP Database Server:

capabilities = [
    "data_access",        # SELECT queries
    "data_modification"   # INSERT/UPDATE/DELETE
]

Step 4: Specify Allowed Resources

Define which resources your agent can access:

Resource Types

Type	Format	Examples
Databases	`database_name`	`customer_db`, `analytics_warehouse`
File Paths	`/path/to/resource`	`/var/log/app`, `/data/exports`
APIs	`api_name` or URL	`stripe_api`, `salesforce`
Services	`service_name`	`payment_gateway`, `email_service`

Example Resource Definitions

allowed_resources = [
    "customer_db",           # Primary customer database
    "orders_db",             # Orders database
    "/var/log/application",  # Application logs
    "stripe_api",            # Payment processing
    "sendgrid"               # Email service
]

Step 5: Register the Agent

Python

from ascend import AscendClient, FailMode
import os

# Initialize client
client = AscendClient(
    api_key=os.getenv("ASCEND_API_KEY"),
    agent_id="customer-service-bot-001",
    agent_name="Customer Service Bot",
    environment="production",
    fail_mode=FailMode.CLOSED
)

# Register the agent
try:
    registration = client.register(
        agent_type="supervised",
        capabilities=[
            "data_access",
            "data_modification",
            "transaction",
            "communication"
        ],
        allowed_resources=[
            "customer_db",
            "orders_db",
            "stripe_api",
            "sendgrid"
        ],
        metadata={
            "team": "customer-support",
            "version": "2.1.0",
            "owner": "support-team@company.com"
        }
    )

    print(f"Agent registered successfully!")
    print(f"  Agent ID: {registration.get('agent_id')}")
    print(f"  Trust Level: {registration.get('trust_level', 'standard')}")
    print(f"  Status: {registration.get('status')}")

except Exception as e:
    print(f"Registration error: {e}")

Node.js

import { AscendClient, FailMode } from '@ascend-ai/sdk';

// Initialize client
const client = new AscendClient({
    apiKey: process.env.ASCEND_API_KEY,
    agentId: 'customer-service-bot-001',
    agentName: 'Customer Service Bot',
    environment: 'production',
    failMode: FailMode.CLOSED
});

// Register the agent
try {
    const registration = await client.register({
        agentType: 'supervised',
        capabilities: [
            'data_access',
            'data_modification',
            'transaction',
            'communication'
        ],
        allowedResources: [
            'customer_db',
            'orders_db',
            'stripe_api',
            'sendgrid'
        ],
        metadata: {
            team: 'customer-support',
            version: '2.1.0',
            owner: 'support-team@company.com'
        }
    });

    console.log('Agent registered successfully!');
    console.log(`  Agent ID: ${registration.agentId}`);
    console.log(`  Trust Level: ${registration.trustLevel || 'standard'}`);
    console.log(`  Status: ${registration.status}`);

} catch (error) {
    console.error('Registration error:', error.message);
}

Step 6: Verify Registration

After registration, verify your agent appears in the ASCEND Console:

Log in to pilot.owkai.app
Navigate to Agents in the sidebar
Find your agent by ID or name
Verify capabilities and resources are correct

You can also verify programmatically:

# Test connection (includes registration status)
status = client.test_connection()

print(f"Connection Status: {status['status']}")
print(f"Agent ID: {status.get('agent_id')}")
print(f"Environment: {status.get('environment')}")

Agent Types Explained

Choose the appropriate agent type based on your use case:

Supervised Agent

Use for: Agents that operate under human oversight

client.register(
    agent_type="supervised",
    # ...
)

Characteristics:

Human can intervene at any time
Actions may be pre-approved or post-reviewed
Lower initial risk assessment
Suitable for customer-facing applications

Autonomous Agent

Use for: Fully automated agents with minimal human intervention

client.register(
    agent_type="autonomous",
    # ...
)

Characteristics:

Operates independently
Higher scrutiny on all actions
May require more approval workflows
Suitable for backend automation

MCP Server

Use for: Model Context Protocol servers providing tools

client.register(
    agent_type="mcp_server",
    # ...
)

Characteristics:

Provides tools to other systems
Actions originate from external requests
Special MCP governance features
Suitable for tool servers and connectors

Complete Registration Example

Here is a complete example showing best practices:

"""
ASCEND Agent Registration Example
---------------------------------
Complete example with error handling and verification.
"""

import os
import logging
from ascend import AscendClient, FailMode

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def register_agent():
    """Register a customer service agent with ASCEND."""

    # Validate environment
    api_key = os.getenv("ASCEND_API_KEY")
    if not api_key:
        raise ValueError("ASCEND_API_KEY environment variable not set")

    # Initialize client
    client = AscendClient(
        api_key=api_key,
        agent_id="customer-service-bot-001",
        agent_name="Customer Service Bot",
        environment=os.getenv("ASCEND_ENVIRONMENT", "production"),
        fail_mode=FailMode.CLOSED,
        timeout=10,  # 10 second timeout
        debug=os.getenv("ASCEND_DEBUG", "false").lower() == "true"
    )

    # Test connection first
    logger.info("Testing ASCEND connection...")
    status = client.test_connection()

    if status["status"] != "connected":
        raise ConnectionError(f"Failed to connect: {status.get('error')}")

    logger.info(f"Connected to ASCEND (API version: {status.get('api_version')})")

    # Register agent
    logger.info("Registering agent...")

    try:
        registration = client.register(
            agent_type="supervised",
            capabilities=[
                "data_access",
                "data_modification",
                "transaction",
                "communication"
            ],
            allowed_resources=[
                "customer_db",
                "orders_db",
                "stripe_api",
                "sendgrid"
            ],
            metadata={
                "team": "customer-support",
                "version": "2.1.0",
                "owner": "support-team@company.com",
                "repository": "github.com/company/cs-bot",
                "documentation": "https://wiki.company.com/cs-bot"
            }
        )

        logger.info("Registration successful!")
        logger.info(f"  Agent ID: {registration.get('agent_id')}")
        logger.info(f"  Trust Level: {registration.get('trust_level', 'standard')}")

        return client, registration

    except Exception as e:
        if "already exists" in str(e).lower():
            logger.info("Agent already registered (this is OK)")
            return client, {"status": "already_registered"}
        raise

if __name__ == "__main__":
    client, registration = register_agent()
    print(f"Agent ready: {client.agent_id}")

Registration Metadata

Use metadata to track important information about your agent:

metadata = {
    # Ownership
    "team": "customer-support",
    "owner": "jane.doe@company.com",

    # Versioning
    "version": "2.1.0",
    "build": "abc123",

    # Documentation
    "repository": "github.com/company/agent",
    "documentation": "https://docs.company.com/agent",

    # Classification
    "cost_center": "CC-1234",
    "project": "customer-experience",

    # Compliance
    "data_classification": "confidential",
    "compliance_scope": ["SOC2", "HIPAA"]
}

Handling Registration Errors

Common registration errors and solutions:

Error	Cause	Solution
`Authentication failed`	Invalid API key	Verify API key is correct
`Agent already exists`	Duplicate registration	Safe to ignore (idempotent)
`Invalid agent_id`	ID format invalid	Use alphanumeric with hyphens
`Rate limit exceeded`	Too many requests	Wait and retry
`Connection timeout`	Network issues	Check connectivity

from ascend.exceptions import (
    AuthenticationError,
    ValidationError,
    RateLimitError,
    ConnectionError
)

try:
    registration = client.register(...)
except AuthenticationError:
    print("Invalid API key - check your credentials")
except ValidationError as e:
    print(f"Invalid input: {e.field_errors}")
except RateLimitError as e:
    print(f"Rate limited - retry after {e.retry_after} seconds")
except ConnectionError:
    print("Cannot reach ASCEND - check network connectivity")

Re-registration and Updates

Agent registration is idempotent. Calling register() multiple times is safe:

First call: Creates the agent
Subsequent calls: Updates metadata (if changed)

To update an agent's capabilities:

# Update capabilities by re-registering
registration = client.register(
    agent_type="supervised",
    capabilities=[
        "data_access",
        "data_modification",
        "transaction",
        "communication",
        "data_export"  # New capability added
    ],
    allowed_resources=[
        "customer_db",
        "orders_db",
        "stripe_api",
        "sendgrid",
        "reporting_api"  # New resource added
    ]
)

Next Steps

Your agent is now registered with ASCEND. Continue with:

Create Your First Policy: Define governance rules for your agent
Evaluate Your First Action: Submit an action for authorization
Dashboard Tour: Monitor your agent in the console

Last Updated: 2026-01-20

Prerequisites​

Understanding Agent Registration​

Step 1: Choose Your Agent ID​

Step 2: Initialize the Client​

Python​

Node.js​

Step 3: Define Capabilities​

Standard Capabilities​

Example Capability Definitions​

Step 4: Specify Allowed Resources​

Resource Types​

Example Resource Definitions​

Step 5: Register the Agent​

Python​

Node.js​

Step 6: Verify Registration​

Agent Types Explained​

Supervised Agent​

Autonomous Agent​

MCP Server​

Complete Registration Example​

Registration Metadata​

Handling Registration Errors​

Re-registration and Updates​

Next Steps​

Prerequisites

Understanding Agent Registration

Step 1: Choose Your Agent ID

Step 2: Initialize the Client

Python

Node.js

Step 3: Define Capabilities

Standard Capabilities

Example Capability Definitions

Step 4: Specify Allowed Resources

Resource Types

Example Resource Definitions

Step 5: Register the Agent

Python

Node.js

Step 6: Verify Registration

Agent Types Explained

Supervised Agent

Autonomous Agent

MCP Server

Complete Registration Example

Registration Metadata

Handling Registration Errors

Re-registration and Updates

Next Steps