Guardrails
Keep your agent inside your rules once it touches your customers' money and records. New here? Get started first.
Check that a write really happened
Your agent moves a contact to "customer" in your CRM. The API answers ok, nothing changed, and the agent tells the sales team it's done. verify reads the record back after the tool has run:
@agentx_protect(agent_id="crm",
verify=lambda args, result: crm.get(args["contact_id"])["stage"] == args["stage"])
def update_contact(contact_id, stage):
return crm.update(contact_id, stage)const updateContact = agentxProtect(updateContactTool, {
name: "update_contact",
verify: async (args, result) => (await crm.get(args.contactId)).stage === args.stage,
});Return True when the change is there. Anything else counts as not confirmed. args is the call's arguments by name, and result is what the tool returned.
When the tool returns an id, check by the id:
@agentx_protect(agent_id="billing",
verify=lambda args, result: stripe.Refund.retrieve(result["id"]).status in ("pending", "succeeded"))
def issue_refund(charge_id, amount):
return stripe.Refund.create(charge=charge_id, amount=amount)const issueRefund = agentxProtect(issueRefundTool, {
name: "issue_refund",
verify: async (args, result) => ["pending", "succeeded"].includes((await stripe.refunds.retrieve(result.id)).status),
});When it isn't confirmed, the agent gets this instead of the tool's result, and you get a line on stderr:
⚠️ [AgentX Unconfirmed] 'update_contact' ran, but reading it back did not show the change. Do not report this as done. Do not repeat the call until you have checked the current state. Tell the user it is unconfirmed.agentx status and agentx audit count these by tool.
It needs no key. It also works while you're watching, so it's the one option that changes what a watched call returns. A tool with a strict return type, such as -> dict, raises AgentXUnconfirmedError instead.
When your own code calls the function, not a model, give it a return type like that, or check is_unconfirmed(result): an untyped one hands your code the message in place of its result.
What it won't catch:
- An agent that says done without calling the tool.
- A tool that raises an error, including a timeout where the write did land.
- A slow write. It reads as not confirmed, so wait inside
verify, and give your read a timeout, becauseverifyhas none of its own.
If verify itself raises an error, the agent is told the result is unknown.
Watch or block, and handling a block
Want your app to behave exactly as it does today? Watch and record tool calls. To record and block dangerous calls, enforce.
Nothing is blocked. Your agent behaves exactly as it does today. This is what an install with no AgentX key does, with nothing to set. Every call is still screened and written down, so read it back with agentx audit.
With a key, set AGENTX_POSTURE=audit, or posture="audit" on one tool, to watch.
To block one dangerous tool while the rest keep watching, put posture="enforce" in the decorator. It stays until you delete that argument, and it beats the shell setting either way.
# with no key, watching is already on:
python your_agent.pyThe dangerous call never runs. It comes back carrying the coaching your agent retries on, so the run finishes instead of failing. This is the step you take once the catches look right to you. A blocked call comes back as a value, not an error. Check it with is_block() below, or your code will use the block object as if it were your tool's return value.
AGENTX_POSTURE=enforce python your_agent.py # mac/linux$env:AGENTX_POSTURE="enforce"; python your_agent.py # PowerShellA blocked call returns an AgentXBlock (strictly-typed tools raise AgentXSecurityBlock instead). Check it with is_block(), feed str(out) back to your LLM to revise the action, then retry. Pass its receipt_id back: a gateway ties the recovery to the original incident by it. With no key, the receipt names the block's own row in your ledger (local- and its number), and a narrower retry of the same tool, made in the same thread or task as the block, counts as the recovery without it.
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):
# str(out) says what was unsafe and the safe path to take (out.challenge
# alone is only the first half). Hand it to your LLM to revise, then call
# the SAME tool again, passing receipt_id (a gateway reads it).
revised_query = your_llm(str(out))
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 not read as SQL or shell, so a ticket note that happens to say delete from is not a block. The exception: on a tool named for what it runs, such as run_sql, with no argument named for its statement, every text argument is read.
What a blocked call looks like to your agent
Nothing to write. With the enforce posture set (step 04 on /docs), 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.
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.
A tool's text arguments (a note, a message, a title) are not read as SQL or shell. The shield reads statements in arguments named for them (query, command, path, url) or declared so by the server's own schema. If none is, it reads every text argument of a tool named for what it runs, such as run_sql.
Blocking, held calls and the reviewer's file
To block TypeScript tools, wrap them with agentxProtect and set AGENTX_API_KEY (and AGENTX_GATEWAY_URL for a gateway that is not on this machine): the gateway checks each call before it runs. If it cannot answer, the call runs unchecked unless AGENTX_FAIL_MODE=closed. A blocked action never executes, and your agent gets the same coaching to recover that the Python decorator delivers.
When the gateway holds a call for a person, answer it from your terminal. Your answer is sent with AGENTX_ADMIN_KEY from your shell when your gateway has one, so the agent cannot approve its own call. With a hosted key, we email the address that asked for the key when a call is held, at most once every 5 minutes while others wait. A gateway you run can post the same notice to Slack, or any URL you set as AGENTX_HOLD_WEBHOOK_URL. On the hosted gateway your agent's key cannot answer its own holds: the email carries a 10-character code, and whoever reads that address signs in at agentx-core.com/app with it to answer. That holds only while your agent cannot read that inbox: an agent with access to that email account could read the code and sign in itself. A rule change sent with the agent's key waits there for that person too, and so does the choice of whether the key's calls are only watched or enforced. Starting with one key? Signed in, you can let the key answer its own held calls on the Settings tab, as before: its rule changes then apply at once, and your agent can approve what is held for it too, so a hold is a pause for you, not a lock. Watch only or enforce stays with the signed-in person either way. Enforcing stops only calls that go through AgentX, not a process that removes AgentX from its code or calls your systems directly.
npx @agentx-core/security-sdk holds # the calls waiting for you
npx @agentx-core/security-sdk holds approve <receipt> # or denyFor your customer's security reviewer, write the file your gateway builds: the rules it checked every call against and the calls it stopped or held.
npx @agentx-core/security-sdk evidence # writes agentx-evidence-<date>.json hereHand the reviewer the file
Your customer's security reviewer will ask what your agent can reach and what was stopped. Write down the sites each agent may reach in .agentx/allowlist.json, in your project:
{"version": 1, "agents": {"crm_worker": {"hosts": ["api.stripe.com"]}}}A call to a site off the list is flagged and still runs while the tool watches, and is stopped before it runs with enforce on. The check reads web addresses that start with a scheme such as https://, so a bare host name, or a call with no such address, is not limited by the list. Then write the file:
agentx evidence # writes agentx-evidence-<date>.json hereIt holds the rules in force and any you switched off, the calls stopped or flagged (the latest 500, each with its time, agent, tool and rule, and the site it was addressed to where one was recorded), each agent's allowlist, and the sites recorded for allowed calls. On some tools a site passed in an argument not named for a web address, such as notify(webhook=...), is not recorded in either place; the allowlist still checks it. It leaves out the calls' own text. It is written on your machine and sent nowhere; read it before you send it, since it names your agents, tools and sites.
Anyone who can write the project's .agentx folder can change the rules, your agent included if it can write files, and nothing in the file records who did. Commit the allowlist and git records each change.
With a key, hand over what your gateway enforced instead: the rules it checked every call against and the calls it stopped or held, for every agent using that key.
agentx evidence --gateway # the file your gateway buildsEverything the record shows
This screen lists every wrapped tool call: which tool, how many times, and what each call touched. To see it before you wrap anything, run it on our demo. Audit watches every call and blocks nothing:
agentx demo --audit # then: agentx auditagentx audit # grouped by toolA sample, shortened. Your tools and numbers will differ:
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
1 call tripped a policy.
1 ran because nothing was blocking at the time.--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), retried (stopped here; the agent retried it narrower, and that ran), or one of three that did not run: held (held for a person, who did not approve it), not run (AgentX could not get a verdict for it), or halted (AgentX stopped it as a runaway loop). The words and their meanings are the CLI's own legend.
agentx audit --calls # one row per call, newest firstA sample, shortened. Your tools and numbers will differ:
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 matchThe 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
This screen lists every wrapped tool call: which tool, how many times, and what each call touched. It reads the servers you wrapped. 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 toolA sample, shortened. Your tools and numbers will differ:
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
1 call tripped a policy.
1 ran because nothing was blocking at the time.--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), retried (stopped here; the agent retried it narrower, and that ran), or one of three that did not run: held (held for a person, who did not approve it), not run (AgentX could not get a verdict for it), or halted (AgentX stopped it as a runaway loop). The words and their meanings are the CLI's own legend.
uvx agentx-mcp --audit --calls # one row per call, newest firstA sample, shortened. Your tools and numbers will differ:
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 recordFrom the folder your agent runs in, see which tools it called, how many times, what each one touched, which wrapped tools it never reached for, and what is new since you last looked:
npx @agentx-core/security-sdk audit # grouped by toolA sample, shortened. Your tools and numbers will differ:
4 calls across 3 tools since 2026-09-14 15:09
4 tools wrapped. 3 called. 1 never ran.
TOOL CALLS SURFACE ARGUMENTS
-----------------------------------------------------------------------
runSql 2 DB limit, sql
refund 1 - amount, currency, order_id
largest amount passed: ≥100,000
sendEmail 1 - body, to
NEW SINCE YOU LAST LOOKED
sendEmail first time we have seen this toolThe last block is one line per change since the previous read, and absent when nothing changed. A repeat run that does exactly what the last one did prints nothing there.
npx @agentx-core/security-sdk audit --calls # one row per call, newest first--json prints the same data for a program, always complete, with the exit code carrying the CI verdict below.
The record holds tool and argument names, no values. Only wrapped tools appear.
In CI, fail the job when there was nothing to read, so a run where the agent never ran cannot pass as a clean audit:
npx @agentx-core/security-sdk@^0.2.0 audit --require-calls # exits 2 on an empty recordThe whole GitHub Actions job, with the record kept as a build artifact, is in the package README on npm.
To watch a dangerous call get stopped and coached, in our playground:
Open the playgroundInstall agentx-mcp
The mcp.json on /docs 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 take the first agentx-mcp out of args.
Watch → Recover → Control
One decorator on a Python tool, one line in your mcp.json, or one line around a TypeScript tool. Python and MCP check every call against the keyless rules (DROP TABLE, secret exfiltration, SSRF), Python also against a site allowlist per agent, and write down what they find; TypeScript writes down every call. Nothing is blocked until you set AGENTX_POSTURE=enforce (Python and MCP). agentx evidence writes the file for your customer's security team. No LLM key, no signup.
record + report
The gateway adds more rules and the checks a keyword match can't do, and tracks session state: budget ceilings and no-progress loop breaking that a single stateless call can't see. Its judge catches what keyword rules can't, 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. Use our hosted gateway with a free key, or run your own with your own Gemini key. An install with an AGENTX_API_KEY set enforces by default: what Watch wrote down, Recover stops. Set AGENTX_POSTURE=audit any time you want it watching instead.
guide + continue
Get the gatewayYour team's rules, set once. Write a rule, and Claude Code asks first on every teammate's machine. Change it on the website and every machine follows within minutes. Approve or deny your agents' calls from the page, and hand a customer's security team one file listing every rule.
review + govern
Start freeOne line in your mcp.json wraps any local MCP server. It screens every tool call against the keyless floor (DROP TABLE, secret exfiltration, SSRF) and writes down what it finds, and out of the box it blocks nothing. Set AGENTX_POSTURE=enforce in that server's env and the same floor stops those calls and coaches your agent to self-correct. No LLM key, no signup, runs on your machine.
record + report
The gateway adds more rules and the checks a keyword match can't do, and tracks session state: budget ceilings and no-progress loop breaking that a single stateless call can't see. Its judge catches what keyword rules can't, 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. Use our hosted gateway with a free key, or run your own with your own Gemini key. An install with an AGENTX_API_KEY set enforces by default: what Watch wrote down, Recover stops. Set AGENTX_POSTURE=audit any time you want it watching instead.
guide + continue
Get the gatewayYour team's rules, set once. Write a rule, and Claude Code asks first on every teammate's machine. Change it on the website and every machine follows within minutes. Approve or deny your agents' calls from the page, and hand a customer's security team one file listing every rule.
review + govern
Start freeRecover and Control run through the gateway. The keyless Watch rung screens every call and writes down what it finds, and blocks nothing until you ask it to; Recover adds more rules and the checks a keyword match can't do, session state (budget ceilings, no-progress loop breaking), and a judge that catches what keywords miss and runs the coach-and-retry for you, so it needs a gateway: ours, or your own with a Gemini key.
If the gateway cannot answer (it is down, slow or returns an error), the call runs: the SDK's own checks still screen it, and it says on stderr that the gateway did not check it. AGENTX_FAIL_MODE=closed refuses the call instead; it has no effect while the SDK only watches.
A call counts as a payment when it has an argument named amount, or ending in _amount (not a min_, max_, lower_ or upper_ bound; nested objects too), and something says it is money: a currency argument beside it, a value marked as money such as "$250", or a tool or action name that moves money, such as refund, pay or transfer. A call whose text says it moves money, such as "transfer $50 to the vendor", counts too, and a team money rule names its own argument. The gateway holds one at or above the money limit for a person: $10 by default, or your money rule's number.
A payment under the money limit can wait for a person too: when payments to the same recipient in the last 24 hours reach the limit; when the same call, with the same arguments, comes twice within 10 minutes, such as a retry after a timeout; or when an argument named order_id, invoice_id, payment_id, charge_id or transaction_id (orderId counts too) has the same value as in another call to the same tool in the last 24 hours, whatever else changed, such as a refund for order 4417 retried the next morning. A retry of the same payment (the same id and amount, or the same call within 10 minutes) while it waits for a person takes its place, so one approval pays once; the earlier call never runs. When a payment a person denied comes again (the same id within 24 hours, or the same call within 10 minutes), the held call says so, in the holds list and on agentx-core.com/app.
Watch is where MCP sits today, and the whole rung is yours with no key. Recover and Control run through the gateway, which does not cover MCP traffic yet, so those two apply to Python and TypeScript tools you write rather than to your MCP servers.
npm install, then one line around your tools: agentxWatchAll({ ... }). Every call is written down on your machine (tool and argument names, no values), and `npx @agentx-core/security-sdk audit` prints what your agent did. Nothing is blocked. No key, no signup.
record + report
The gateway adds more rules and the checks a keyword match can't do, and tracks session state: budget ceilings and no-progress loop breaking that a single stateless call can't see. Its judge catches what keyword rules can't, 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. Use our hosted gateway with a free key, or run your own with your own Gemini key. An install with an AGENTX_API_KEY set enforces by default: what Watch wrote down, Recover stops. Set AGENTX_POSTURE=audit any time you want it watching instead.
guide + continue
Get the gatewayYour team's rules, set once. Write a rule, and Claude Code asks first on every teammate's machine. Change it on the website and every machine follows within minutes. Approve or deny your agents' calls from the page, and hand a customer's security team one file listing every rule.
review + govern
Start freeRecover and Control run through the gateway. Watch records what your agent did and blocks nothing; enforcement starts at Recover, where more rules, the checks a keyword match can't do, and session state (budget ceilings, no-progress loop breaking) check each call, backed by a judge that catches what keyword rules miss.
If the gateway cannot answer, the call runs with no checks, and the SDK says so on stderr. AGENTX_FAIL_MODE=closed refuses the call instead; it has no effect while the SDK only watches.
A call counts as a payment when it has an argument named amount, or ending in _amount (not a min_, max_, lower_ or upper_ bound; nested objects too), and something says it is money: a currency argument beside it, a value marked as money such as "$250", or a tool or action name that moves money, such as refund, pay or transfer. A call whose text says it moves money, such as "transfer $50 to the vendor", counts too, and a team money rule names its own argument. The gateway holds one at or above the money limit for a person: $10 by default, or your money rule's number.
To set that number for a tool, add a money rule on the website (agentx-core.com/app, Rules tab) or with the Python package's CLI: agentx rule add --tool issue_refund --argument amount --currency USD --hold-at 250, then agentx rule push.
A payment under the money limit can wait for a person too: when payments to the same recipient in the last 24 hours reach the limit; when the same call, with the same arguments, comes twice within 10 minutes, such as a retry after a timeout; or when an argument named order_id, invoice_id, payment_id, charge_id or transaction_id (orderId counts too) has the same value as in another call to the same tool in the last 24 hours, whatever else changed, such as a refund for order 4417 retried the next morning. A retry of the same payment (the same id and amount, or the same call within 10 minutes) while it waits for a person takes its place, so one approval pays once; the earlier call never runs. When a payment a person denied comes again (the same id within 24 hours, or the same call within 10 minutes), the held call says so, in the holds list and on agentx-core.com/app.
Run the gateway
The gateway adds more rules and the checks a keyword match can't do, coached recovery, and team review and approval before a risky action runs.
Worth knowing before you run this: it will not carry your MCP traffic. Run it for Python tools you write yourself, or skip it for now. The files it needs are at agentx-core.com/gateway.
Use ours. The hosted gateway is for trying AgentX: do not send production credentials or other people's personal data through it. For real customer data, run your own gateway. Get a free key at agentx-core.com/gateway, with nothing to run, then:
1. Save the key in your project's
.envfile. Create the file next to the code that starts your agent if you do not have one, and add.envto your.gitignoreso the key is never committed.# AgentX hosted gateway. The key is shown once; AgentX keeps only a hash of it. AGENTX_API_KEY=<your key from agentx-core.com/gateway> AGENTX_GATEWAY_URL=<the gateway URL shown with your key>2. Install, and load the file in your app. AgentX reads the key from your app's environment, not from the file, so your app has to load it. Skip the second part if your app already calls
load_dotenv().pip install agentx-security-sdk python-dotenv# At the top of the file that starts your agent, # before any tool runs: from dotenv import load_dotenv load_dotenv()3. Check it, from the same folder, with the Python your agent runs on: the first line on macOS and Linux, the second on Windows. If your agent runs in a virtual environment, activate it first. It should print
AgentX key loaded. If it printsAgentX key NOT loaded, check that.envis in this folder and holds the key. Thenagentx statusshows your hosted account and the model calls your key has used today. If it shows a local status the first time, run it again: the hosted gateway may still be waking up.python -c "from dotenv import load_dotenv; load_dotenv(); import os; k = os.environ.get('AGENTX_API_KEY', ''); u = os.environ.get('AGENTX_GATEWAY_URL', ''); print('AgentX key loaded' if k.startswith('agentx_sk_h_') and u.startswith('http') else 'AgentX key NOT loaded' if not k else 'AgentX key looks wrong: check the key and URL you saved when you signed up')"py -c "from dotenv import load_dotenv; load_dotenv(); import os; k = os.environ.get('AGENTX_API_KEY', ''); u = os.environ.get('AGENTX_GATEWAY_URL', ''); print('AgentX key loaded' if k.startswith('agentx_sk_h_') and u.startswith('http') else 'AgentX key NOT loaded' if not k else 'AgentX key looks wrong: check the key and URL you saved when you signed up')"4. Put
@agentx_protect(agent_id="my_agent")on the tools your agent calls. With the key set they block by default, and a blocked call comes back to your agent with the safe way to do it. If your own code uses what a tool returns, check it withis_block()first: a blocked call returns a block, not your tool's result. How to protect a tool5. See it stop a call. Save this as
agentx_check.pyin the same folder and run it with the same Python. It is safe:run_shellnever runs the command, it only returns a sentence.from dotenv import load_dotenv load_dotenv() from agentx_sdk import agentx_protect @agentx_protect(agent_id="my_agent") def run_shell(command): return "This ran, so AgentX did not stop it." print(run_shell("rm -rf /"))- A line ending in
(your gateway)means it worked. - A line ending in
(local check, no LLM)means the gateway gave no verdict. Check the key and URL you saved. This ranmeans it did not find your key. Check that.envis in this folder.
- A line ending in
6. Open agentx-core.com/app with your key. That is where you answer a call waiting for a person. For a security review, it shows the rules in force, the last 500 calls that were stopped or held, and the sites recorded for allowed calls. Download the file and attach it to the review.
Using TypeScript? Do step 1, then install the package below and start your agent with
node --env-file=.env(Node 20.6 or later). Steps 2 to 5 are for Python. Step 6 is the same.npm install @agentx-core/security-sdkWrap your tools with
agentxProtectAll, as below. A tool is an object with anexecutefunction, and a Vercel AI SDKtool()is one. A plain function cannot be wrapped. To see it stop a call, save this asagentx_check.mjsand run the command under it.Stopped by AgentX.means it worked.This ranmeans it found no key or the gateway did not answer, and the lines under it say which. An error naming your key means the gateway refused it, so check the key you saved.import { agentxProtectAll, isBlock } from "@agentx-core/security-sdk"; const tools = agentxProtectAll( { run_shell: { execute: async ({ command }) => "This ran, so AgentX did not stop it." } }, { agentId: "my_agent" }, ); const result = await tools.run_shell.execute({ command: "rm -rf /" }); console.log(isBlock(result) ? "Stopped by AgentX." : result);node --env-file=.env agentx_check.mjs- Team rules you keep on one machine need no key. To share them with your team, use the key with agentx rule push or on the website. MCP servers through agentx-mcp run on your machine without a key, and do not use it yet.
Or run your own, with Docker and your own Gemini key. Get the files at agentx-core.com/gateway, then:
Use ours. The hosted gateway is for trying AgentX: do not send production credentials or other people's personal data through it. For real customer data, run your own gateway. Get a free key at agentx-core.com/gateway, save the two lines it gives you in your project's .env, add .env to your .gitignore, and start your agent with node --env-file=.env (Node 20.6 or later), so the key reaches your agent's environment. Tools wrapped with agentxProtect are then checked by our gateway.
Or run your own, with Docker and your own Gemini key. Get the files at agentx-core.com/gateway, then:
docker compose up -d # the full floor + Recover run hereThen connect your agent. Set these where it runs. Without the key, it never calls this gateway.
AGENTX_API_KEY=agentx_sk_local_sandbox
AGENTX_GATEWAY_URL=http://127.0.0.1:8000Set them in your shell, or put them in your agent's own .env, not the gateway's, and load it: load_dotenv() in Python, node --env-file=.env in TypeScript. If you set your own AGENTX_API_KEY in the gateway's .env, use that one instead.
Traffic starts flowing through it once your tools are wrapped with agentxProtect.
Gateway protection over MCP is on the roadmap, so the keyless agentx-mcp proxy stays your protection for MCP servers today.
Both are free: get a hosted key or the download. Questions or something broke? Join the Discord.
What you add when you want more. Extra rules and the checks a keyword match can't do, coached recovery that finishes the run, and team review before a risky action runs.
The Python decorator and the agentx-mcp proxy run the keyless check first, and the TypeScript SDK watches and records, all with no key and nothing but counts leaving your machine. The gateway adds more rules and Recover: use ours with a free key and nothing to run, with your team's rules set in one place on the website, or run your own with your own Gemini key. Over MCP it is on the roadmap.
Teach it from your blocks
Every block your agents hit is a chance to teach AgentX. 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 blockChanged 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.
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 blockWorks 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. With agentx-mcp 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.
Every option and command
Concepts
AgentX blocks a dangerous tool call, then hands your agent coaching so the run recovers. 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, so the run recovers. |
| Challenge | The first half of the coaching: what was unsafe. str(block) gives both halves, with the safe path. |
| Safe path | The concrete alternative the coaching names (e.g. "give a condition that leaves the rest untouched"). |
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 (Watch, Recover, Control) is orthogonal: it sets how much reasoning backs the block, from the keyless floor up to the gateway judge.
Pin one tool
A per-tool posture beats the AGENTX_POSTURE env var for that one tool and stays until you delete the argument, so it works in both directions. Pin "enforce" on the one tool you want blocking while the rest watch. Pin "audit" on the one tool that keeps tripping a rule wrongly, so it goes on running while everything else enforces.
# one tool blocks while the rest watch
@agentx_protect(agent_id="crm_worker", posture="enforce")
def dispatch_crm_update(client_id, profile_notes, db_session=None):
...
# or the reverse: one tool keeps running while the rest enforce
@agentx_protect(agent_id="crm_worker", posture="audit")
def dispatch_crm_update(client_id, profile_notes, db_session=None):
...Decorator options
Everything @agentx_protect takes. Only agent_id is required.
| agent_id | Required. Names the agent on every record, and picks its own site list in .agentx/allowlist.json. |
| extract_query_func | A function given the call's arguments that returns the text AgentX checks, for a command in an argument named something else, such as q. Default: the arguments named for what they carry (sql, command, path, url and the like); if none is, every text argument of a tool named for what it runs. |
| extract_cot_func | A function given the call's arguments that returns the agent's reasoning for it, sent to the gateway's judge when you have a key. Default: none. |
| action | With a key, tells the gateway what kind of action the tool takes, such as "fetch_url". Default: a call whose text starts with a URL is read as one; otherwise the gateway decides. |
| budget_pool_id | With a key, tools that share one id share one spend budget. Default: the AGENTX_BUDGET_POOL_ID env var, else no pooling. |
| enforcement | The older name for posture. Still accepted, with a warning; if both disagree, blocking wins. |
| posture | "audit" watches: the call runs and what your rules would stop is recorded. "enforce" blocks. Beats AGENTX_POSTURE for this tool. Default: watching without a key, blocking with one. |
| returns_sensitive | New. True treats the prose this tool returns as sensitive (text of 20 characters or more, more than one word; not status words, dates or ids), for data only you know is private (notes, contracts). Default: False, and values are judged by their shape and field name. See Sensitive data leaving below. |
| sends_out | New. True treats this tool as sending data out of your company, for a tool whose name and arguments do not say so (a helpdesk or CRM client). Default: False, and calls are judged by where they go and by their name. |
| verify | New. verify(args, result) reads the change back after the tool returns. args is the call's arguments by name, with the defaults it left out filled in. result is what the tool returned. It runs only when the tool returned and the call was not stopped. Exactly True confirms. On an async tool it may be async. See Check that a write really happened, above. Default: none. |
Sensitive data leaving
Within one run, AgentX remembers the sensitive values your protected tools returned: emails, phone numbers, US social security numbers, card numbers, AWS keys, private keys and GitHub tokens; values under customer-data fields such as address or billing_address and secret fields such as password (a field ending in key or token, such as api_key, counts when its value looks like a key: 16 characters or more, no spaces, letters mixed with digits or symbols); and the prose a tool marked returns_sensitive=True returns. A later protected call that sends one of them out is stopped, or recorded while you are watching, with or without a key.
A call sends out when it names a host or a recipient outside your company, when its name says so (send, post, upload, email, publish, notify, transfer, push, export), or when it is marked sends_out=True. A value that appears only where the call is addressed, such as to= or a URL's host, does not count: emailing a customer at their own address is the job. The value itself in a call's content is stopped wherever it goes, its owner included, so the stop tells the agent to leave it out or refer to it without it (the last four digits of a card). Inside the company means a private or local address (localhost, private IP ranges, names ending .internal, .local, .corp, .lan, .svc); every public name counts as outside, your company's own domains included, so a stop on one of them is a call to look at rather than a leak by itself. The values stay in your process's memory for the run. The local record keeps the kind of value and the two tool names, never the value. Not caught: data that is reworded, summarised or encoded before it leaves.
@agentx_protect(agent_id="support")
def read_customer(customer_id):
... # returns the customer's email, card and address
@agentx_protect(agent_id="support", sends_out=True)
def create_ticket(summary):
... # files a ticket in an outside helpdesk
read_customer(42)
create_ticket("Card 4242 4242 4242 4242 was declined")
# watching: it runs, and the record notes it would have been stopped
# blocking: it is stopped, and the agent is told which tool returned the cardTeam rules
Correcting your coding agent about the same thing again? Turn the correction into a rule. Before any shell command that contains every phrase you gave, Claude Code asks you first and shows your reason.
agentx rule add "run_suites.py" --why "the suites run once, at the end, with my go-ahead"
agentx rule listThe rule is written to .agentx/team-rules.json with who added it (your git name) and when. Commit the file, and teammates who have AgentX's check installed (agentx hook install) get the same rule. agentx rule list shows each rule and what it did; agentx rule remove ID takes one out. Add --tool NAME to match calls to that tool instead of shell commands. Nothing is written without a person at the terminal, and a shell command that changes the team rules is asked about too.
An SDK agent's call is checked by a gateway, which holds a matching call for a person to answer with agentx holds (with a hosted key, also on agentx-core.com/app). With a hosted key, we email the address that asked for the key when a call is held, at most once every 5 minutes while others wait. A gateway you run can post the same notice to Slack, or any URL you set as AGENTX_HOLD_WEBHOOK_URL. On the hosted gateway your agent's key cannot answer its own holds: the email carries a 10-character code, and whoever reads that address signs in at agentx-core.com/app with it to answer. That holds only while your agent cannot read that inbox: an agent with access to that email account could read the code and sign in itself. A rule change sent with the agent's key waits there for that person too, and so does the choice of whether the key's calls are only watched or enforced. Starting with one key? Signed in, you can let the key answer its own held calls on the Settings tab, as before: its rule changes then apply at once, and your agent can approve what is held for it too, so a hold is a pause for you, not a lock. Watch only or enforce stays with the signed-in person either way. Enforcing stops only calls that go through AgentX, not a process that removes AgentX from its code or calls your systems directly. If your gateway lists an admin key in AGENTX_ADMIN_KEYS, set it as AGENTX_ADMIN_KEY in your own shell, not the agent's, so the agent cannot answer its own hold. Where nobody can answer a hold, such as a gateway you share with other teams and no admin key for your key, the gateway stops the call instead and says why. The hosted gateway holds it, and you answer at agentx-core.com/app. The SDK on its own does not check team rules: the agent needs AGENTX_API_KEY and a gateway. Name the agent's own tool in the rule (--tool run_shell), since shell means Claude Code's and Codex's shell. A gateway you run from the project reads the file; for the hosted gateway, or any other gateway your AGENTX_API_KEY reaches (gateway 2026.10.26.2 or later), send the rules with agentx rule push, and agentx rule list says whether the gateway's copy matches the file. On the hosted gateway you can also add, edit, switch off and remove them on the website (agentx-core.com/app, Rules tab).
A rule can also hold a call by a number in it: 50 VMs may be fine on dev and not on production.
agentx rule add --tool provision_instances --argument count --hold-at prod=25 --hold-at dev=500 --why "more than a handful of VMs needs a second look"A call to provision_instances waits for a person when its count is at or above the limit for where the agent runs. That comes from AGENTX_ENVIRONMENT in the agent's process, such as AGENTX_ENVIRONMENT=prod, named as in --hold-at; with none set, or one the rule doesn't list, the lowest limit applies. A call whose count is missing or not a number waits too.
For money, add --currency USD, and --unit cents if the call's amount is in cents (an amount of 2550 is 25.50); --hold-at stays in the currency. The gateway already holds a payment at or above a set amount, $10 on the hosted gateway. A money rule replaces that amount for its tool, higher or lower, unless a limit set on your own gateway is lower. With --currency-field naming the argument that carries the call's currency, a call in another currency waits for a person too.
With --recipient customer_id naming the argument that says who is paid, payments to the same recipient add up. Without it, the gateway looks for one such as to, payee or customer, and adds up the tool's payments together when it finds none.
When a tool a team rule names changes, the SDK says so once on stderr, so you can check the rule still fits. It reads the rules file in your project, so a rule kept only on the gateway is not seen.
With AGENTX_API_KEY set where Claude Code or Codex runs (its environment, or the project's .env), each developer's hook also checks your gateway's rules and tells the gateway only about the calls a rule matched; agentx rule list then shows what each rule did across the team. The gateway's list wins: a rule changed on the website reaches every machine within 5 minutes, agentx rule push refuses to undo a change made there, and agentx rule pull takes those changes into the file for you to commit.
In Claude Code's auto mode, and when permission prompts are skipped, Claude Code does not stop to ask, so AgentX stops the call instead and gives the command back for you to run yourself (a one-line Bash command as !<command>, which the agent cannot type). Codex cannot ask either: once you add the check there with agentx hook install --codex, a team rule warns and the call runs, unless you added the rule with --stop-where-cannot-ask.
Team rules
Correcting your coding agent about the same thing again? Turn the correction into a rule. Before any shell command that contains every phrase you gave, Claude Code asks you first and shows your reason.
agentx rule add "run_suites.py" --why "the suites run once, at the end, with my go-ahead"
agentx rule listThe rule is written to .agentx/team-rules.json with who added it (your git name) and when. Commit the file, and teammates who have AgentX's check installed (agentx hook install) get the same rule. agentx rule list shows each rule and what it did; agentx rule remove ID takes one out. Add --tool NAME to match calls to that tool instead of shell commands. Nothing is written without a person at the terminal, and a shell command that changes the team rules is asked about too.
A rule can also hold a call by a number in it: 50 VMs may be fine on dev and not on production.
agentx rule add --tool provision_instances --argument count --hold-at prod=25 --hold-at dev=500 --why "more than a handful of VMs needs a second look"A call to provision_instances waits for a person when its count is at or above the limit for where the agent runs. That comes from AGENTX_ENVIRONMENT in the agent's process, such as AGENTX_ENVIRONMENT=prod, named as in --hold-at; with none set, or one the rule doesn't list, the lowest limit applies. A call whose count is missing or not a number waits too.
For money, add --currency USD, and --unit cents if the call's amount is in cents (an amount of 2550 is 25.50); --hold-at stays in the currency. The gateway already holds a payment at or above a set amount, $10 on the hosted gateway. A money rule replaces that amount for its tool, higher or lower, unless a limit set on your own gateway is lower. With --currency-field naming the argument that carries the call's currency, a call in another currency waits for a person too.
With --recipient customer_id naming the argument that says who is paid, payments to the same recipient add up. Without it, the gateway looks for one such as to, payee or customer, and adds up the tool's payments together when it finds none.
When a tool a team rule names changes, the SDK says so once on stderr, so you can check the rule still fits. It reads the rules file in your project, so a rule kept only on the gateway is not seen.
With AGENTX_API_KEY set where Claude Code or Codex runs (its environment, or the project's .env), each developer's hook also checks your gateway's rules and tells the gateway only about the calls a rule matched; agentx rule list then shows what each rule did across the team. The gateway's list wins: a rule changed on the website reaches every machine within 5 minutes, agentx rule push refuses to undo a change made there, and agentx rule pull takes those changes into the file for you to commit.
In Claude Code's auto mode, and when permission prompts are skipped, Claude Code does not stop to ask, so AgentX stops the call instead and gives the command back for you to run yourself (a one-line Bash command as !<command>, which the agent cannot type). Codex cannot ask either: once you add the check there with agentx hook install --codex, a team rule warns and the call runs, unless you added the rule with --stop-where-cannot-ask.
CLI reference
The agentx CLI ships with the Python SDK; agentx help prints this list.
| agentx demo | Ten-second offline 'aha': watch a DROP TABLE get blocked (no key, no gateway) |
| agentx hook | Check Claude Code's shell commands and MCP calls: 'hook install' adds it to this project's Claude Code settings and watches; 'hook install --enforce' blocks in every session |
| agentx evidence | A file for your reviewer: the rules in force, the calls stopped or held, the calls that did not run (no verdict, or halted as a runaway loop), and a link 'agentx audit --record --head' checks later. Writes agentx-evidence-<date>.json; '--json' prints it. '--gateway' writes the file your gateway builds instead, and '--gateway --head <value>' checks its record was not rewritten since |
| agentx audit | What your wrapped tools actually DID, grouped by tool; --calls for one row per call, --json for a program, --limit N or --all for how much, --share for a copy with your ledger path and trace ids stripped |
| 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 | Your wrapped tools' blocks, what came after, and the safe-paths learned, ready to adopt |
| agentx adopt | Adopt a learned safe-path so AgentX coaches your agents to it |
| agentx review | One-key pass over pending blocks: adopt a safe-path, or label a block right/wrong; it also proposes the tools and sites each agent may use |
| agentx allowlist | The tools and sites each agent may use, compared with your gateway's copy; 'allowlist push' sends .agentx/allowlist.json to your gateway |
| agentx holds | Calls your gateway is holding for a person; 'holds approve <receipt>' or 'holds deny <receipt>' answers one, with AGENTX_ADMIN_KEY |
| agentx rule | Turn a correction you keep repeating into a team rule in .agentx/team-rules.json ('rule add PHRASE --why REASON'): before a matching call, Claude Code asks you first (in auto mode AgentX stops it and hands the command back for you to run; Codex warns, or stops the call if you add --stop-where-cannot-ask); 'rule list' shows each rule with who added it, why, and what it did; 'rule remove ID' takes one out; 'rule push' sends them to your gateway; 'rule pull' takes the changes made there (on the website, or pushed from another copy) into the file |
| agentx policies | List the customizable floor policies + your active coaching (--check to validate), and what your policies file adds to them |
| 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.