GALXEE AI CfAM API Reference
Complete reference for the Containment for Agentic Middleware SDK. Version 1.0.0.
Overview
CfAM (Containment for Agentic Middleware) is a security middleware layer that wraps AI agent execution with policy enforcement, rate limiting, payload inspection, and tamper-evident audit logging.
It is model-agnostic — works with OpenAI, Anthropic, Google Gemini, and any LLM-based reasoning system. It requires no infrastructure changes and adds less than 2ms of latency overhead.
Installation
Python
pip install containai-middleware
Or download the SDK file directly and place it in your project:
# Download containai_middleware.py and place in your project root\nfrom containai_middleware import AgentMiddleware
Node.js / TypeScript
npm install containai-middleware\n# or\nyarn add containai-middleware
Quick Start
Three lines to full containment:
from containai_middleware import AgentMiddleware
# 1. Initialize with your policy
agent = AgentMiddleware(
policy="strict",
allowed_domains=["api.openai.com"],
max_requests_per_minute=60
)
# 2. Decorate your agent function
@agent.secure
async def run_agent(task: str) -> str:
# Your agent logic runs here — fully contained
response = await my_ai_agent.execute(task)
return response
# 3. Call it normally
result = await run_agent("Summarize this document")The @agent.secure decorator wraps your function with a new ephemeral session on each call, enforces all policy checks, and wipes context after execution.
AgentMiddleware
The main entry point. Accepts a policy string or a ContainmentPolicy object.
policystr | ContainmentPolicyPolicy mode or full policy object. Default: "strict"allowed_domainsList[str]Domains the agent may contact. Supports wildcards (*.example.com). Default: []blocked_domainsList[str]Domains always blocked, regardless of mode. Default: []allowed_methodsList[str]HTTP methods the agent may use. Default: ["GET","POST"]max_requests_per_minuteintSliding window rate limit. Default: 60max_payload_bytesintMaximum request payload size (1 MB default). Default: 1048576sandboxboolEnable sandboxed execution context. Default: Trueaudit_logboolEnable tamper-evident audit logging. Default: Trueephemeral_contextboolWipe context between sessions. Default: Trueagent_idstr | NoneOptional agent identifier for audit logs. Default: autocheck_request()
Manually evaluate a request before making it. Use this for fine-grained control inside your agent logic.
verdict = await agent.check_request(
url="https://api.openai.com/v1/chat/completions",
method="POST",
payload={"model": "gpt-4", "messages": [...]}
)
if not verdict.allowed:
raise PermissionError(f"[{verdict.status}] {verdict.reason}")
# Safe to proceed
response = await http_client.post(url, json=payload)allowedboolTrue if the action is permitted.statusVerdictStatusALLOWED | BLOCKED | RATE_LIMITED | POLICY_VIOLATION | SANDBOX_VIOLATIONreasonstrHuman-readable explanation of the verdict.eventAuditEventThe audit event recorded for this evaluation.Audit Log
Every action is recorded in a tamper-evident, hash-chained audit log. Each event includes a chain_hash that links it to all previous events.
# Get all audit events
events = agent.get_audit_log()
for event in events:
print(f"[{event['verdict']}] {event['method']} {event['target']} — {event['latency_ms']}ms")
# Verify the audit chain has not been tampered with
is_intact = agent.verify_audit_integrity()
print(f"Audit chain integrity: {'✓ verified' if is_intact else '✗ TAMPERED'}")event_idUUID for this event.session_idUUID for the current agent session.agent_idIdentifier of the agent.action_typehttp_request | database_query | file_system | subprocess | ...targetThe URL or resource targeted.methodHTTP method (GET, POST, etc.).verdictALLOWED | BLOCKED | RATE_LIMITED | POLICY_VIOLATIONreasonExplanation of the verdict.latency_msTime taken to evaluate the request (ms).payload_bytesSize of the request payload.timestampISO 8601 UTC timestamp.chain_hashSHA-256 hash linking this event to the chain.Policy Modes
"strict"Block everything not explicitly in allowed_domains. Recommended for production and sensitive deployments.
"permissive"Allow everything not in blocked_domains. Useful for development and testing.
"audit"Allow all actions but log everything. Use for observability without enforcement.
TypeScript
import { AgentMiddleware, Policy, ContainmentVerdict } from 'containai-middleware';
const policy: Policy = {
mode: 'strict',
allowedDomains: ['api.openai.com', 'api.anthropic.com'],
maxRequestsPerMinute: 60,
auditLog: true,
sandbox: true,
ephemeralContext: true,
};
const agent = new AgentMiddleware(policy);
// Wrap your agent
const secureAgent = agent.secure(async (task: string): Promise<string> => {
// Manual check example
const verdict: ContainmentVerdict = await agent.checkRequest(
'https://api.openai.com/v1/chat/completions',
'POST',
{ model: 'gpt-4', messages: [{ role: 'user', content: task }] }
);
if (!verdict.allowed) {
throw new Error(`[CfAM] ${verdict.status}: ${verdict.reason}`);
}
return await myAiAgent.execute(task);
});
// Verify audit integrity
const intact: boolean = agent.verifyAuditIntegrity();Architecture
CfAM consists of three independently verifiable components that together enforce containment at the execution layer:
Policy Engine
Cryptographically signed capability manifests define what an agent is permitted to do. Boundary violations are detected before execution. Policies are HMAC-SHA256 signed to prevent tampering.
Containment Layer
Executes agent-requested API calls, telemetry, and database communications in ephemeral sandboxes. Validates every proposed action before execution. Enforces rate limits, domain allowlists, method restrictions, and payload size limits.
Audit Chain
Every action is recorded in a hash-chained, append-only audit log. Each event includes a SHA-256 chain hash linking it to all previous events, making tampering detectable. The chain can be verified at any time with verify_audit_integrity().
Success Metrics
CfAM is measured against these production-readiness criteria: