Quick Start Guide

This guide walks you through integrating ASCEND with your AI agent in under 5 minutes. By the end, you will have a working agent that evaluates actions against ASCEND policies.

Prerequisites

Before you begin, ensure you have:

• An ASCEND account with API access
• Python 3.9+ or Node.js 18+
• Your API key from the ASCEND Console

Step 1: Install the SDK

Choose your preferred language:

Python

pip install ascend-ai-sdk

Node.js

npm install @ascend-ai/sdk

Step 2: Set Your API Key

Store your API key securely as an environment variable:

export ASCEND_API_KEY="your_api_key_here"

For production deployments, use a secrets manager like AWS Secrets Manager or HashiCorp Vault.

Step 3: Initialize the Client

Python

from ascend import AscendClient, FailMode

# Initialize the ASCEND client
client = AscendClient(
    api_key="your_api_key_here",  # Or use ASCEND_API_KEY env var
    agent_id="my-first-agent",
    agent_name="My First AI Agent",
    fail_mode=FailMode.CLOSED  # Block actions if ASCEND is unreachable
)

# Test the connection
status = client.test_connection()
print(f"Connection status: {status['status']}")

Node.js

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

// Initialize the ASCEND client
const client = new AscendClient({
    apiKey: 'your_api_key_here',  // Or use ASCEND_API_KEY env var
    agentId: 'my-first-agent',
    agentName: 'My First AI Agent',
    failMode: FailMode.CLOSED  // Block actions if ASCEND is unreachable
});

// Test the connection
const status = await client.testConnection();
console.log(`Connection status: ${status.status}`);

Step 4: Register Your Agent

Register your agent with ASCEND to establish its identity and capabilities:

Python

# Register the agent
registration = client.register(
    agent_type="supervised",
    capabilities=["data_access", "file_operations"],
    allowed_resources=["customer_db", "/var/log"]
)

print(f"Agent registered with trust level: {registration.get('trust_level', 'standard')}")

Node.js

// Register the agent
const registration = await client.register({
    agentType: 'supervised',
    capabilities: ['data_access', 'file_operations'],
    allowedResources: ['customer_db', '/var/log']
});

console.log(`Agent registered with trust level: ${registration.trustLevel || 'standard'}`);

Step 5: Evaluate an Action

Before your agent performs any action, evaluate it against ASCEND policies:

Python

from ascend import Decision

# Evaluate an action before execution
decision = client.evaluate_action(
    action_type="data_access",
    resource="customer_db",
    parameters={
        "query": "SELECT email FROM customers WHERE id = 123"
    }
)

# Check the decision
if decision.decision == Decision.ALLOWED:
    print(f"Action allowed (risk score: {decision.risk_score})")
    # Proceed with the action
    result = execute_database_query()

    # Log successful completion
    client.log_action_completed(
        action_id=decision.action_id,
        result={"rows_returned": len(result)}
    )

elif decision.decision == Decision.PENDING:
    print(f"Action requires approval (ID: {decision.approval_request_id})")
    # Optionally wait for approval or notify the user

else:  # Decision.DENIED
    print(f"Action denied: {decision.reason}")
    # Handle the denial appropriately

Node.js

import { Decision } from '@ascend-ai/sdk';

// Evaluate an action before execution
const decision = await client.evaluateAction({
    actionType: 'data_access',
    resource: 'customer_db',
    parameters: {
        query: 'SELECT email FROM customers WHERE id = 123'
    }
});

// Check the decision
if (decision.decision === Decision.ALLOWED) {
    console.log(`Action allowed (risk score: ${decision.riskScore})`);
    // Proceed with the action
    const result = await executeDatabaseQuery();

    // Log successful completion
    await client.logActionCompleted({
        actionId: decision.actionId,
        result: { rowsReturned: result.length }
    });

} else if (decision.decision === Decision.PENDING) {
    console.log(`Action requires approval (ID: ${decision.approvalRequestId})`);
    // Optionally wait for approval or notify the user

} else {  // Decision.DENIED
    console.log(`Action denied: ${decision.reason}`);
    // Handle the denial appropriately
}

Complete Example

Here is a complete working example that demonstrates the full integration:

Python

"""
ASCEND Quick Start Example
--------------------------
A complete example demonstrating ASCEND integration.
"""

import os
from ascend import AscendClient, FailMode, Decision

