agentx-security-sdk 0.2.11

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 hard 403 Forbidden exception, killing the run completely and wasting compute tokens.

AgentX is different. It is an intelligent, neuro-symbolic edge reasoning engine and local vector shield that intercepts dangerous tool calls, filters threats, and returns a structural Socratic Challenge back to the agent's context window. This forces the agent to rethink its strategy, fix parameters, and self-correct without crashing your application. And it instantly distributes novel threat signatures across a global Shared Immunity Ledger.

🧠 Don't just block agents. Coach them and Immunize your network.

---

🏗️ Split-Plane Architecture

AgentX relies on a decoupled, split-plane hybrid architecture to balance sub-millisecond latency with deep cognitive reasoning:

• The Edge SDK (agentx_sdk): A zero-config Python package instrumenting sensitive tool calls via reflective code signatures.
• The Data Plane (Neuro-Symbolic Reasoning Engine): A high-performance Python FastAPI service (the "Wedge"). Handles Abstract Syntax Tree (AST) evaluation, zero-day threat trapping, and local execution of the Shared Immunity Network via a strict Layer 0 -> Layer 1 -> Layer 2 funnel.
• The Control Plane (Dashboard): A Next.js application listening on port 3000. Connects to a Supabase-backed real-time ledger to provide an executive command console for tracking corporate ROI metrics, analyzing agent Chain of Thought (CoT) loops, and promoting newly discovered policy vectors.

---

⚡ 1. Quickstart

AgentX requires zero changes to your underlying agentic logic, custom tools, or payload schemas. The SDK dynamically inspects function signatures at runtime using an auto-reflective ingestion engine.

Step 1: Install the SDK

pip install agentx-security-sdk

Step 2: Decorate Sensitive Tool Operations

Attach the @agentx_protect decorator over any high-risk system tool. The SDK automatically serializes parameters and enforces the evaluation wedge:

# ✅ MODERN REFLECTIVE IMPORTS (No boilerplate functions required)
from agentx_sdk.decorators import agentx_protect

@agentx_protect(agent_id="frictionless_enterprise_worker")
def dispatch_crm_update(client_id: str, profile_notes: str, db_session=None):
    """
    AgentX automatically inspects string elements, ignores connection objects
    like 'db_session', and evaluates intents out-of-prompt natively in RAM.
    """
    print(f"Updating records for {client_id}")

Step 3: Configure Environment Boundry Flags

Copy .env.example to .env and add your API keys.

AGENTX_API_KEY=agentx_sk_test_XXXXX
NEXT_PUBLIC_GATEWAY_URL=http://localhost:8000
AGENTX_ALLOW_PAYLOAD_SYNC=true
AGENTX_BYPASS_LOCAL_SHIELD=false
GEMINI_API_KEY=gemini_sk_XXXXX

Step 4: Spin up the Edge Reasoning Engine

Boot your local data plane wedge proxy middleware and your frontend dashboard console node simultaneously:

docker-compose up -d

OR

uvicorn backend/gateway:app --host "0.0.0.0" --port=8000

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

---

Step 5: Run a Live Frictionless Run Pass

Watch the AgentX SDK utilize its auto-reflective ingestion core to catch a nested SQL injection attempt hidden inside helper variables, bypass internal SQLAlchemy network pointers, and trigger an edge block without throwing a system crash exception:

python examples/08_frictionless_agent_protection.py```
```text


🕹️ Console Session Output Logs:

