Core Concepts

This guide explains the fundamental concepts you need to understand when working with ASCEND. These concepts form the foundation of how ASCEND governs AI agent operations.

Agents

An agent is any autonomous or semi-autonomous system that performs actions on behalf of users or processes. In ASCEND, agents are the primary actors that require governance.

Agent Types

ASCEND supports different agent types based on their level of autonomy:

Agent Type	Description	Typical Use Cases
`supervised`	Agents that operate under human oversight	Customer service bots, data analysts
`autonomous`	Fully automated agents with minimal human intervention	Scheduled jobs, monitoring systems
`mcp_server`	MCP (Model Context Protocol) servers providing tools	Database connectors, file systems

Agent Identity

Every agent in ASCEND has a unique identity defined by:

client = AscendClient(
    agent_id="customer-service-bot-001",  # Unique identifier
    agent_name="Customer Service Bot",     # Human-readable name
    agent_type="supervised"
)

Field	Purpose	Example
`agent_id`	Unique identifier across your organization	`cs-bot-001`, `data-pipeline-prod`
`agent_name`	Human-readable display name	`Customer Service Bot`
`agent_type`	Classification for policy matching	`supervised`, `autonomous`

Agent Capabilities

Agents declare their capabilities during registration. Capabilities describe what an agent can do:

client.register(
    agent_type="supervised",
    capabilities=[
        "data_access",        # Can read data
        "data_modification",  # Can write/update data
        "transaction",        # Can perform financial transactions
        "file_operations"     # Can read/write files
    ],
    allowed_resources=[
        "customer_db",        # Specific database
        "/var/log/app"        # Specific file path
    ]
)

Capabilities help ASCEND match appropriate policies and assess risk.

Actions

An action is any operation an agent attempts to perform that requires authorization. Every action goes through ASCEND before execution.

Action Structure

Actions have a standardized structure:

decision = client.evaluate_action(
    action_type="database.query",           # Category.operation format
    resource="production_db",               # What resource is involved
    parameters={                            # Action-specific details
        "sql": "SELECT * FROM customers",
        "limit": 100
    },
    context={                               # Additional context
        "user_request": "Show me all customers",
        "session_id": "sess_12345"
    }
)

Action Types

Actions are categorized using a hierarchical naming convention:

Category	Action Type	Description
Data	`data_access`	Reading data from any source
	`data_modification`	Creating, updating, or deleting data
	`data_export`	Exporting data outside the system
Database	`database.query`	SQL SELECT operations
	`database.write`	SQL INSERT/UPDATE operations
	`database.delete`	SQL DELETE operations
	`database.admin`	DDL operations (CREATE, DROP, ALTER)
File	`file.read`	Reading file contents
	`file.write`	Writing to files
	`file.delete`	Deleting files
Financial	`financial.refund`	Processing refunds
	`financial.transfer`	Money transfers
	`financial.payment`	Payment processing
System	`system.config`	Configuration changes
	`system.restart`	Service restarts
	`api_call`	External API invocations
Communication	`communication.email`	Sending emails
	`communication.sms`	Sending SMS messages

Action Lifecycle

Every action follows a defined lifecycle:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Submit    │────▶│  Evaluate   │────▶│   Decide    │
│   Action    │     │   Policy    │     │             │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
                    ▼                          ▼                          ▼
            ┌─────────────┐           ┌─────────────┐            ┌─────────────┐
            │   Allowed   │           │   Pending   │            │   Denied    │
            │             │           │  Approval   │            │             │
            └──────┬──────┘           └──────┬──────┘            └──────┬──────┘
                   │                         │                          │
                   ▼                         ▼                          ▼
            ┌─────────────┐           ┌─────────────┐            ┌─────────────┐
            │   Execute   │           │   Review    │            │    Log &    │
            │   Action    │           │  & Approve  │            │   Reject    │
            └──────┬──────┘           └──────┬──────┘            └─────────────┘
                   │                         │
                   │                         ▼
                   │                  ┌─────────────┐
                   │                  │  Approved / │
                   │                  │   Denied    │
                   │                  └──────┬──────┘
                   │                         │
                   ▼                         ▼
            ┌─────────────────────────────────────┐
            │         Log Completion              │
            │   (Success or Failure)              │
            └─────────────────────────────────────┘

Decisions

A decision is ASCEND's response to an action evaluation request. Every action receives exactly one decision.

Decision Types

Decision	Value	Meaning
Allowed	`allowed`	Action is permitted; proceed with execution
Denied	`denied`	Action is blocked; do not execute
Pending	`pending`	Action requires human approval before execution

Decision Response

The decision response contains comprehensive information:

decision = client.evaluate_action(...)

# Decision properties
decision.action_id          # Unique ID for audit trail
decision.decision           # allowed, denied, or pending
decision.risk_score         # 0-100 risk assessment
decision.reason             # Human-readable explanation
decision.policy_violations  # List of violated policies (if any)
decision.approval_request_id # ID to track approval (if pending)
decision.conditions         # Any conditions applied

Handling Decisions

from ascend import Decision

decision = client.evaluate_action(
    action_type="financial.refund",
    resource="payment_gateway",
    parameters={"amount": 500, "customer_id": "cust_123"}
)

if decision.decision == Decision.ALLOWED:
    # Safe to proceed
    result = process_refund()
    client.log_action_completed(decision.action_id, result)

elif decision.decision == Decision.PENDING:
    # Requires human approval
    print(f"Approval required. Notify approvers.")
    # Optionally wait: decision = client.wait_for_decision(decision.action_id)

elif decision.decision == Decision.DENIED:
    # Not allowed
    print(f"Action denied: {decision.reason}")
    for violation in decision.policy_violations:
        print(f"  - {violation}")

Policies

A policy is a rule that defines how ASCEND should evaluate and respond to specific actions. Policies are the core of ASCEND's governance model.

Policy Components

Component	Description	Example
Name	Human-readable identifier	"High Value Refund Approval"
Conditions	When the policy applies	`action_type == "financial.refund"`
Action	What to do when conditions match	`require_approval`, `deny`, `allow`
Priority	Order of evaluation (higher = first)	100

Policy Types

ASCEND supports several policy action types:

Action	Behavior
`allow`	Permit the action immediately
`deny`	Block the action
`require_approval`	Route to human approvers
`flag`	Allow but create an alert
`modify`	Allow with modifications (e.g., add conditions)

Policy Matching

Policies are matched against actions using conditions:

{
    "name": "Block PII Export",
    "conditions": {
        "action_type": "data_export",
        "resource": {"$contains": "customer"},
        "parameters.includes_pii": true
    },
    "action": "deny",
    "reason": "Exporting PII requires special authorization"
}

Policy Hierarchy

Policies are evaluated in priority order. The first matching policy determines the decision:

Priority 100: Deny all database.admin actions        → Checked first
Priority 75:  Require approval for financial > $1000 → Checked second
Priority 50:  Allow read-only data_access            → Checked third
Priority 0:   Default policy                         → Fallback

Risk Scoring

Risk scoring quantifies the potential impact of an action on a scale from 0 to 100. Higher scores indicate higher risk.

Risk Score Ranges

Level	Score Range	Typical Response
Low	0-44	Auto-approve
Medium	45-69	Allow with logging
High	70-84	Require approval
Critical	85-100	Block or escalate

Risk Factors

ASCEND considers multiple factors when calculating risk:

Factor	Description	Impact
Action Type	Some actions are inherently riskier	DELETE > SELECT
Resource Sensitivity	PII, financial data, production systems	+20-40 points
Data Volume	Number of records affected	Scales with volume
Agent Trust Level	Established vs. new agents	Lower trust = higher risk
Time of Day	Actions outside business hours	+10-20 points
Historical Behavior	Past policy violations	+15-30 points

Risk Indicators

You can provide risk hints to help ASCEND assess risk more accurately:

decision = client.evaluate_action(
    action_type="data_access",
    resource="customer_db",
    parameters={"query": "SELECT * FROM customers"},
    risk_indicators={
        "pii_involved": True,
        "financial_data": False,
        "external_transfer": False,
        "data_sensitivity": "high"
    }
)

Organizations and Tenants

ASCEND is a multi-tenant platform where each organization has complete isolation.

Organization Isolation

Aspect	Isolation Level
Data	Complete database isolation via Row-Level Security
API Keys	Keys work only for issuing organization
Policies	Policies apply only within organization scope
Agents	Agents registered to specific organizations
Audit Logs	Logs visible only to organization members

Organization Hierarchy

Organization (Company)
├── Users (Admin, Analyst, Viewer)
├── API Keys (For programmatic access)
├── Agents (Registered AI agents)
├── Policies (Governance rules)
└── Resources (Protected assets)

Audit Trail

Every action in ASCEND creates an immutable audit trail record for compliance purposes.

Audit Record Contents

Field	Description
`timestamp`	When the action occurred (UTC)
`action_id`	Unique action identifier
`agent_id`	Which agent performed the action
`action_type`	Type of action
`resource`	Target resource
`decision`	Authorization decision
`risk_score`	Calculated risk score
`policy_matched`	Which policy determined the decision
`approver`	Who approved (if applicable)
`completion_status`	Success or failure
`hash`	Cryptographic hash for integrity

Compliance Features

Immutability: Audit records cannot be modified or deleted
Hash Chaining: Each record includes a hash of the previous record
WORM Storage: Write-Once-Read-Many storage pattern
Retention: Configurable retention periods (default: 7 years)

Summary

Concept	Purpose	Key Points
Agent	Actor performing actions	Has ID, name, type, capabilities
Action	Operation requiring authorization	Has type, resource, parameters
Decision	Authorization response	Allowed, denied, or pending
Policy	Governance rule	Conditions, actions, priority
Risk Score	Quantified risk assessment	0-100 scale
Organization	Tenant isolation boundary	Complete data separation
Audit Trail	Compliance record	Immutable, hash-chained

Next Steps

Now that you understand the core concepts:

Platform Architecture: See how these concepts fit together
Register Your First Agent: Put these concepts into practice
Create Your First Policy: Define your governance rules

Last Updated: 2026-01-20

Agents​

Agent Types​

Agent Identity​

Agent Capabilities​

Actions​

Action Structure​

Action Types​

Action Lifecycle​

Decisions​

Decision Types​

Decision Response​

Handling Decisions​

Policies​

Policy Components​

Policy Types​

Policy Matching​

Policy Hierarchy​

Risk Scoring​

Risk Score Ranges​

Risk Factors​

Risk Indicators​

Organizations and Tenants​

Organization Isolation​

Organization Hierarchy​

Audit Trail​

Audit Record Contents​

Compliance Features​

Summary​

Next Steps​