Using ACT with Custom Agents

Overview

If you've built custom AI agents using your own LLM infrastructure or proprietary frameworks, you still need governance to control what resources they can access. ACT provides a framework-agnostic way to enforce policies on any AI agent, regardless of how it's built.

Your custom agent can call external APIs without restrictions
No built-in audit trail for compliance and debugging
Difficult to enforce constraints dynamically without code changes
No rate limiting or quota management
Limited visibility into what resources agents are accessing

ACT solves this by providing a REST API-based governance layer for any custom agent.

Architecture

Custom Agent

Your LLM/AI implementation

→

ACT REST API

                        ✓ Enforce policies

                        ✓ Manage tokens

                        ✓ Audit logs

→

Your Services

Protected resources

⚠️ Authentication Required

All requests to https://api.acttokens.com require:

API Key (in X-Api-Key header) - Platform authentication
Capability Token (in request body) - Agent authorization

Learn more about dual-token authentication →

Quick Start

Step 1: Get Your API Key

ACT_API_KEY="your_api_key_here"
ACT_BASE_URL="https://api.acttokens.com"

Step 2: Register Your Custom Agent

curl -X POST $ACT_BASE_URL/v1/agents \
  -H "X-Api-Key: $ACT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Recommendation Engine",
    "description": "Personalized recommendations powered by custom LLM",
    "metadata": {
      "type": "custom",
      "model": "internal-model-v2",
      "endpoint": "https://your-agent-api/v1/predict"
    }
  }'

Step 3: Define Policies

Create policies that govern what your custom agent can do:

curl -X POST $ACT_BASE_URL/v1/policies \
  -H "X-Api-Key: $ACT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recommendation Engine Policy",
    "actions": ["read", "query", "recommend"],
    "resources": ["api://user_profiles/*", "api://product_catalog/*"],
    "effect": "allow",
    "constraints": {
      "maxQueriesPerMinute": 1000,
      "maxDataPoints": 10000,
      "userDataClassification": "internal",
      "allowCrossRegionAccess": false
    }
  }'

Step 4: Issue an ACT Token

curl -X POST $ACT_BASE_URL/v1/tokens \
  -H "X-Api-Key: $ACT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123",
    "expiresIn": 3600
  }'

# Response: {"token": "eyJhbGc..."}

Step 5: Integrate ACT into Your Custom Agent

Before your agent calls external APIs, validate the request with ACT:

import requests
from uuid import uuid4
from datetime import datetime

class CustomAgentWithACT:
    def __init__(self, act_api_key, act_base_url, act_token):
        self.act_api_key = act_api_key
        self.act_base_url = act_base_url
        self.act_token = act_token
        self.model = self.load_model()  # Load your custom LLM
    
    def load_model(self):
        # Load your custom model
        return load_internal_model()
    
    def validate_action_with_act(self, action, resource):
        """Check if action is permitted"""
        response = requests.post(
            f"{self.act_base_url}/v1/enforce",
            headers={
                "X-Api-Key": self.act_api_key,
                "Content-Type": "application/json"
            },
            json={
                "requestId": str(uuid4()),
                "capabilityToken": self.act_token,
                "action": action,
                "resourceId": resource,
                "tenantId": "default-tenant",
                "context": {
                    "timestamp": datetime.utcnow().isoformat(),
                    "agentVersion": "2.0"
                }
            }
        )
        
        result = response.json()
        return result["decision"] == "allowed"
    
    def predict(self, user_id, query):
        """Generate recommendation"""
        # Validate access to user profile
        if not self.validate_action_with_act(
            "read", f"api://user_profiles/{user_id}"):
            raise PermissionError("Access to user profile denied")
        
        # Validate access to product catalog
        if not self.validate_action_with_act(
            "query", "api://product_catalog/*"):
            raise PermissionError("Access to catalog denied")
        
        # Safe to proceed - call your custom model
        user_profile = self.fetch_user_profile(user_id)
        recommendations = self.model.predict(
            query=query,
            user_profile=user_profile
        )
        
        return recommendations
    
    def fetch_user_profile(self, user_id):
        # Fetch user data (already validated above)
        return {"id": user_id, "preferences": [...]}

# Usage
agent = CustomAgentWithACT(
    act_api_key="your_key",
    act_base_url="https://your-act-instance",
    act_token="token_from_step_4"
)

recommendations = agent.predict(
    user_id="user_456",
    query="recommend products"
)

Step 6: Deploy and Monitor

# Your custom agent now enforces ACT policies
# All resource access is validated and logged
# Monitor audit logs for insights into agent behavior

Example Use Cases

✅ Recommendation Engine

Policy: Read user profiles and product catalog

actions: ["read", "query"]
resources: ["api://user_profiles/*", "api://products/*"]
constraints: { 
  maxQueriesPerMinute: 1000,
  noPersonalData: false
}

✅ Fraud Detection Agent

Policy: Read transactions, flag suspicious activity

actions: ["read", "analyze", "alert"]
resources: ["api://transactions/*", "api://alerts/*"]
constraints: { 
  readOnly: false,
  realTimeProcessing: true
}

✅ Content Moderation System

Policy: Analyze content, update moderation status

actions: ["read", "analyze", "update"]
resources: ["api://content/*", "api://moderation/*"]
constraints: { 
  maxContentPerMinute: 100,
  requiresReview: false
}

Best Practices

Validate before every API call: Make ACT calls synchronous and fail-safe. If ACT is unavailable, deny by default.
Add context to validation: Include relevant context (user ID, timestamp, etc.) to help with audit logs
Implement token rotation: Refresh ACT tokens regularly (hourly) to limit blast radius
Use request IDs: Generate unique IDs for each validation request to track across logs
Monitor ACT latency: Cache validation results briefly to avoid performance impact
Review constraints regularly: Audit your policies quarterly to ensure they match your threat model

Troubleshooting

ACT validation calls are slow

Solution: ACT calls should be fast (<100ms), but you can implement local caching of decisions. Consider batching validations if your agent makes many decisions in parallel.

Agent behavior inconsistent with policy

Solution: Check your validation logic. Ensure you're calling ACT before every resource access. Review audit logs to see which calls were blocked.

Token expiration during long operations

Solution: Implement automatic token refresh. Issue new tokens hourly or before long-running operations.