agentx-security-sdk 0.2.5

The self-healing exception handler for autonomous AI agents.

🛡️ AgentX: The Semantic Firewall for AI Agents

LLM Agents are brilliant, but they are incredibly brittle. They will drop your production database, leak AWS keys, and fall victim to prompt injections. Traditional firewalls just crash the agent by returning a 403 Forbidden.

AgentX is different. It is a neuro-symbolic edge gateway that intercepts dangerous tool calls, blocks them, and returns a Socratic Challenge back to the agent's context window—forcing the agent to rethink its strategy and self-correct without crashing.

🧠 Don't just block agents. Coach them.

The 5 Pillars of Agentic Security

AgentX is built on a "Reasoning Engine" architecture that treats AI agents as autonomous employees rather than static scripts. We secure them through five core pillars:

1. Cognitive Interception: We intercept tool calls to compare the agent's stated intent (Chain of Thought) against its actual deterministic action.
2. Socratic Nudging: Instead of crashing the agent with a 403 Forbidden, we issue a Socratic Challenge to guide them to a safe, desired end-goal.
3. Human-in-the-Loop (HITL): If the gateway cannot judge intent safely, the agent is paused (202 Accepted) and sent to a SOC Sandbox for human evaluation.
4. Dynamic Policy Refresh: We collect novel intents at the edge, allowing DevSecOps to draft new policies that sync globally to all containers in 3 seconds.
5. Immutable Audit Trails: We maintain a chronological ledger of agent thoughts, actions, and corrections for future learning and compliance.

════════════════════════════════════════════════════════════
 🛡️  AgentX Session Summary (Trace: 7012938b-4cde-4bea-aac8)
════════════════════════════════════════════════════════════
 ⏱️  Uptime:                15.49 seconds
 🛠️  Tools Monitored:       2
────────────────────────────────────────────────────────────
 🛑 Intercepts:            1   |  Cumulative: 34
 💥 Critical Blocks:       1   |  Cumulative: 18
 🔄 Self-Corrections:      1   |  Recovery Rate: 100.0%
 💰 Tokens Saved:         ~1500  |  Cumulative: ~51000
 ⏳ Time Saved:           ~5s    |  Cumulative: ~170s
════════════════════════════════════════════════════════════
 🩺 AGENT HEALTH INSIGHT
────────────────────────────────────────────────────────────
 ⚠️  Top Offender: 'Database Isolation'
 💡 Tip: Consider refining your agent's system prompt to avoid this.


🚀 The 4 Shields (Defense-in-Depth)
The Inbound Shield (Prompt Injection): Sanitizes inbound user text to prevent cognitive hijacking ("Ignore previous instructions") before the agent reads it.

The Logic Shield (Database Guard): Uses AST parsing and Gemini to catch destructive queries (DROP, DELETE) and nudges the agent to write safer SQL.

The Network Shield (SSRF Guard): Prevents agents from acting as confused deputies to hit cloud metadata IPs (e.g., 169.254.169.254).

The Egress Shield (DLP/PII Scrubber): Dynamically masks PII and API keys on the wire, maintaining clean audit logs without triggering SOC alert fatigue.


⚡ Quickstart (Time-to-Value < 3 Minutes)
1. Install the SDK
Zero-config integration for your Python agents.

```bash
pip install agentx-security-sdk

2. Wrap your Tools Add the @agentx_protect decorator to any function your LangChain, AutoGen, or custom ReAct agent uses. AgentX operates out-of-band, adding zero latency to safe calls.

from agentx_sdk.decorators import agentx_protect

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

3. Spin up the Edge Gateway AgentX requires an Edge node to process heuristics and embeddings at sub-millisecond speeds.

Clone this repository.

Copy .env.example to .env and add your API keys (SUPABASE_URL, SUPABASE_KEY, GEMINI_API_KEY).

Boot the gateway:

docker-compose up -d

The gateway is now listening on http://localhost:8000 and mirroring policies from your Control Plane.

4. Run the Simulation Watch the AgentX Gateway coach a rogue agent in real-time.

python examples/simulate_agent_sdk.py

📊 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.
══════════════════════════════════════════════════

📦 Try the Developer Demos Inside the examples/ folder, you will find three standalone scripts proving the AgentX Reasoning Layer:

• 01_self_healing_agent.py: Watch AgentX catch a hallucination and coach the agent to self-correct (Saving tokens and uptime).
• 02_cognitive_intent_block.py: Watch the Semantic Firewall catch malicious intent even when the raw syntax is perfectly safe.
• 03_human_escalation.py: See how an agent safely pauses execution and pings a SOC analyst for approval using a 202 Accepted queue.

🕹️ Human-in-the-Loop (HITL) & Control Plane

Sometimes, an agent needs to drop a table for a valid business reason.

AgentX features a Next.js Control Plane Dashboard. If an agent requests an escalation, the SDK securely pauses local execution and polls the Edge Gateway. A human SOC analyst can click "Approve" or "Deny" in the UI, and the Python execution loop will automatically resume.

cd ui
npm install
npm run dev

## 🤝 Contributing
We are actively looking for design partners. If you are building autonomous agents in production and are terrified of what they might do, open an issue or reach out!


## 🏗️ 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 Cloud Policies**: Enforces isolation rules instantly via a Supabase-backed Control Plane that syncs to edge caches in 3 seconds.

## 🔒 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:** Moved neuro-symbolic evaluation entirely into the Data Plane container to eliminate agent runtime bypasses. (Completed)
* **✅ Zero-Knowledge Hard Split-Plane:** Mathematically enforced VPC telemetry isolation via localized metric stripping. (Completed)
* **⬜ Local LRU Neural Cache:** Deduplicate vector embeddings to minimize edge latency down to sub-1ms. (Next up)
* **⬜ Core DevX Inspection Engine:** Expose a unified CLI interface for localized policy and metric auditing. (Active)
* **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.