Agentguard47 MCP server

AgentGuard

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. Requires Python 3.9 or newer.

Getting started

Install in a virtual environment, then run the offline checks:

python -m pip install agentguard47
agentguard doctor
agentguard demo

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.

agentguard receipt agentguarddemotraces.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.

Guard a Claude Code session

agentguard hook claude-code --install --write

This installs a Claude Code hook that refuses the third identical tool call in a row and a call that already failed twice. Refusals 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

agentguard run --budget-usd 5 agent.py

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.

Stop before a third call

Save this as budgetdemo.py and run python budgetdemo.py. It makes no network requests.

from agentguard import BudgetExceeded, BudgetGuard

budget = BudgetGuard(max_calls=2)
completed = 0

for _ in range(3):
    try:
        budget.check()  # Check before the operation.
        # Put your provider or tool call here.
        completed += 1
        budget.consume(calls=1)  # Record the completed operation.
    except BudgetExceeded:
        print(f"Stopped before call {completed + 1}")

assert completed == 2

Expected output: Stopped before call 3.

Connect a provider

Install the provider's client separately. For OpenAI:

python -m pip install openai

from agentguard import BudgetGuard, JsonlFileSink, Tracer, patch_openai

budget = BudgetGuard(max_cost_usd=5.00)
tracer = Tracer(
    service="my-agent",
    sink=JsonlFileSink(".agentguard/traces.jsonl"),
)
patch_openai(tracer, budget_guard=budget)
# Make your OpenAI chat.completions.create or responses.create calls after this setup.

The patch checks recorded usage before dispatch and records response usage afterward, including streamed calls once the final usage arrives. A response can exceed the remaining cost or token allowance. Concurrent requests do not reserve capacity. Chat Completions streams request include_usage unless the caller already set it.

Shortened. The full README is on GitHub.