agentx-security-sdk 0.2.1__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agentx-security-sdk
3
- Version: 0.2.1
3
+ Version: 0.2.2
4
4
  Summary: The self-healing exception handler for autonomous AI agents.
5
5
  Home-page: https://github.com/vdalal/semantic-gateway
6
6
  Author: AgentX Team
@@ -23,29 +23,83 @@ Dynamic: requires-dist
23
23
  Dynamic: requires-python
24
24
  Dynamic: summary
25
25
 
26
- # AgentX Security SDK & Semantic Gateway 🛡️
26
+ # 🛡️ AgentX: The Semantic Firewall for AI Agents
27
27
 
28
- 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.
28
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
29
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
29
30
 
30
- 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.
31
+ 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`.
31
32
 
32
- ## 🚀 Quickstart (Agent Integration)
33
+ **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*.
34
+
35
+ ### 🧠 Don't just block agents. Coach them.
36
+ ```text
37
+ ════════════════════════════════════════════════════════════
38
+ 🛡️ AgentX Session Summary (Trace: 7012938b-4cde-4bea-aac8)
39
+ ════════════════════════════════════════════════════════════
40
+ ⏱️ Uptime: 15.49 seconds
41
+ 🛠️ Tools Monitored: 2
42
+ ────────────────────────────────────────────────────────────
43
+ 🛑 Intercepts: 1 | Cumulative: 34
44
+ 💥 Critical Blocks: 1 | Cumulative: 18
45
+ 🔄 Self-Corrections: 1 | Recovery Rate: 100.0%
46
+ 💰 Tokens Saved: ~1500 | Cumulative: ~51000
47
+ ⏳ Time Saved: ~5s | Cumulative: ~170s
48
+ ════════════════════════════════════════════════════════════
49
+ 🩺 AGENT HEALTH INSIGHT
50
+ ────────────────────────────────────────────────────────────
51
+ ⚠️ Top Offender: 'Database Isolation'
52
+ 💡 Tip: Consider refining your agent's system prompt to avoid this.
53
+
54
+
55
+ 🚀 The 4 Shields (Defense-in-Depth)
56
+ The Inbound Shield (Prompt Injection): Sanitizes inbound user text to prevent cognitive hijacking ("Ignore previous instructions") before the agent reads it.
57
+
58
+ The Logic Shield (Database Guard): Uses AST parsing and Gemini to catch destructive queries (DROP, DELETE) and nudges the agent to write safer SQL.
59
+
60
+ The Network Shield (SSRF Guard): Prevents agents from acting as confused deputies to hit cloud metadata IPs (e.g., 169.254.169.254).
61
+
62
+ The Egress Shield (DLP/PII Scrubber): Dynamically masks PII and API keys on the wire, maintaining clean audit logs without triggering SOC alert fatigue.
63
+
64
+
65
+ ⚡ Quickstart (Time-to-Value < 3 Minutes)
66
+ 1. Install the SDK
67
+ Zero-config integration for your Python agents.
33
68
 
34
- Install the SDK via PyPI:
35
69
  ```bash
36
70
  pip install agentx-security-sdk
37
71
  ```
38
-
39
- 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.
72
+ 2. Wrap your Tools
73
+ 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.
40
74
 
41
75
  ```python
42
76
  from agentx_sdk.decorators import agentx_protect
43
77
 
44
- @agentx_protect(agent_id="agent_prod_01")
78
+ @agentx_protect(agent_id="customer_support_agent")
45
79
  def execute_database_query(query: str):
46
- # Your database logic here
80
+ # Your local logic here
47
81
  return db.execute(query)
82
+ ```
83
+ 3. Spin up the Edge Gateway
84
+ AgentX requires an Edge node to process heuristics and embeddings at sub-millisecond speeds.
85
+
86
+ Clone this repository.
87
+
88
+ Copy .env.example to .env and add your API keys (SUPABASE_URL, SUPABASE_KEY, GEMINI_API_KEY).
89
+
90
+ Boot the gateway:
48
91
 
