agentx-security-sdk 0.2.0

The self-healing exception handler for autonomous AI agents.

AgentX Security SDK & Semantic Gateway 🛡️

AgentX is a production-grade security layer and semantic firewall designed specifically for autonomous AI agents. It intercepts, evaluates, and conditionally blocks agent-driven actions based on intent, policy violation, and neuro-symbolic evaluation.

Instead of failing silently or requiring immediate human intervention, the AgentX Edge SDK issues a Socratic Challenge, forcing the agent to reason about its actions and self-correct into a safe operation.

🚀 Quickstart (Agent Integration)

Install the SDK via PyPI:

pip install agentx-security-sdk

Wrap any sensitive tool or function with the @agentx_protect decorator. AgentX operates at the edge, adding zero latency to your cloud operations until an anomaly is detected.

from agentx_sdk.decorators import agentx_protect

@agentx_protect(agent_id="agent_prod_01")
def execute_database_query(query: str):
    # Your database logic here
    return db.execute(query)

📊 Local Telemetry & Agent Health

AgentX ships with a built-in, privacy-first SQLite time-series event log (.agentx.db). It tracks every interception locally. When your agent script finishes or crashes, AgentX automatically prints a comprehensive Session Summary and Lifetime ROI dashboard:

══════════════════════════════════════════════════
 🛡️  AgentX Session Summary
══════════════════════════════════════════════════
 ⏱️  Uptime:                9.17 seconds
 🛠️  Tools Monitored:       2
──────────────────────────────────────────────────
 🛑 Intercepts:            1   |  Cumulative: 5
 💥 Critical Blocks:       1   |  Cumulative: 5
 💰 Tokens Saved:      ~1500   |  Cumulative: ~7500
 ⏳ Time Saved:        ~5m     |  Cumulative: ~25m
══════════════════════════════════════════════════
 🩺 AGENT HEALTH INSIGHT
──────────────────────────────────────────────────
 ⚠️ Top Offender: 'Database Isolation'
 🛠️  Tip: Consider refining your agent's system prompt to avoid this.
══════════════════════════════════════════════════

🏗️ The Architecture (Split-Plane)

AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum performance and security for AI-driven enterprise systems.

• The Edge SDK (AgentX): The lightweight Python package that instruments agent tools and triggers local Socratic self-healing.
• The Data Plane (Semantic Firewall): A Python FastAPI middleware (the "Wedge") that intercepts raw HTTP/SQL payloads before they hit the database.
• The Control Plane (Dashboard): A Next.js application (deployed via Vercel) that allows human reviewers to monitor intercepted agent traffic, review chains of thought, and approve or deny parked requests.
• The Shared Brain: Supabase acts as the central state manager. Both the Control Plane and Data Plane synchronize via Supabase, decoupling the network architecture and allowing asynchronous state polling.
• The Evaluator: Google's Gemini 2.5 Flash is used to translate an agent's Chain of Thought (CoT) into a zero-knowledge taxonomy to evaluate intent against YAML-defined enterprise policies.

✨ Key Features & Built-in Policies

• Automated Socratic Self-Healing: Intercepts dangerous tool calls and challenges the agent to revise its strategy.
• Fast Pass Heuristic Traps: Instantly intercepts structurally dangerous queries (e.g., DROP TABLE, DELETE) with minimal latency.
• Zero-Knowledge Intent Extraction: Prevents malicious prompt injection by translating raw agent logic into a strict schema before policy evaluation.
• Dynamic YAML Policies: Enforces isolation rules like "Mass Destructive Intent", "Database Isolation", "Network Sandbox (SSRF)", and "Secrets Exfiltration".

🛠️ Getting Started (Backend Deployment)

If you are deploying your own instance of the Semantic Gateway Control Plane:

Prerequisites

• Python 3.10+
• Node.js 18+
• Supabase Account
• Google AI Studio API Key (Gemini)

1. Environment Variables

Create a .env file in the root directory. Ensure this file is in your .gitignore to protect your IP and keys.

SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_service_role_key
GEMINI_API_KEY=your_gemini_api_key

2. Run the Semantic Firewall (Dockerized)

The Data Plane (Wedge) is fully containerized for maximum reliability. Make sure your .env is configured in the root directory, then build and run the backend:

cd backend
docker build -t agentx-gateway .
docker run -p 8000:8000 --env-file ../.env agentx-gateway

The firewall is now intercepting traffic at http://localhost:8000

3. Run the Control Plane Dashboard (Vercel/Local)

Start your Next.js application to view the intercepted incidents.

cd ui
npm install
npm run dev

Your dashboard is now live at http://localhost:3000

4. Run the Agent Simulation

Simulate a rogue agent attempting a destructive action. Watch the firewall intercept it, issue a challenge, and route it to your dashboard.

python examples/simulate_agent_sdk.py

🔒 Security Posture

• Secret Management: API keys are never checked into version control. Production variables are managed securely via the Vercel Dashboard.
• History Scrubbing: This repository has been scrubbed of legacy keys using git-filter-repo.
• Private IP: Repository is private to protect proprietary evaluation prompts and architecture.

📈 Roadmap

• Trust Boundary Shift: Move the neuro-symbolic evaluation entirely behind the Data Plane to prevent agent manipulation.
• Dynamic Policy Engine: Shift YAML configurations directly into Supabase for instant Control Plane sync.
• Dockerization: Containerize the Data Plane for deployment to AWS ECS / Render for persistent, low-latency edge interception.
• Multi-Tenancy: Implement Supabase Row Level Security (RLS) for multi-org deployments.