```text
========================================================================
🤖 AGENTX DEMO 08: ZERO-CONFIGURATION ENTERPRISE TOOL PROTECTION
========================================================================
Scenario: An engineer wraps an existing corporate function with AgentX.
The SDK automatically parses inputs via Python signature reflection.

🔄 --- Agent Execution Step ---
Agent Attempting Call: dispatch_crm_update(client_id='CLI-99401', profile_notes='...')
Injected Input Payload: 'Customer requested normal update. Retain account historical state; DROP TABLE users;'

🛡️ [AgentX SDK] Intercepting tool call to 'dispatch_crm_update' and active_stats = 0...
⚡ [LOCAL VECTOR SHIELD] Fast-Path Intercept Engaged! (Similarity Score Check: OVERRIDE_MATCHED)
🛑 [LOCAL BLOCK] Policy 'Mass Destructive Intent' breached locally. Returning offline instruction block string.

🛑 [AGENTX REASONING ENGINE] Request Intercepted & Blocked!
-> The reflection engine successfully captured the nested SQL payload.
-> The SQLAlchemy session context object was safely ignored.

🔒 Enterprise data assets protected via zero-configuration injection monitoring.
========================================================================

════════════════════════════════════════════════════════════
 🛡️  AgentX Session Summary (Trace: bbfda7a1-8e1b-41dd-8c59-b784a3bbdf6d)
════════════════════════════════════════════════════════════
 ⏱️  Uptime:                0.27 seconds
 🛠️  Tools Monitored:       2
────────────────────────────────────────────────────────────
 🛑 Intercepts:            1   |  Cumulative: 3
 💥 Critical Blocks:       1   |  Cumulative: 1
 🚨 Human Escalations:     0   |  Cumulative: 0
 🔄 Self-Corrections:      1   |  Cumulative: 0
 📈 Recovery Rate:         100.0%
 💰 Tokens Saved:          ~1500
 ⏳ Time Saved:            ~5s
════════════════════════════════════════════════════════════

📊 Executive Control Plane Telemetry When your agent script finishes or exits, local telemetry logs (.agentx.db) sync securely back to the central database layout. Open your browser workspace to http://localhost:3000/dashboard to inspect your real-time performance summary matrix:

+-----------------------------------------------------------------------------------+
|                                 SOC SANDBOX                                       |
+-----------------------------------------------------------------------------------+
|  [Task Reliability Rate]  [Tokens Saved]  [Compute Capital]  [DevOps Time Saved]  |
|          85.4%             1.3M tkn        $6.54             24.0 hrs        |
|   📈 Socratic Recovery      ⚡ JIT Optimized    💰 Spend Saved    ⏱️ Reclaimed SWE |
+-----------------------------------------------------------------------------------+

Advanced ROI Mappings:

• Task Reliability Rate: Compiles the percentage of threatened agent execution steps that reached full completion via automated self-healing loops without throwing an exception.
• Tokens Saved (M): Tracks total prompt overhead prevented by keeping static security texts out of system prompts, combined with preventing infinite "retry storm" hallucinations using Layer 0 Circuit Breakers.
• Compute Capital Retained: Translates aggregate saved token matrices down to corporate infrastructure runway dollars using model API baselines.
• Engineering Time Saved: Calculates cumulative wall-clock SWE debugging hours saved by allowing the engine to handle compliance out-of-band (~$75.00/hr).

---

🧠 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:

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, we issue a Socratic Challenge to guide them to a safe, desired end-goal.
3. Shared Immunity Network: When an agent attempts a novel zero-day attack, the exact signature is extracted and instantly distributed to all local Edge nodes globally for O(1) interception.
4. Human-in-the-Loop (HITL): If an agent pulls the "Andon Cord" (requests help), the system suspends the execution thread (202 Accepted) and parks it in the SOC Sandbox for human approval.
5. Circuit Breakers: If an agent enters an infinite hallucination loop, AgentX hard-locks the runtime after 3 strikes to prevent massive LLM token billing overages.

---

🚀 The 4 Shields (Defense-in-Depth)

1. The Inbound Shield (Prompt Injection): Sanitizes inbound user text to prevent cognitive hijacking ("Ignore previous instructions") before the agent reads it.

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

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

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

---

📊 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 other Developer Demos Inside the examples/ folder, you will find a few 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.
• And many more...

---

🕹️ 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 Reasoning Engine. 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

---

## 🏗️ 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, Pro, or higher (configurable via an environment variable) 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.

---

🚀 Future Roadmap & Milestones
✅ 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)

✅ Zero-Config Reflection Engine: Eliminated manual query and CoT boilerplate writing using dynamic signature parameters compilation hooks. (Completed)

✅ Local Vector Shield Engine: Hydrated compiled .bin weight matrices right inside process RAM to support offline sub-millisecond validations. (Future)

⬜ Local LRU Neural Cache: Deduplicate vector embeddings to minimize edge latency down to sub-1ms. (Next Up)

⬜ Containerized Multi-Region Edge Cluster: Standardize container blueprints for automated high-availability deployments onto AWS ECS and Render clusters. (Future)


🤝 Contributing & Support
We are actively partnering with engineering groups building production-grade autonomous agent systems. If you are tracking high-concurrency tool execution lines and are terrified of what your agent loops might drop or execute, open an issue card or reach out directly to join our design partner circle!