92
+ ```bash
93
+ docker-compose up -d
94
+ ```
95
+ The gateway is now listening on http://localhost:8000 and mirroring policies from your Control Plane.
96
+
97
+
98
+ 4. Run the Simulation
99
+ Watch the AgentX Gateway coach a rogue agent in real-time.
100
+
101
+ ```bash
102
+ python examples/simulate_agent_sdk.py
49
103
  ```
50
104
 
51
105
  ## 📊 Local Telemetry & Agent Health
@@ -72,6 +126,20 @@ AgentX ships with a built-in, privacy-first SQLite time-series event log (`.agen
72
126
 
73
127
  ```
74
128
 
129
+ ## 🕹️ Human-in-the-Loop (HITL) & Control Plane
130
+ Sometimes, an agent needs to drop a table for a valid business reason.
131
+
132
+ 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.
133
+
134
+ ```bash
135
+ cd ui
136
+ npm install
137
+ npm run dev
138
+
139
+ ## 🤝 Contributing
140
+ 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!
141
+
142
+
75
143
  ## 🏗️ The Architecture (Split-Plane)
76
144
 
77
145
  AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum performance and security for AI-driven enterprise systems.
@@ -89,61 +157,6 @@ AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum perfor
89
157
  * **Zero-Knowledge Intent Extraction:** Prevents malicious prompt injection by translating raw agent logic into a strict schema before policy evaluation.
90
158
  * **Dynamic YAML Policies:** Enforces isolation rules like "Mass Destructive Intent", "Database Isolation", "Network Sandbox (SSRF)", and "Secrets Exfiltration".
91
159
 
92
- ## 🛠️ Getting Started (Backend Deployment)
93
-
94
- If you are deploying your own instance of the Semantic Gateway Control Plane:
95
-
96
- ### Prerequisites
97
-
98
- * Python 3.10+
99
- * Node.js 18+
100
- * [Supabase](https://supabase.com) Account
101
- * [Google AI Studio](https://aistudio.google.com/) API Key (Gemini)
102
-
103
- ### 1. Environment Variables
104
-
105
- Create a `.env` file in the root directory. **Ensure this file is in your `.gitignore` to protect your IP and keys.**
106
-
107
- ```env
108
- SUPABASE_URL=your_supabase_url
109
- SUPABASE_KEY=your_supabase_service_role_key
110
- GEMINI_API_KEY=your_gemini_api_key
111
-
112
- ```
113
-
114
- ### 2. Run the Semantic Firewall (Dockerized)
115
- 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:
116
-
117
- ```bash
118
- cd backend
119
- docker build -t agentx-gateway .
120
- docker run -p 8000:8000 --env-file ../.env agentx-gateway
121
-
122
- ```
123
-
124
- The firewall is now intercepting traffic at http://localhost:8000
125
-
126
- ### 3. Run the Control Plane Dashboard (Vercel/Local)
127
-
128
- Start your Next.js application to view the intercepted incidents.
129
-
130
- ```bash
131
- cd ui
132
- npm install
133
- npm run dev
134
-
135
- ```
136
- Your dashboard is now live at http://localhost:3000
137
-
138
- ### 4. Run the Agent Simulation
139
-
140
- Simulate a rogue agent attempting a destructive action. Watch the firewall intercept it, issue a challenge, and route it to your dashboard.
141
-
142
- ```bash
143
- python examples/simulate_agent_sdk.py
144
-
145
- ```
146
-
147
160
  ## 🔒 Security Posture
148
161
 
149
162
  * **Secret Management:** API keys are never checked into version control. Production variables are managed securely via the Vercel Dashboard.
@@ -24,23 +24,39 @@ def start_secure_session():
24
24
  trace_id_var.set(session_id)
25
25
  return session_id
26
26
 
27
- # --- 1. THE SESSION TRACKER ---
27
+ # --- 1. THE SESSION TRACKER & EXIT SUMMARY ---
28
28
  _session_stats = {
29
29
  "start_time": time.time(),
30
30
  "total_calls": 0,
31
31
  "intercepts": 0,
32
- "critical_blocks": 0
32
+ "critical_blocks": 0,
33
+ "self_corrections": 0,
34
+ "last_call_was_challenge": False # <-- Tracks the cognitive pivot state
33
35
  }
34
36
 
35
- def _print_roi_summary():
37
+ def _print_agentx_summary():
36
38
  """Fires automatically when the developer's script ends or crashes."""
39
+
40
+ # Only print if we actually did something this session to avoid terminal spam
41
+ if _session_stats["total_calls"] == 0 and _session_stats["intercepts"] == 0:
42
+ return
43
+
37
44
  duration = round(time.time() - _session_stats["start_time"], 2)
38
45
  session_tokens = _session_stats["intercepts"] * 1500
39
46
  session_time = _session_stats["intercepts"] * 5
40
47
 
48
+ # Calculate the Hero Metric: Self-Correction Rate
49
+ scr = 0
50
+ if _session_stats["intercepts"] > 0:
51
+ scr = round((_session_stats["self_corrections"] / _session_stats["intercepts"]) * 100, 1)
52
+
41
53
  # Fetch historical data
42
- history = get_lifetime_stats()
43
- if not history:
54
+ try:
55
+ history = get_lifetime_stats()
56
+ if not history:
57
+ raise ValueError("No history")
58
+ except Exception:
59
+ # Fallback if the local DB is fresh or errors out
44
60
  history = {
45
61
  "total_intercepts": _session_stats["intercepts"],
46
62
  "total_critical": _session_stats["critical_blocks"],
@@ -49,30 +65,31 @@ def _print_roi_summary():
49
65
  "top_offender": None
50
66
  }
51
67
 
52
- print("\n" + "═"*50)
68
+ print("\n" + "═"*60)
53
69
  print(f" 🛡️ AgentX Session Summary (Trace: {trace_id_var.get() or 'N/A'})")
54
- print("═"*50)
70
+ print("═"*60)
55
71
  print(f" ⏱️ Uptime: {duration} seconds")
56
72
  print(f" 🛠️ Tools Monitored: {_session_stats['total_calls']}")
57
- print("─"*50)
73
+ print("─"*60)
58
74
 
59
75
  # The Action-Oriented UI
60
76
  print(f" 🛑 Intercepts: {_session_stats['intercepts']} | Cumulative: {history['total_intercepts']}")
61
77
  print(f" 💥 Critical Blocks: {_session_stats['critical_blocks']} | Cumulative: {history['total_critical']}")
62
- print(f" 💰 Tokens Saved: ~{session_tokens} | Cumulative: ~{history['total_tokens']}")
63
- print(f" Time Saved: ~{session_time}m | Cumulative: ~{history['total_time']}m")
78
+ print(f" 🔄 Self-Corrections: {_session_stats['self_corrections']} | Recovery Rate: {scr}%")
79
+ print(f" 💰 Tokens Saved: ~{session_tokens} | Cumulative: ~{history['total_tokens']}")
80
+ print(f" ⏳ Time Saved: ~{session_time}s | Cumulative: ~{history['total_time']}s")
64
81
 
65
82
  # The 5+ Block Threshold for the Health Report
66
- if history['total_intercepts'] >= 5 and history['top_offender']:
67
- print("═"*50)
83
+ if history.get('total_intercepts', 0) >= 5 and history.get('top_offender'):
84
+ print("═"*60)
68
85
  print(" 🩺 AGENT HEALTH INSIGHT")
69
- print("─"*50)
70
- print(f" ⚠️ Top Offender: '{history['top_offender']}'")
71
- print(" 🛠️ Tip: Consider refining your agent's system prompt to avoid this.")
86
+ print("─"*60)
87
+ print(f" ⚠️ Top Offender: '{history['top_offender']}'")
88
+ print(" 💡 Tip: Consider refining your agent's system prompt to avoid this.")
72
89
 
73
- print("═"*50 + "\n")
90
+ print("═"*60 + "\n")
74
91
 
75
- atexit.register(_print_roi_summary)
92
+ atexit.register(_print_agentx_summary)
76
93
  # --------------------------
77
94
 
78
95
  def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None):
@@ -101,6 +118,9 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
101
118
  _session_stats["intercepts"] += 1
102
119
  _session_stats["critical_blocks"] += 1
103
120
 
121
+ # +++ SENSOR: Track that we challenged the agent
122
+ _session_stats["last_call_was_challenge"] = True
123
+
104
124
  mock_policy_id = "POL-SEC-001"
105
125
  mock_policy_name = "Database Isolation"
106
126
 
@@ -115,6 +135,12 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
115
135
  })
116
136
  else:
117
137
  print(f"✅ [AgentX SDK] Intent safe (Mock). Executing '{func.__name__}'.")
138
+
139
+ # +++ SENSOR: Check if this was a successful recovery!
140
+ if _session_stats.get("last_call_was_challenge"):
141
+ _session_stats["self_corrections"] += 1
142
+ _session_stats["last_call_was_challenge"] = False
143
+
118
144
  return func(*args, **kwargs)
119
145
 
120
146
  # =========================================================
@@ -125,7 +151,7 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
125
151
  query=query,
126
152
  chain_of_thought=chain_of_thought,
127
153
  receipt_id=receipt_id,
128
- trace_id=current_trace_id # <--- NEW PARAMETER PASSED TO CLIENT
154
+ trace_id=current_trace_id
129
155
  )
130
156
 
131
157
  status = eval_res.get("status") if isinstance(eval_res, dict) else None
@@ -134,6 +160,9 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
134
160
  if isinstance(eval_res, dict) and eval_res.get("error") == "AgentX Policy Violation":
135
161
  _session_stats["intercepts"] += 1
136
162
 
163
+ # +++ SENSOR: Track that we challenged the agent
164
+ _session_stats["last_call_was_challenge"] = True
165
+
137
166
  actual_policy_id = eval_res.get("policy_id", "POL-UNKNOWN")
138
167
  policy_name = eval_res.get("policy_triggered", "Unknown Policy")
139
168
  challenge_text = eval_res.get("challenge", "Policy violation detected. Please revise your intent.")
@@ -166,15 +195,13 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
166
195
  print(f"\n🚨 [AgentX SDK] Task suspended. Request escalated to Human SOC.")
167
196
  print(f"⏳ [AgentX SDK] Polling for human decision (Receipt: {receipt_id})...")
168
197
 
169
- # Retrieve the API key for the polling requests
170
198
  api_key = os.environ.get("AGENTX_API_KEY")
171
199
  headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
172
200
 
173
201
  # The Polling Loop
174
202
  while True:
175
- time.sleep(3) # Wait 3 seconds between checks
203
+ time.sleep(3)
176
204
  try:
177
- # Check the status endpoint with Auth Headers
178
205
  status_check = requests.get(
179
206
  f"{_client.gateway_url}/v1/status/{receipt_id}",
180
207
  headers=headers
@@ -184,7 +211,8 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
184
211
 
185
212
  if current_status == "APPROVED":
186
213
  print(f"\n✅ [AgentX SDK] Human SOC APPROVED the override!")
187
- # Execute the dangerous function because a human authorized it
214
+ # Reset state, this wasn't a self-correction, human bypassed it.
215
+ _session_stats["last_call_was_challenge"] = False
188
216
  return func(*args, **kwargs)
189
217
 
190
218
  elif current_status == "DENIED":
@@ -194,18 +222,24 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
194
222
  "instruction": "The SOC analyst explicitly denied this action. You must find an alternative path or fail the task."
195
223
  })
196
224
 
197
- # If PENDING or ESCALATED, it just loops again
198
225
  elif status_check.status_code == 401:
199
- print(f"\n❌ [AgentX SDK] Auth Error: Gateway rejected polling request. Check AGENTX_API_KEY.")
226
+ print(f"\n❌ [AgentX SDK] Auth Error: Gateway rejected polling request.")
200
227
  return json.dumps({"error": "Unauthorized Polling"})
201
228
 
202
229
  except Exception as e:
203
230
  print(f"⚠️ Polling error: {e}")
204
231
 
205
232
  # 3. Check for the "Success" path
206
- elif isinstance(eval_res, dict) and eval_res.get("status") == "success":
233
+ elif isinstance(eval_res, dict) and eval_res.get("status") in ["success", "ALLOWED"]:
207
234
  print(f"✅ [AgentX SDK] Intent safe. Executing '{func.__name__}'.")
208
- return eval_res
235
+
236
+ # +++ SENSOR: Check if this was a successful recovery!
237
+ if _session_stats.get("last_call_was_challenge"):
238
+ _session_stats["self_corrections"] += 1
239
+ _session_stats["last_call_was_challenge"] = False
240
+
241
+ # Fix: Actually execute the function instead of returning the Gateway's JSON
242
+ return func(*args, **kwargs)
209
243
 
210
244
  # 4. Handle actual Gateway crashes
211
245
  else:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agentx-security-sdk
3
- Version: 0.2.1
3
+ Version: 0.2.2
4
4
  Summary: The self-healing exception handler for autonomous AI agents.
5
5
  Home-page: https://github.com/vdalal/semantic-gateway
6
6
  Author: AgentX Team
@@ -23,29 +23,83 @@ Dynamic: requires-dist
23
23
  Dynamic: requires-python
24
24
  Dynamic: summary
25
25
 
26
- # AgentX Security SDK & Semantic Gateway 🛡️
26
+ # 🛡️ AgentX: The Semantic Firewall for AI Agents
27
27
 
28
- 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.
28
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
29
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
29
30
 
30
- 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.
31
+ 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`.
31
32
 
32
- ## 🚀 Quickstart (Agent Integration)
33
+ **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*.
34
+
35
+ ### 🧠 Don't just block agents. Coach them.
36
+ ```text
37
+ ════════════════════════════════════════════════════════════
38
+ 🛡️ AgentX Session Summary (Trace: 7012938b-4cde-4bea-aac8)
39
+ ════════════════════════════════════════════════════════════
40
+ ⏱️ Uptime: 15.49 seconds
41
+ 🛠️ Tools Monitored: 2
42
+ ────────────────────────────────────────────────────────────
43
+ 🛑 Intercepts: 1 | Cumulative: 34
44
+ 💥 Critical Blocks: 1 | Cumulative: 18
45
+ 🔄 Self-Corrections: 1 | Recovery Rate: 100.0%
46
+ 💰 Tokens Saved: ~1500 | Cumulative: ~51000
47
+ ⏳ Time Saved: ~5s | Cumulative: ~170s
48
+ ════════════════════════════════════════════════════════════
49
+ 🩺 AGENT HEALTH INSIGHT
50
+ ────────────────────────────────────────────────────────────
51
+ ⚠️ Top Offender: 'Database Isolation'
52
+ 💡 Tip: Consider refining your agent's system prompt to avoid this.
53
+
54
+
55
+ 🚀 The 4 Shields (Defense-in-Depth)
56
+ The Inbound Shield (Prompt Injection): Sanitizes inbound user text to prevent cognitive hijacking ("Ignore previous instructions") before the agent reads it.
57
+
58
+ The Logic Shield (Database Guard): Uses AST parsing and Gemini to catch destructive queries (DROP, DELETE) and nudges the agent to write safer SQL.
59
+
60
+ The Network Shield (SSRF Guard): Prevents agents from acting as confused deputies to hit cloud metadata IPs (e.g., 169.254.169.254).
61
+
62
+ The Egress Shield (DLP/PII Scrubber): Dynamically masks PII and API keys on the wire, maintaining clean audit logs without triggering SOC alert fatigue.
63
+
64
+
65
+ ⚡ Quickstart (Time-to-Value < 3 Minutes)
66
+ 1. Install the SDK
67
+ Zero-config integration for your Python agents.
33
68
 
34
- Install the SDK via PyPI:
35
69
  ```bash
36
70
  pip install agentx-security-sdk
37
71
  ```
38
-
39
- 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.
72
+ 2. Wrap your Tools
73
+ 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.
40
74
 
41
75
  ```python
42
76
  from agentx_sdk.decorators import agentx_protect
43
77
 
44
- @agentx_protect(agent_id="agent_prod_01")
78
+ @agentx_protect(agent_id="customer_support_agent")
45
79
  def execute_database_query(query: str):
46
- # Your database logic here
80
+ # Your local logic here
47
81
  return db.execute(query)
82
+ ```
83
+ 3. Spin up the Edge Gateway
84
+ AgentX requires an Edge node to process heuristics and embeddings at sub-millisecond speeds.
85
+
86
+ Clone this repository.
87
+
88
+ Copy .env.example to .env and add your API keys (SUPABASE_URL, SUPABASE_KEY, GEMINI_API_KEY).
89
+
90
+ Boot the gateway:
48
91
 
92
+ ```bash
93
+ docker-compose up -d
94
+ ```
95
+ The gateway is now listening on http://localhost:8000 and mirroring policies from your Control Plane.
96
+
97
+
98
+ 4. Run the Simulation
99
+ Watch the AgentX Gateway coach a rogue agent in real-time.
100
+
101
+ ```bash
102
+ python examples/simulate_agent_sdk.py
49
103
  ```
50
104
 
51
105
  ## 📊 Local Telemetry & Agent Health
@@ -72,6 +126,20 @@ AgentX ships with a built-in, privacy-first SQLite time-series event log (`.agen
72
126
 
73
127
  ```
74
128
 
129
+ ## 🕹️ Human-in-the-Loop (HITL) & Control Plane
130
+ Sometimes, an agent needs to drop a table for a valid business reason.
131
+
132
+ 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.
133
+
134
+ ```bash
135
+ cd ui
136
+ npm install
137
+ npm run dev
138
+
139
+ ## 🤝 Contributing
140
+ 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!
141
+
142
+
75
143
  ## 🏗️ The Architecture (Split-Plane)
76
144
 
77
145
  AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum performance and security for AI-driven enterprise systems.
@@ -89,61 +157,6 @@ AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum perfor
89
157
  * **Zero-Knowledge Intent Extraction:** Prevents malicious prompt injection by translating raw agent logic into a strict schema before policy evaluation.
90
158
  * **Dynamic YAML Policies:** Enforces isolation rules like "Mass Destructive Intent", "Database Isolation", "Network Sandbox (SSRF)", and "Secrets Exfiltration".
91
159
 
92
- ## 🛠️ Getting Started (Backend Deployment)
93
-
94
- If you are deploying your own instance of the Semantic Gateway Control Plane:
95
-
96
- ### Prerequisites
97
-
98
- * Python 3.10+
99
- * Node.js 18+
100
- * [Supabase](https://supabase.com) Account
101
- * [Google AI Studio](https://aistudio.google.com/) API Key (Gemini)
102
-
103
- ### 1. Environment Variables
104
-
105
- Create a `.env` file in the root directory. **Ensure this file is in your `.gitignore` to protect your IP and keys.**
106
-
107
- ```env
108
- SUPABASE_URL=your_supabase_url
109
- SUPABASE_KEY=your_supabase_service_role_key
110
- GEMINI_API_KEY=your_gemini_api_key
111
-
112
- ```
113
-
114
- ### 2. Run the Semantic Firewall (Dockerized)
115
- 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:
116
-
117
- ```bash
118
- cd backend
119
- docker build -t agentx-gateway .
120
- docker run -p 8000:8000 --env-file ../.env agentx-gateway
121
-
122
- ```
123
-
124
- The firewall is now intercepting traffic at http://localhost:8000
125
-
126
- ### 3. Run the Control Plane Dashboard (Vercel/Local)
127
-
128
- Start your Next.js application to view the intercepted incidents.
129
-
130
- ```bash
131
- cd ui
132
- npm install
133
- npm run dev
134
-
135
- ```
136
- Your dashboard is now live at http://localhost:3000
137
-
138
- ### 4. Run the Agent Simulation
139
-
140
- Simulate a rogue agent attempting a destructive action. Watch the firewall intercept it, issue a challenge, and route it to your dashboard.
141
-
142
- ```bash
143
- python examples/simulate_agent_sdk.py
144
-
145
- ```
146
-
147
160
  ## 🔒 Security Posture
148
161
 
149
162
  * **Secret Management:** API keys are never checked into version control. Production variables are managed securely via the Vercel Dashboard.
@@ -9,7 +9,7 @@ if os.path.exists("README.md"):
9
9
 
10
10
  setup(
11
11
  name="agentx-security-sdk",
12
- version="0.2.1",
12
+ version="0.2.2",
13
13
  author="AgentX Team",
14
14
  author_email="founders@agentx.com",
15
15
  description="The self-healing exception handler for autonomous AI agents.",