Skip to main content

Python SDK Installation

Install the ASCEND Python SDK and verify your setup.

Requirements​

  • Python 3.9 or higher
  • pip package manager

Installation​

pip install ascend-ai-sdk

This installs the ascend module with all dependencies (requests).

Verify Installation​

from ascend import AscendClient, Decision, FailMode

client = AscendClient(
    api_key="owkai_your_api_key_here",
    agent_id="test-agent",
    agent_name="Test Agent",
)

status = client.test_connection()

if status["status"] == "connected":
    print(f"Connected to ASCEND (v{status['api_version']})")
else:
    print(f"Connection error: {status.get('error')}")

Environment Variables​

The SDK reads configuration from environment variables when parameters are not provided directly:

VariableRequiredDefaultDescription
ASCEND_API_KEYYes—Your organization API key
ASCEND_API_URLNohttps://pilot.owkai.appAPI endpoint URL
ASCEND_AGENT_IDNo—Default agent identifier
ASCEND_AGENT_NAMENo—Default agent name
export ASCEND_API_KEY="owkai_live_your_api_key_here"
export ASCEND_API_URL="https://pilot.owkai.app"
from ascend import AscendClient

# Client reads from environment variables automatically
client = AscendClient(agent_name="My Agent")

Quick Start​

from ascend import AscendClient, Decision, FailMode

# Initialize with fail-closed mode (recommended for production)
client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="customer-service-agent",
    agent_name="Customer Service AI",
    fail_mode=FailMode.CLOSED,
)

# Register agent with platform
client.register(
    agent_type="automation",
    capabilities=["database.query", "file.read", "api.call"],
    allowed_resources=["production_db", "customer_api"],
)

# Evaluate an action
decision = client.evaluate_action(
    action_type="database.query",
    resource="production_db",
    parameters={"query": "SELECT COUNT(*) FROM users"},
)

if decision.decision == Decision.ALLOWED:
    print(f"Approved! Risk score: {decision.risk_score}")
elif decision.decision == Decision.DENIED:
    print(f"Denied: {decision.reason}")
elif decision.decision == Decision.PENDING:
    print(f"Pending approval: {decision.approval_request_id}")

Docker Installation​

FROM python:3.11-slim

RUN pip install --no-cache-dir ascend-ai-sdk

COPY your_application.py /app/
WORKDIR /app

CMD ["python", "your_application.py"]

Security Standards​

The SDK implements enterprise security standards:

  • TLS Enforcement — HTTPS required for all non-localhost connections (PY-SEC-002)
  • API Key Masking — Sensitive values masked in all log output (PY-SEC-001)
  • Retry Jitter — Randomized backoff to prevent thundering herd (PY-SEC-003)
  • Input Validation — Action parameters validated before network calls (PY-SEC-004)
  • Risk Score Stripping — Server-side risk scores cannot be injected from client (PY-SEC-005)
  • SOC 2 Type II — Multi-tenant data isolation
  • HIPAA 164.312 — Audit trails for all actions

Logging​

The SDK includes a structured logger with automatic API key masking:

from ascend import AscendClient

# Enable debug logging
client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="my-agent",
    agent_name="My Agent",
    debug=True,
)

API keys, bearer tokens, and other sensitive values are automatically masked in all log output.

Troubleshooting​

Missing API Key​

AuthenticationError: API key is required. Set ASCEND_API_KEY or pass api_key parameter.

Solution: Set the environment variable or pass api_key directly:

export ASCEND_API_KEY=owkai_live_your_key

TLS Error on Remote URL​

ConfigurationError: TLS required for non-localhost URLs

Solution: Use https:// for all remote API URLs. HTTP is only allowed for localhost and 127.0.0.1.

Connection Errors​

# Increase timeout for slow networks
client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="my-agent",
    agent_name="My Agent",
    timeout=60,
)

Next Steps​

Last updated on