Client Configuration

Configure AscendClient for your environment and requirements.

Constructor Parameters

from ascend import AscendClient, FailMode

client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="my-agent-001",
    agent_name="My AI Agent",
    api_url="https://pilot.owkai.app",
    environment="production",
    fail_mode=FailMode.CLOSED,
    timeout=5,
    max_retries=3,
    enable_circuit_breaker=True,
    circuit_breaker_threshold=5,
    circuit_breaker_timeout=30,
    signing_secret=None,
    debug=False,
)

Parameter	Type	Default	Description
api_key	str	None	Organization API key. Falls back to ASCEND_API_KEY env var.
agent_id	str	None	Unique agent identifier. Falls back to ASCEND_AGENT_ID.
agent_name	str	None	Human-readable agent name. Falls back to ASCEND_AGENT_NAME.
api_url	str	https://pilot.owkai.app	API endpoint URL. Falls back to ASCEND_API_URL.
environment	str	"production"	Deployment environment (production, staging, development).
fail_mode	FailMode	FailMode.CLOSED	Behavior when ASCEND is unreachable.
timeout	int	5	Request timeout in seconds.
max_retries	int	3	Maximum retry attempts for failed requests.
enable_circuit_breaker	bool	True	Enable circuit breaker pattern.
circuit_breaker_threshold	int	5	Failures before opening circuit.
circuit_breaker_timeout	int	30	Seconds before attempting recovery.
signing_secret	str	None	HMAC secret for request signing.
debug	bool	False	Enable debug logging.

Initialization Methods

Method 1: Direct Parameters

from ascend import AscendClient

client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="my-agent-001",
    agent_name="My AI Agent",
)

Method 2: Environment Variables

export ASCEND_API_KEY="owkai_live_xxxxxxxxxxxx"
export ASCEND_AGENT_ID="my-agent-001"
export ASCEND_AGENT_NAME="My AI Agent"

from ascend import AscendClient

# Client reads from environment
client = AscendClient()

Method 3: Mixed Approach

import os
from ascend import AscendClient

# Override specific settings; rest from env
client = AscendClient(
    api_key=os.getenv("CUSTOM_API_KEY"),
    timeout=60,
)

Fail Mode Configuration

The SDK supports two fail modes that control behavior when the ASCEND API is unreachable:

Mode	Behavior	Use Case
FailMode.CLOSED	Block all actions when ASCEND is unreachable	Production (recommended)
FailMode.OPEN	Allow all actions when ASCEND is unreachable	Development/testing

from ascend import AscendClient, FailMode

# Production: fail-closed (secure default)
prod_client = AscendClient(
    api_key="owkai_prod_xxxxxxxxxxxx",
    agent_id="prod-agent",
    agent_name="Production Agent",
    fail_mode=FailMode.CLOSED,
)

# Development: fail-open (for testing)
dev_client = AscendClient(
    api_key="owkai_dev_xxxxxxxxxxxx",
    agent_id="dev-agent",
    agent_name="Dev Agent",
    fail_mode=FailMode.OPEN,
)

Circuit Breaker

The built-in circuit breaker prevents cascading failures when the API is unhealthy:

• Closed — Normal operation, requests pass through
• Open — After threshold failures, all requests are rejected immediately
• Half-Open — After recovery timeout, allows test requests to check recovery

from ascend import AscendClient

client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="my-agent",
    agent_name="My Agent",
    enable_circuit_breaker=True,
    circuit_breaker_threshold=5,   # Open after 5 failures
    circuit_breaker_timeout=30,    # Try recovery after 30s
)

Environment-Specific Configuration

import os
from ascend import AscendClient, FailMode

def get_client():
    """Get client configured for current environment."""
    env = os.getenv("ENVIRONMENT", "development")

    configs = {
        "development": {
            "api_url": "https://dev.owkai.app",
            "fail_mode": FailMode.OPEN,
            "debug": True,
            "timeout": 60,
        },
        "staging": {
            "api_url": "https://staging.owkai.app",
            "fail_mode": FailMode.CLOSED,
            "debug": False,
            "timeout": 30,
        },
        "production": {
            "api_url": "https://pilot.owkai.app",
            "fail_mode": FailMode.CLOSED,
            "debug": False,
            "timeout": 5,
        },
    }

    config = configs.get(env, configs["development"])
    return AscendClient(
        agent_id="my-agent",
        agent_name="My Agent",
        **config,
    )

Request Signing

For additional security, configure HMAC request signing:

from ascend import AscendClient

client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="my-agent",
    agent_name="My Agent",
    signing_secret="your_hmac_secret_here",
)

When a signing secret is configured, every request includes an X-Signature header with an HMAC-SHA256 signature of the request body.

Thread Safety

AscendClient is thread-safe. Create a single instance and share it across threads:

from ascend import AscendClient, AgentAction
from concurrent.futures import ThreadPoolExecutor

client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="my-agent",
    agent_name="My Agent",
)

def evaluate(action_type, resource):
    return client.evaluate_action(action_type=action_type, resource=resource)

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = [
        executor.submit(evaluate, "data.read", "db1"),
        executor.submit(evaluate, "data.write", "db2"),
    ]
    for f in futures:
        print(f.result().decision)

Or use the built-in bulk evaluation:

from ascend import AscendClient, AgentAction

actions = [
    AgentAction(agent_id="bot", agent_name="Bot", action_type="data.read", resource="db1"),
    AgentAction(agent_id="bot", agent_name="Bot", action_type="data.write", resource="db2"),
]

result = client.evaluate_actions(actions, max_concurrent=5)
print(f"{result.succeeded}/{result.total} succeeded")

Connection Testing

from ascend import AscendClient

client = AscendClient(
    api_key="owkai_live_xxxxxxxxxxxx",
    agent_id="my-agent",
    agent_name="My 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')}")

Best Practices

1. Reuse client instances — Create one client and share it across your application.
2. Use environment variables — Never hardcode API keys in source code.
3. Use fail-closed in production — FailMode.CLOSED is the secure default.
4. Set appropriate timeouts — Use short timeouts (5s) for real-time operations, longer (60s+) for batch processing.
5. Enable circuit breaker — Prevents cascading failures when the API is unhealthy.

Next Steps

• Agent Actions — Submit and manage actions
• Error Handling — Handle errors gracefully
• API Reference — Complete API documentation