bmdhodl/agent47

Stop runaway agents with runtime checks in Python.
AgentGuard checks budgets, repeated tool calls, retries, and elapsed time in
instrumented Python code. Guards raise exceptions so your application can stop
the next operation. The base SDK has no runtime dependencies and needs no account.
**Names:** this repository is agent47, the PyPI package is agentguard47,
and the Python import is agentguard. AgentGuard 2.0.0 requires Python 3.11 or newer.
On Python 3.9 or 3.10, pin agentguard47==1.4.0. See the
Python migration guide before upgrading.
Getting started
Install in a virtual environment, then run the offline checks:
doctor checks the installation and local trace writing. demo exercises
budget, loop, and retry stops without provider keys or network access. Follow
the trace path printed by the command to inspect its output.
agentguard demo --feedback prints a local redacted report; nothing is sent.
For a fresh PowerShell install and a runnable raw starter, follow the
published-release walkthrough.
Share a stop receipt (new in 2.0.0)
agentguard receipt agentguard_demo_traces.jsonl prints a receipt of each stop
with the trace's SHA-256 drawn as a barcode. Add --format markdown to paste it
into a PR or issue. The hash identifies the trace file; it is not a signature.
This **stop receipt** records a covered guard refusal. Anthropic's official
/receipts plugin
summarizes past Claude Code work (30 days by default). Neither output proves
prevented spend or provides a signed attestation. The agentguard receipt
command stays the same.
Guard a Claude Code session (new in 2.0.0)
This installs a Claude Code hook that refuses the third identical tool call in
a row and a call that already failed twice. "Identical" ignores JSON key order
and preserves case and whitespace in values. The optional no_progress_max
rule refuses a tool after repeated empty or same-error results even when input
changes; it is off by default. Refusals omit raw input and go to
.agentguard/claude-code/trace.jsonl. It
checks tool calls, not tokens or subscription quota. See the
Claude Code hook guide.
Guard a script without editing it (new in 2.0.0)
This patches the OpenAI and Anthropic clients, then runs agent.py in the same
interpreter. Settings come from flags, then environment variables, then
.agentguard.json. A guard stop exits 1. Every run ends with the trace path on
stderr, ready for agentguard receipt. agentguard run python -m mypkg works too. The bounds are
the same as patching the client yourself; see
enforcement boundary.
Subprocesses start a separate interpreter and are not patched by the parent.
A detached, uninstrumented child can keep running after the guarded script
exits. The offline reproduction
demonstrates that boundary with two simulated calls and no network access.
agentguard run prices every patched call at paid rates, including a local
model behind an OpenAI-compatible URL such as Ollama. A dollar budget can then
stop a model that costs nothing. For a local model, patch the client in the
script with free_local_clients=[client] and a BudgetGuard token or call
cap, then run the script with python; see
free local clients.
Stop before a third call
Save this as budget_demo.py and run python budget_demo.py. It makes no
network requests.
Expected output: Stopped before call 3.
Stop a reworded loop
A stuck agent often rewords each retry, so no call repeats exactly.
max_no_progress counts results instead: the same tool coming back empty, or
with the same error, N times in a row stops the run whatever the arguments.
normalize=True canonicalizes containers while preserving case and whitespace
in argument values. Both options are off by default.
Expected output: No progress: grep came back empty 3 times in a row (limit: