Agent Capabilities

Overview

Agent capabilities define what an AI agent is permitted to do within the Ascend governance platform. Capabilities include action types, resource access, data classification restrictions, and operational constraints. Properly configured capabilities ensure agents operate within security boundaries while maintaining the flexibility to perform their intended functions.

Key Capabilities

Action Type Restrictions: Define which action types an agent can perform
Resource Access Control: Specify allowed and blocked resources
Data Classification Enforcement: Control access based on data sensitivity
Rate Limiting: Constrain action throughput
Budget Controls: Monitor and limit operational costs
Time Windows: Restrict operational hours
Anomaly Detection: Identify unusual behavior patterns

How It Works

Capability Evaluation Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                      CAPABILITY EVALUATION PIPELINE                          │
└─────────────────────────────────────────────────────────────────────────────┘

Action Submitted
      │
      v
┌─────────────────┐
│  1. Agent Active │──── FAIL ────> Action Rejected (Agent Suspended)
│     Check        │
└────────┬────────┘
         │ PASS
         v
┌─────────────────┐
│  2. Action Type  │──── FAIL ────> Action Rejected (Action Not Allowed)
│     Allowed?     │
└────────┬────────┘
         │ PASS
         v
┌─────────────────┐
│  3. Resource     │──── FAIL ────> Action Rejected (Resource Blocked)
│     Permitted?   │
└────────┬────────┘
         │ PASS
         v
┌─────────────────┐
│  4. Data Class   │──── FAIL ────> Action Rejected (Classification Blocked)
│     Allowed?     │
└────────┬────────┘
         │ PASS
         v
┌─────────────────┐
│  5. Rate Limit   │──── FAIL ────> Action Rejected (Rate Limited)
│     OK?          │
└────────┬────────┘
         │ PASS
         v
┌─────────────────┐
│  6. Budget       │──── FAIL ────> Action Rejected (Budget Exceeded)
│     Available?   │
└────────┬────────┘
         │ PASS
         v
┌─────────────────┐
│  7. Time Window  │──── FAIL ────> Action Rejected (Outside Hours)
│     Active?      │
└────────┬────────┘
         │ PASS
         v
┌─────────────────┐
│  8. Risk Score   │
│     Calculation  │────────────────> Policy Evaluation
└─────────────────┘

Action Type Categories

Category	Examples	Default Risk
Read Operations	query, read, list, describe, get	Low (10-25)
Write Operations	create, update, modify, put, post	Medium (40-60)
Delete Operations	delete, remove, destroy, drop, truncate	High (70-90)
Execute Operations	execute, run, invoke, call	Medium-High (50-75)
Admin Operations	admin, configure, manage, grant, revoke	Critical (80-95)

Resource Classification

Resources are evaluated against three lists in order:

Blocked Resources (highest priority): Explicit deny - action immediately rejected
Allowed Resources: Explicit allow - action proceeds to next check
Default Behavior: If not in either list, depends on configuration (default: allow)

Resource Evaluation:
┌─────────────────┐
│ Is resource in  │──── YES ────> DENY (immediate)
│ blocked_list?   │
└────────┬────────┘
         │ NO
         v
┌─────────────────┐
│ Is resource in  │──── YES ────> ALLOW (proceed)
│ allowed_list?   │
└────────┬────────┘
         │ NO
         v
┌─────────────────┐
│ Default policy? │──── DENY ────> DENY
│                 │──── ALLOW ───> ALLOW (proceed)
└─────────────────┘

Configuration

Action Type Configuration

# Define allowed action types for an agent
allowed_action_types = [
    # Read operations
    "query",
    "read",
    "list",
    "describe",

    # Limited write operations
    "create",
    "update",

    # Specific business operations
    "invoice_process",
    "ticket_route",
    "lead_score"
]

Resource Configuration

# Allowed resources (explicit allow list)
allowed_resources = [
    "invoice_database",
    "vendor_api",
    "approval_workflow",
    "reporting_service"
]

# Blocked resources (explicit deny list - takes precedence)
blocked_resources = [
    "credentials_vault",
    "payment_gateway",
    "employee_pii",
    "production_admin",
    "audit_logs_write"
]

Data Classification Configuration

# Allowed data classifications
allowed_data_classifications = [
    "public",
    "internal",
    "confidential-business"
]

# Blocked data classifications (takes precedence)
blocked_data_classifications = [
    "pii",
    "financial",
    "secret",
    "top-secret",
    "hipaa-phi"
]

Rate Limit Configuration

Parameter	Type	Description	Example
`max_actions_per_minute`	integer	Maximum actions per minute	100
`max_actions_per_hour`	integer	Maximum actions per hour	2000
`max_actions_per_day`	integer	Maximum actions per day	10000

Budget Configuration

Parameter	Type	Description	Example
`max_daily_budget_usd`	float	Daily spending limit	500.00
`budget_alert_threshold_percent`	integer	Alert at this % usage	80
`auto_suspend_on_budget_exceeded`	boolean	Auto-suspend when exceeded	true

Time Window Configuration

Parameter	Type	Description	Example
`time_window_enabled`	boolean	Enable time restrictions	true
`time_window_start`	string	Start time (HH:MM)	"09:00"
`time_window_end`	string	End time (HH:MM)	"17:00"
`time_window_timezone`	string	Timezone	"America/New_York"
`time_window_days`	array	Allowed days (1=Mon)	[1,2,3,4,5]

Anomaly Detection Configuration

Parameter	Type	Description	Example
`anomaly_detection_enabled`	boolean	Enable anomaly detection	true
`baseline_actions_per_hour`	float	Normal action rate	150.0
`baseline_error_rate`	float	Normal error rate	0.02
`baseline_avg_risk_score`	float	Normal risk score	35.0
`anomaly_threshold_percent`	float	Alert on % deviation	50.0

Usage Examples

Configure Full Capabilities (Python SDK)

from ascend import AscendClient

client = AscendClient(api_key="your-api-key")

# Update agent with comprehensive capability configuration
agent = client.agents.update(
    agent_id="finance-invoice-processor",

    # Action type restrictions
    allowed_action_types=[
        "invoice_read",
        "invoice_create",
        "invoice_update",
        "invoice_submit",
        "vendor_lookup",
        "approval_request"
    ],

    # Resource access control
    allowed_resources=[
        "invoice_db",
        "vendor_api",
        "approval_workflow",
        "email_notification"
    ],
    blocked_resources=[
        "payment_gateway",
        "bank_api",
        "employee_pii",
        "salary_data",
        "credentials_vault"
    ],

    # Data classification
    allowed_data_classifications=["public", "internal", "business-confidential"],
    blocked_data_classifications=["pii", "financial-regulated", "secret"],

    version_notes="Updated capabilities for Q1 2026"
)

Configure Rate Limits (cURL)

curl -X PUT https://api.ascend.security/api/registry/agents/my-agent/rate-limits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_actions_per_minute": 50,
    "max_actions_per_hour": 1000,
    "max_actions_per_day": 5000
  }'

Configure Budget Controls (cURL)

curl -X PUT https://api.ascend.security/api/registry/agents/my-agent/budget \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_daily_budget_usd": 250.00,
    "budget_alert_threshold_percent": 75,
    "auto_suspend_on_exceeded": true
  }'

Configure Time Windows (cURL)

curl -X PUT https://api.ascend.security/api/registry/agents/my-agent/time-window \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "start_time": "08:00",
    "end_time": "18:00",
    "timezone": "America/New_York",
    "allowed_days": [1, 2, 3, 4, 5]
  }'

Configure Data Classifications (cURL)

curl -X PUT https://api.ascend.security/api/registry/agents/my-agent/data-classifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_classifications": ["public", "internal"],
    "blocked_classifications": ["pii", "financial", "secret", "hipaa"]
  }'

Get Agent Usage Statistics

curl -X GET https://api.ascend.security/api/registry/agents/my-agent/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "agent_id": "my-agent",
#   "status": "active",
#   "rate_limits": {
#     "per_minute": {"limit": 50, "current": 12, "remaining": 38},
#     "per_hour": {"limit": 1000, "current": 245, "remaining": 755},
#     "per_day": {"limit": 5000, "current": 1823, "remaining": 3177}
#   },
#   "budget": {
#     "max_daily_usd": 250.00,
#     "current_spend_usd": 87.50,
#     "remaining_usd": 162.50,
#     "alert_sent": false
#   },
#   "anomaly_detection": {
#     "enabled": true,
#     "last_check": "2026-01-20T14:00:00Z",
#     "count_24h": 0
#   },
#   "health": {
#     "status": "online",
#     "last_heartbeat": "2026-01-20T14:30:00Z",
#     "error_rate_percent": 0.5
#   }
# }

Set Anomaly Baselines

# After agent behavior stabilizes, set baselines
curl -X POST https://api.ascend.security/api/registry/agents/my-agent/set-baselines \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "success": true,
#   "agent_id": "my-agent",
#   "baselines": {
#     "actions_per_hour": 150.0,
#     "error_rate": 0.02,
#     "avg_risk_score": 35.0,
#     "threshold_percent": 50.0
#   }
# }

Check for Anomalies

curl -X GET https://api.ascend.security/api/registry/agents/my-agent/anomalies \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response (when anomaly detected):
# {
#   "agent_id": "my-agent",
#   "anomaly_detection": {
#     "enabled": true,
#     "has_anomaly": true,
#     "severity": "high",
#     "anomalies": [
#       {
#         "type": "action_rate_spike",
#         "baseline": 150.0,
#         "current": 450.0,
#         "deviation_percent": 200.0,
#         "message": "Action rate 3x above baseline"
#       }
#     ],
#     "count_24h": 3
#   }
# }

Best Practices

Action Type Guidelines

Principle of Least Privilege: Only grant action types that are absolutely necessary.

# GOOD - Specific, minimal permissions
allowed_action_types = [
    "invoice_read",
    "invoice_create",
    "invoice_update"
]

# BAD - Overly broad permissions
allowed_action_types = [
    "read",
    "write",
    "delete",
    "execute"
]

Resource Access Guidelines

Default Deny Pattern: Use allowed_resources as a whitelist, not blocked_resources as a blacklist.

# PREFERRED - Explicit allow list (default deny)
allowed_resources = [
    "specific_database_1",
    "specific_api_2",
    "specific_service_3"
]
blocked_resources = []  # Empty - not in allowed = blocked

# LESS PREFERRED - Block list only (default allow)
allowed_resources = []  # Empty = allow all not blocked
blocked_resources = [
    "sensitive_resource_1",
    "sensitive_resource_2"
]
# Risk: New sensitive resources may not be blocked

Rate Limiting Guidelines

Agent Type	Recommended per_minute	Recommended per_hour
Low-volume batch	10	100
Standard API	60	1000
High-throughput	200	5000
Streaming	500	10000

Warning Thresholds: Set alerts at 80% of limits to catch issues before hard blocks.

Budget Guidelines

Start Conservative: Begin with lower budgets and increase based on actual usage
Alert Early: Set alert thresholds at 60-75% to allow time to react
Auto-Suspend Critical: Enable auto-suspend for production agents
Review Weekly: Check budget utilization trends weekly

Time Window Guidelines

Use Case	Recommended Window
Business operations	08:00-18:00 local, Mon-Fri
Global operations	24/7 (no restrictions)
Maintenance windows	Specific hours on weekends
High-risk operations	Reduced hours with monitoring

Anomaly Detection Guidelines

Wait for Stability: Set baselines only after 2+ weeks of normal operation
Start Lenient: Begin with 50% deviation threshold, tighten as needed
Multiple Metrics: Monitor action rate, error rate, AND risk score
Alert, Don't Block: Use anomalies for alerting, not automatic blocking (initially)

Security Recommendations

Block Sensitive Resources Explicitly: Always list credentials, PII, and payment systems
Limit Delete Operations: Most agents should not have delete permissions
Audit Admin Actions: Any admin-level action types require special scrutiny
Data Classification First: Implement data classification restrictions before going live
Review Quarterly: Audit capabilities quarterly and remove unused permissions

Agent Registry Overview - Complete registry documentation
Agent Registration Guide - Step-by-step registration
Policy Management - Policy-based governance
Risk Scoring - Risk calculation details
Alerts Configuration - Setting up capability alerts

Compliance

Capability management supports compliance with:

SOC 2 CC6.1: Logical access controls
SOC 2 CC6.2: Access authorization
SOC 2 CC7.1: Security incident management
PCI-DSS 7.1: Restrict access by business need
PCI-DSS 7.2: Access control systems
NIST 800-53 AC-3: Access enforcement
NIST 800-53 AC-6: Least privilege
NIST 800-53 SI-4: Information system monitoring
HIPAA 164.312(a): Access control
GDPR Article 25: Data protection by design

Overview​

Key Capabilities​

How It Works​

Capability Evaluation Flow​

Action Type Categories​

Resource Classification​

Configuration​

Action Type Configuration​

Resource Configuration​

Data Classification Configuration​

Rate Limit Configuration​

Budget Configuration​

Time Window Configuration​

Anomaly Detection Configuration​

Usage Examples​

Configure Full Capabilities (Python SDK)​

Configure Rate Limits (cURL)​

Configure Budget Controls (cURL)​

Configure Time Windows (cURL)​

Configure Data Classifications (cURL)​

Get Agent Usage Statistics​

Set Anomaly Baselines​

Check for Anomalies​

Best Practices​

Action Type Guidelines​

Resource Access Guidelines​

Rate Limiting Guidelines​

Budget Guidelines​

Time Window Guidelines​

Anomaly Detection Guidelines​

Security Recommendations​

Related​

Compliance​