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:

agentx demo --audit   # then: agentx audit

03See what it recorded

This screen lists every wrapped tool call: which tool, how many times, and what each call touched. Right now that is the demo run from step 02, our agent and not yours. Wrap one of your own tools in step 04 and its calls land here too.

agentx audit   # grouped by tool

TOOL                   CALLS  SURFACE       ARGUMENTS
-----------------------------------------------------------------------
fetch_invoice_pdf          1  HTTP          url
issue_refund               1  -             amount, currency +2 more
                              largest amount passed: >=1,000
run_sql                    1  DB            db_session, query

2 calls tripped a policy.
1 was stopped while blocking was on; 1 ran because audit was on.

--calls gives one row per call, newest first, with the time. Each row ends with what became of the call: ran, stopped, ran, flagged (it tripped a policy and was let through), or retried (it was stopped, and the agent then got there another way).

agentx audit --calls   # one row per call, newest first

TIME      TOOL                   STATUS       SURFACE ARGUMENTS
2026-08-31
18:00:30  query_orders_db*       ran, flagged DB      sql
18:00:30  write_ticket_note*     ran          FS      contents, path
18:00:30  run_sql*               retried      DB      db_session, query

* 3 rows above written by AgentX's own demo or examples, not by your agent.

Once your own tools are on the screen, each run opens with what is new since you last looked. With more than one agent running, each call also names which one made it.

--limit N and --all set how much you see. --json prints the same data for a program.

--share writes agentx-audit.json: the same data as --json, with your ledger's file path and the trace ids taken out. It prints what is in the file and what is not, so you can check before you send it.

Calls are recorded whether blocking is on or off. Only wrapped tools appear here, so this is not all your agent did.

In CI, --require-calls exits 2 when the ledger holds no calls, so a job where the agent never ran cannot pass as a clean audit. --fail-on-rule-match exits 3 when a recorded call matched a rule you adopted, and names the rule.

agentx audit --require-calls --fail-on-rule-match   # for CI: exit 2 on an empty record, 3 on a rule match

The whole GitHub Actions workflow. Copy it into .github/workflows/, point the "Run the agent" step at your own entry point, and the install line at your own dependency file:

name: agent audit

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - run: pip install "agentx-security-sdk>=0.5.1" -r requirements.txt

      # Your agent, its tools wrapped with @agentx_protect. It writes .agentx.db into whatever
      # directory it runs in, and `audit` below reads the one in the same directory.
      - name: Run the agent
        run: python ./scripts/run_agent.py

      # Exits 2 if the record holds no calls, 3 if a call matched one of your rules, so a run
      # where the agent silently did nothing, or did the thing you wrote a rule against, cannot
      # pass as a clean audit.
      - name: What did the agent do
        run: agentx audit --require-calls --fail-on-rule-match

      # The same data for a program, kept as a build artifact. The step above already decided
      # the job, so this one must not fail it a second time, and must not hide its own failure
      # either. continue-on-error marks the step red and leaves the verdict to the step above.
      - name: Keep the record
        if: always()
        continue-on-error: true
        run: agentx audit --json > agentx-audit.json

      # Without this the file is written into the runner and thrown away with it.
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: agentx-audit
          path: agentx-audit.json

Put it on your agent

04Wrap a tool, then choose how it runs

One decorator on the tool function you want vetted. This is the only code change either choice below needs.

from agentx_sdk import agentx_protect

@agentx_protect(agent_id="crm_worker")
def run_sql(query: str, db=None):
    ...

Want your app to behave exactly as it does today? Watch and record tool calls with 4A. To record and block dangerous calls, go with 4B.

# nothing to set, watching is already on:
python your_agent.py

AGENTX_POSTURE=enforce python your_agent.py  # mac/linux

$env:AGENTX_POSTURE="enforce"; python your_agent.py  # PowerShell

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", posture="enforce")
def run_sql(query: str, db=None):
    return db.execute(query)

