Documentation

AgentX is a runtime firewall for AI agents. It blocks catastrophic tool calls (DROP TABLE, secret exfiltration, SSRF) before they execute, then coaches the agent to a safe path so the run finishes. Pick your stack and start keyless in 30 seconds.

Choose your stack

01Install

Public on PyPI, no account and no key, nothing leaves your machine. The Python SDK is agentx-security-sdk (which also ships the agentx-mcp proxy); MCP-only users can install the agentx-mcp package on its own (MIT, open source).

pip install agentx-security-sdk

Then see it work in ten seconds, offline, with no key and no gateway:

agentx demo   # watch a prompt-injected DROP TABLE get blocked

02Protect a Python tool

Wrap any tool function with @agentx_protect. The reflection engine inspects the signature automatically, serializes the risky inputs, and ignores connection objects like a SQLAlchemy session. No boilerplate, no payload schemas. The keyless Shield blocks the blatant catastrophic calls right in process RAM, before they run. Pick your framework:

from agentx_sdk import agentx_protect

@agentx_protect(agent_id="crm")
def call_api(url):
    return requests.get(url)

# the agent picks the url at runtime:
call_api("http://169.254.169.254/")

It is a plain decorator, so it composes with your framework: put @agentx_protecton the underlying tool function, under LangChain's @tool, a CrewAI tool, or a LlamaIndex FunctionTool. Async tools (LangGraph, AutoGen) are supported, and strictly-typed tools raise instead of returning, so Pydantic or LangChain return-validation never crashes (see Handle a block).

Want coverage without wrapping each tool? The agentx-mcp proxy screens every tools/call at one point, so there is no decorator to forget. Framework-native middleware for the SDK path is on the roadmap.

Don't own the tool's Python? Running a non-Python agent? Wrap any MCP server with agentx-mcp and every tools/call is screened by the same keyless Shield before it runs. No decorator, no key, no code change. One line in your mcp.json (Claude Code, Cursor, or any MCP client):

{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": [
        "agentx-mcp", "npx", "-y",
        "@modelcontextprotocol/server-filesystem",
        "/data"
      ]
    }
  }
}

agentx-mcp spawns the real server and relays the protocol untouched, intercepting only tool calls. A blocked call comes back to the agent as a coaching tool error it can self-correct on, so the run keeps going and the dangerous call never reaches the server.

Get the agentx-mcp command however suits your stack. All three run the same keyless Shield:

The config above uses uvx, so it needs no install. Prefer a persistent install? pip or pipx put agentx-mcp on your PATH; then set command to agentx-mcp and drop the uvx arg.

03Handle a block

A blocked call returns an AgentXBlock (strictly-typed tools raise AgentXSecurityBlock instead). Check it with is_block(), feed its .challenge back to your LLM to revise the action, then retry, threading receipt_id so the recovery is tied to the original incident.

from agentx_sdk import agentx_protect, is_block

@agentx_protect(agent_id="crm_worker")
def dispatch_update(client_id: str, notes: str, db=None):
    query = f"UPDATE clients SET notes = '{notes}' WHERE id = '{client_id}'"
    return db.execute(query)

# Call the tool, then check the result before you trust it:
out = dispatch_update(client_id="c-99401", notes=agent_notes, db=session)

if is_block(out):
    # out.challenge says what was unsafe and how to fix it. Hand it to your
    # LLM to revise, then call the SAME tool again, passing receipt_id so the
    # retry is tied to the original block.
    revised_notes = your_llm(out.challenge)
    out = dispatch_update(
        client_id="c-99401",
        notes=revised_notes,
        db=session,
        receipt_id=out.receipt_id,
    )

# out is now the real return value of your tool, safely.

out.policy names the policy that fired; out.safe_path is the preferred alternative when a policy names one (else None). Doing this with your own LLM is the manual version of Recover; the gateway automates it.

04Shield → Recover → Control

ShieldFree · Local

pip install, then one decorator on a Python tool or one line in your mcp.json to wrap any MCP server. The keyless Shield blocks the blatant catastrophic calls (DROP TABLE, secret exfiltration, SSRF) before they run, and coaches your agent to self-correct. No LLM key, no signup, runs on your machine.

block + coach

pip install agentx-security-sdk

RecoverGateway + Gemini key

The gateway judge catches what keyword rules can't see, writes the safe path when your policy carries none, and runs the coach-and-retry for you, so your agent finishes the task instead of dying on a 403. Needs the gateway and your own Gemini key.

guide + continue

Get the gateway

Control+ Team

Connect the cloud control plane for team human-in-the-loop and SOC approvals, shared dashboards, and a fleet-wide audit trail. Central oversight for when one machine isn't the whole story.

review + govern

Request Access

Recover and Control run through the gateway. The keyless Shield blocks AND coaches your agent to self-correct; Recover adds the gateway judge that catches what keywords miss and runs the coach-and-retry for you, so it needs both the gateway and a Gemini key.

05Concepts

AgentX blocks a dangerous tool call, then hands your agent coaching so the run recovers instead of dead-ending. A few terms tie it together:

Policy	A built-in floor: a trigger plus the coaching it delivers on a block. `agentx policies` lists them (e.g. "Mass Destructive Intent").
Trigger	The deterministic detector that fires the block (a blocked intent or a structural signature). Runs keyless and offline, no LLM.
Coaching	What your agent receives on a block: what went wrong plus a safe path to try. This is what lets the run recover instead of dead-ending on a 403.
Challenge	The coaching message your agent actually reads (the text of the coaching).
Safe path	The concrete alternative the coaching names (e.g. "add a WHERE clause, or snapshot first").

Rewrite any policy's coaching by name, keyless, with agentx customize. It applies on both the @agentx_protect decorator and the agentx-mcp proxy. The tiers above (Shield, Recover, Control) are orthogonal: they set how much reasoning backs the block, from the keyless floor up to the gateway judge.

06CLI reference

Every command runs locally. agentx help prints this list.

agentx demo	Ten-second offline 'aha': watch a DROP TABLE get blocked (no key, no gateway)
agentx share	Turn your most recent block into a postable card + share draft
agentx status	Local protection stats + armed policies (live view needs the gateway)
agentx insights	Review your agents' learned safe-paths (numbered) for adoption
agentx adopt	Adopt a learned safe-path so AgentX coaches your agents to it
agentx policies	List the customizable floor policies + your active coaching (--check to validate)
agentx customize	Customize a floor policy's coaching by name, keyless (--text or --edit)
agentx pull	Pull your org's policy config from the control plane
agentx push	Contribute abstract threat signals to shared immunity (opt-in)
agentx sync	pull + push

Customize the coaching, keyless. A block hands your agent a coaching message (what went wrong plus a safe path), and that wording drives whether it recovers. Run agentx policies to see the built-in floor policies and the coaching each ships with, then override one by name with agentx customize "Mass Destructive Intent" --text "..." (or --edit to open your editor on the current text). It saves to ./.agentx/overrides.json and applies keyless on both the @agentx_protect decorator and the agentx-mcp proxy.

07Run the gateway

The gateway adds the full deterministic floor (AST parsing, the SSRF normalizer, the whole failure catalog), coached recovery, and team HITL/SOC. The image ships with design-partner access.

docker compose up -d   # the full floor + Recover run here

Today the gateway backs the SDK (decorator) integration; gateway protection over MCP is on the roadmap, so for MCP servers the keyless agentx-mcp proxy is your protection now. The gateway is free and runs locally: get it self-serve. Questions or something broke? Join the Discord.