Documentation

02See it work

Once the SDK is installed, watch a prompt-injected DROP TABLE get blocked in ten seconds, offline, with no key and no gateway:

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

Then see what audit records, on the same demo. Audit watches every call and blocks nothing, so this run stops nothing and writes down all of it:

agentx demo --audit   # then: agentx audit

03Choose how it runs

Two postures. Audit watches every call and blocks nothing. Enforce stops the dangerous ones.

@agentx_protect(agent_id="crm_worker")
# then run your agent with audit on

@agentx_protect(agent_id="crm_worker")
# enforce is the default: nothing to set

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.

02Handle a block

Nothing to write. When the Shield blocks a tools/call, the proxy returns it to the agent as a coaching tool error, and the agent reads the guidance and self-corrects on its next turn. The run keeps going and the dangerous call never reaches the server.

To watch it happen before you wire your own servers, run the demo. It drives the same proxy your MCP client spawns, against a bundled stub server, and shows a DROP TABLE blocked with coaching and a scoped SELECT allowed through:

uvx agentx-mcp --demo   # no key, no gateway, no Node, no checkout

That coaching is in-band and keyless. Gateway-backed Recover over MCP (richer, model-coached self-heal) is on the roadmap; today the agentx-mcp proxy is your keyless protection.

Trying it on servers you already use?One server's calls can all be recorded and none of them blocked, while every other server you wrapped keeps enforcing. Add this beside argsin that server's block, with a comma between them, and repeat it per server you want in audit:

"env": { "AGENTX_ENFORCEMENT": "audit" }

Then read it back with uvx agentx-mcp --audit, call by call. Remove the env line to enforce.

03Install agentx-mcp

The mcp.json in the door uses uvx, so it needs no install. For a persistent install, get the agentx-mcp command however suits your stack. All three run the same keyless Shield:

With pip or pipx, agentx-mcp lands on your PATH; then set command to agentx-mcp and drop the uvx arg.

06Close the loop

Every block your agents hit is a chance to teach the firewall. Run agentx reviewfor a one-key pass over what got blocked: adopt the safe-path an agent already found, so AgentX coaches straight to it next time, or label a block right or wrong so the org's picture of what's a real threat sharpens. The protection compounds with use instead of staying static.

agentx review   # one key each: adopt a safe-path, or label a block

06Close the loop

Blocks and recoveries pile up as your agents run. Walk them with one key each: adopt a safe path an agent already found, or label a block right or wrong, so the protection gets better at your work instead of staying generic.

uvx agentx-mcp --review   # one key each: adopt a safe-path, or label a block

Works whether or not you installed anything, and reads the store the proxy wrote, wherever your MCP host launched it from.

Concepts

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:

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 in step 04 (Shield, Recover, Control) are orthogonal: they set how much reasoning backs the block, from the keyless floor up to the gateway judge.

CLI reference

The agentx CLI ships with the Python SDK. Every command runs locally; agentx help prints this list.

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.