# Call the tool, then check the result before you trust it:
out = run_sql(query=agent_query, 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_query = your_llm(out.challenge)
    out = run_sql(query=revised_query, 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.

Put the statement in an argument named for it (query, sql, command, path, url). Text arguments such as notes or body are never read as SQL or shell, so a ticket note that happens to say delete from is not a block.

02Handle a block

Nothing to write. With the enforce posture set (the one line further down this step), when the floor 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. Watching, which is the default, the same call is recorded and forwarded.

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, and the demo pins the enforce posture to show it. Gateway-backed Recover over MCP (richer, model-coached self-heal) is on the roadmap; today the agentx-mcp proxy is your keyless screen, and your protection once you set the posture below.

Claude Code? It writes the entry for you; the command is the same, our proxy first and your server after it:

claude mcp add filesystem -- uvx agentx-mcp npx -y @modelcontextprotocol/server-filesystem /data

Trying it on servers you already use? Every wrapped server records its calls and blocks none of them, so nothing you add can break a server that already works. To make ONE server block, add this beside args in that server's block, with a comma between them, and repeat it per server you want enforcing:

"env": { "AGENTX_POSTURE": "enforce" }

Remove the env line to go back to watching. Every server you did not edit is watching already.

A tool's text arguments (a note, a message, a title) are never read as SQL or shell. The shield reads statements only in arguments named for them (query, command, path, url) or declared so by the server's own schema.

03See what it recorded

This screen lists every wrapped tool call: which tool, how many times, and what each call touched. It reads the servers you wrapped in step 01. The demo is not on it: uvx agentx-mcp --demo runs in a temporary directory of its own and writes nothing here.

uvx agentx-mcp --audit   # grouped by tool

TOOL                   CALLS  SURFACE       ARGUMENTS
-----------------------------------------------------------------------
fetch_invoice_pdf          1  HTTP          url
issue_refund               1  -             amount, currency +2 more
                              largest amount passed: >=1,000
run_sql                    1  DB            db_session, query

2 calls tripped a policy.
1 was stopped while blocking was on; 1 ran because audit was on.

--calls gives one row per call, newest first, with the time. Each row ends with what became of the call: ran, stopped, ran, flagged (it tripped a policy and was let through), or retried (it was stopped, and the agent then got there another way).

uvx agentx-mcp --audit --calls   # one row per call, newest first

TIME      TOOL                   STATUS       SURFACE ARGUMENTS
2026-08-31
18:00:30  query_orders_db*       ran, flagged DB      sql
18:00:30  write_ticket_note*     ran          FS      contents, path
18:00:30  run_sql*               retried      DB      db_session, query

* 3 rows above written by AgentX's own demo or examples, not by your agent.

Once your own tools are on the screen, each run opens with what is new since you last looked. With more than one agent running, each call also names which one made it.

Once a server you wrapped has been called, this screen also says how many tools that server advertises, how many your agent called, and names the ones it never called. Nobody chooses what a third-party server exposes, so a tool your agent could reach and never used is worth a look.

--limit N and --all set how much you see. --json prints the same data for a program.

--share writes agentx-audit.json: the same data as --json, with your ledger's file path and the trace ids taken out. It prints what is in the file and what is not, so you can check before you send it.

Calls are recorded whether blocking is on or off. Only wrapped tools appear here, so this is not all your agent did.

In CI, --require-calls exits 2 when the ledger holds no calls, so a job where the agent never ran cannot pass as a clean audit.

uvx agentx-mcp --audit --require-calls   # for CI: exit 2 on an empty record

04Install 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.

07Close the loop

Every block your agents hit is a chance to teach the firewall. Run agentx review for 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.

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

Changed your mind about one of those answers? agentx review --undo is the way back, and it is the only one. It walks all three things you can decide here: an answer you gave for a whole policy, a detection rule you adopted, and a block you already judged. Adopting arms enforcement, so nothing you do here is a one-way door.

07Close 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.

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.

Changed your mind? uvx agentx-mcp --review --undo takes it back. Over this door that covers the answers you gave for a whole policy and the blocks you already judged. Adopted rules live in your project, in .agentx/rules.json, so removing one means naming that project in the server's env block first: AGENTX_PROJECT_DIR (on Claude Code, ${CLAUDE_PROJECT_DIR}). The screen prints the exact line to use.

Concepts

AgentX blocks a dangerous tool call, then hands your agent coaching so the run recovers. 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 tier ladder above (Shield, Recover, Control) is orthogonal: it sets 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.