def main():
    # Initialize client
    client = AscendClient(
        api_key=os.getenv("ASCEND_API_KEY"),
        agent_id="quickstart-agent",
        agent_name="Quick Start Demo Agent",
        fail_mode=FailMode.CLOSED
    )

    # Test connection
    status = client.test_connection()
    if status["status"] != "connected":
        print(f"Connection failed: {status.get('error')}")
        return

    print("Connected to ASCEND successfully!")

    # Register agent
    try:
        registration = client.register(
            agent_type="supervised",
            capabilities=["data_access"],
            allowed_resources=["demo_database"]
        )
        print(f"Agent registered: {registration}")
    except Exception as e:
        print(f"Registration note: {e}")  # May already be registered

    # Evaluate a low-risk action
    print("\n--- Evaluating low-risk action ---")
    decision = client.evaluate_action(
        action_type="data_access",
        resource="demo_database",
        parameters={"query": "SELECT COUNT(*) FROM users"}
    )

    print(f"Decision: {decision.decision.value}")
    print(f"Risk Score: {decision.risk_score}")
    print(f"Action ID: {decision.action_id}")

    if decision.decision == Decision.ALLOWED:
        # Simulate action execution
        print("Executing action...")
        client.log_action_completed(
            action_id=decision.action_id,
            result={"count": 1000}
        )
        print("Action completed and logged.")

    # Evaluate a high-risk action
    print("\n--- Evaluating high-risk action ---")
    decision = client.evaluate_action(
        action_type="data_modification",
        resource="demo_database",
        parameters={"query": "DELETE FROM users WHERE inactive = true"}
    )

    print(f"Decision: {decision.decision.value}")
    print(f"Risk Score: {decision.risk_score}")

    if decision.decision == Decision.DENIED:
        print(f"Reason: {decision.reason}")
    elif decision.decision == Decision.PENDING:
        print(f"Approval required. Request ID: {decision.approval_request_id}")

if __name__ == "__main__":
    main()

Node.js

/**
 * ASCEND Quick Start Example
 * --------------------------
 * A complete example demonstrating ASCEND integration.
 */

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

async function main() {
    // Initialize client
    const client = new AscendClient({
        apiKey: process.env.ASCEND_API_KEY,
        agentId: 'quickstart-agent',
        agentName: 'Quick Start Demo Agent',
        failMode: FailMode.CLOSED
    });

    // Test connection
    const status = await client.testConnection();
    if (status.status !== 'connected') {
        console.log(`Connection failed: ${status.error}`);
        return;
    }

    console.log('Connected to ASCEND successfully!');

    // Register agent
    try {
        const registration = await client.register({
            agentType: 'supervised',
            capabilities: ['data_access'],
            allowedResources: ['demo_database']
        });
        console.log('Agent registered:', registration);
    } catch (e) {
        console.log('Registration note:', e.message);  // May already be registered
    }

    // Evaluate a low-risk action
    console.log('\n--- Evaluating low-risk action ---');
    let decision = await client.evaluateAction({
        actionType: 'data_access',
        resource: 'demo_database',
        parameters: { query: 'SELECT COUNT(*) FROM users' }
    });

    console.log(`Decision: ${decision.decision}`);
    console.log(`Risk Score: ${decision.riskScore}`);
    console.log(`Action ID: ${decision.actionId}`);

    if (decision.decision === Decision.ALLOWED) {
        // Simulate action execution
        console.log('Executing action...');
        await client.logActionCompleted({
            actionId: decision.actionId,
            result: { count: 1000 }
        });
        console.log('Action completed and logged.');
    }

    // Evaluate a high-risk action
    console.log('\n--- Evaluating high-risk action ---');
    decision = await client.evaluateAction({
        actionType: 'data_modification',
        resource: 'demo_database',
        parameters: { query: 'DELETE FROM users WHERE inactive = true' }
    });

    console.log(`Decision: ${decision.decision}`);
    console.log(`Risk Score: ${decision.riskScore}`);

    if (decision.decision === Decision.DENIED) {
        console.log(`Reason: ${decision.reason}`);
    } else if (decision.decision === Decision.PENDING) {
        console.log(`Approval required. Request ID: ${decision.approvalRequestId}`);
    }
}

main().catch(console.error);

Understanding the Response

When you call evaluate_action(), ASCEND returns an authorization decision:

Field	Type	Description
action_id	string	Unique identifier for audit trail
decision	enum	allowed, denied, or pending
risk_score	integer	Risk score from 0-100
reason	string	Human-readable explanation
policy_violations	array	List of violated policies (if denied)
approval_request_id	string	ID for tracking approval (if pending)

Fail Modes

ASCEND supports two fail modes that control behavior when the service is unreachable:

Mode	Behavior	Use Case
CLOSED	Block all actions if ASCEND is unreachable	High-security environments (recommended)
OPEN	Allow all actions if ASCEND is unreachable	High-availability requirements

# Fail-secure (recommended for production)
client = AscendClient(
    api_key="...",
    agent_id="...",
    fail_mode=FailMode.CLOSED
)

# Fail-open (use with caution)
client = AscendClient(
    api_key="...",
    agent_id="...",
    fail_mode=FailMode.OPEN
)

What is Next?

Congratulations! You have successfully integrated ASCEND with your AI agent. Here are your next steps:

1. Core Concepts: Understand agents, policies, actions, and risk scoring
2. Register Your First Agent: Learn about agent types and capabilities
3. Create Your First Policy: Define custom governance rules
4. Dashboard Tour: Explore the ASCEND console

Troubleshooting

Connection Failed

If you see a connection error:

1. Verify your API key is correct
2. Check network connectivity to https://pilot.owkai.app
3. Ensure your firewall allows outbound HTTPS (port 443)

Authentication Error

If you receive a 401 error:

1. Verify your API key has not expired
2. Check that the API key is correctly formatted
3. Ensure the API key has not been revoked

Rate Limited

If you receive a 429 error:

1. The SDK will automatically retry with exponential backoff
2. For sustained high volume, contact support about rate limit increases

Need Help?

• Check the API Reference for detailed endpoint documentation
• Review SDK Documentation for advanced usage
• Contact support through the ASCEND console

---

Last Updated: 2026-01-20