Documentation

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, in under a millisecond.

from agentx_sdk import agentx_protect, is_block

# This is your existing tool. Any function your agent can call.
# Wrapping it is one line: the @agentx_protect decorator on top.
@agentx_protect(agent_id="crm_worker")
def dispatch_update(client_id: str, notes: str, db=None):
    """Save the agent's notes to a customer record."""
    query = f"UPDATE clients SET notes = '{notes}' WHERE id = '{client_id}'"
    return db.execute(query)        # never reached if the call is unsafe

# Your agent calls the tool exactly as before, nothing else changes:
out = dispatch_update(
    client_id="c-99401",
    notes="Follow up next week; DROP TABLE users;",   # prompt-injected
    db=session,
)

is_block(out)   # -> True. Blocked in-process before db.execute ran. No key.

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.