AgentGuard

Stop runaway agents before they burn money.

Zero-dependency Python kill switch for AI agents. Hard budget caps. Loop detection. Local traces. MIT.

pip install agentguard47

Getting started

1. Install and verify

pip install agentguard47
agentguard doctor   # package ok?
agentguard demo     # offline proof (no API keys)

2. Guard an OpenAI client

from agentguard import BudgetGuard, LoopGuard, Tracer, patch_openai

budget = BudgetGuard(max_cost_usd=5.00, warn_at_pct=0.8)
loop = LoopGuard(max_repeats=3)
tracer = Tracer(service="my-agent", guards=[loop])

patch_openai(tracer, budget_guard=budget)
# every OpenAI call is now traced + budget-enforced

When spend crosses the hard limit, BudgetExceeded is raised and the run stops.

3. Cap a single task

Session budget can still have headroom. One goal can still be killed:

with budget.goal("refund", max_cost_usd=0.50, warn_at_pct=0.8) as g:
    g.attempt()
    budget.consume(cost_usd=0.12)
    # BudgetExceeded names the goal when it crosses

4. Read the local proof

agentguard report .agentguard/traces.jsonl
agentguard incident .agentguard/traces.jsonl

Or scaffold a starter file:

agentguard quickstart --framework raw --write
python agentguard_raw_quickstart.py

What it stops

Not a dashboard. Not a model router. An in-process exception that kills the bad run mid-flight.

Cap your agent's x402 wallet spend

Agents that pay per-call via x402 (USDC micropayments) can drain a wallet in a silent loop. X402SpendGuard wraps the payment step and refuses before paying:

from agentguard import X402SpendGuard

guard = X402SpendGuard(
    max_total_usd=5.00,        # wallet cap, add period="day" for a daily reset
    max_per_endpoint_usd=1.00, # cap per resource URL
    max_per_call_usd=0.10,     # refuse any single payment above this
)
guard.charge(0.001, "https://api.example.com/search", my_x402_pay_step)

AgentGuard meters and refuses; it never signs or settles. Amounts come from your x402 client. No crypto dependencies.

Features

• Hard stops — exceptions inside your process, not after-the-fact alerts
• Task-level budgets — BudgetGuard.goal(...) for sub-task caps + warn hooks
• Local traces — JSONL by default; no network unless you opt in
• Zero deps — stdlib only; Python 3.9+
• Provider patches — patch_openai / patch_anthropic
• Budget preflight — provider patches refuse new requests once recorded usage reaches a configured cap, including sync and async clients. Use budget.check() before your own provider call and budget.consume(...) after its response. The check does not charge usage or reserve concurrent capacity. A response can exceed the remaining token/cost allowance; streaming totals are not yet tracked by the patches.
• Framework hooks — LangChain, LangGraph, CrewAI (optional extras)

Local by default

• No API key required for local proof
• No network unless you configure HttpSink
• MIT licensed

The SDK is the free local proof path. Start local. Add hosted ingest later only if you want retained history, alerts, team visibility, spend trends, hosted decision history, or dashboard-managed remote kill signals. Local guards remain authoritative. HttpSink mirrors trace and decision events; it does not execute remote kill signals by itself.

Integrations

OpenAI · Anthropic · LangChain · LangGraph · CrewAI · raw agent loops

pip install "agentguard47[langchain]"   # optional extras as needed

Security

The base install declares zero runtime dependencies. pip install agentguard47 pulls nothing, so a default install adds no third-party exposure.

Extras install third-party packages and need a separate audit. The LangChain and LangGraph extras now require Python 3.10+ and raise their minimum versions to the tested September 2026 releases. OpenTelemetry requires 1.44.0 or newer. The base SDK remains compatible with Python 3.9+.

The optional [crewai] extra requires CrewAI 1.15.21 or newer. Its current dependency tree still installs ChromaDB 1.1.1, with four distinct unresolved advisories: CVE-2026-45829, CVE-2026-45830, CVE-2026-45831, and CVE-2026-45833. The audit database provides no fixed version. Avoid this extra unless you have reviewed that upstream exposure. Installing AgentGuard alone does not install ChromaDB or start a server. See the upstream advisory and the release audit.

HttpSink validates the address it actually connects to, retains TLS hostname verification, and refuses cross-origin redirects. It connects directly and does not use environment proxy settings. A local guard stops instrumented work in your Python process; it does not cancel an agent loop running on a provider's server. Cost estimates are not invoices; supply provider-reported cost or use strict cost resolution when an estimate is insufficient.

Docs

• Getting started guide
• Examples
• MCP server — npx -y @agentguard47/mcp-server

Links

• PyPI: https://pypi.org/project/agentguard47/
• Issues: https://github.com/bmdhodl/agent47/issues
• AgentGuard on the web (hosted history, alerts, and MCP visibility for Claude Code, Cursor, and Codex): https://bmdpat.com/tools/agentguard?utm_source=agentguard47&utm_medium=readme&utm_campaign=touchpoints

The hosted page is an optional next step, not a requirement. The SDK stays free, local, and MIT, and the local guards stay authoritative. Nothing in this package phones home. The only network egress is a sink or exporter you configure yourself, such as HttpSink or an OpenTelemetry exporter.

MIT · Built for people who ship agents and hate surprise bills.

Latest Release Notes (1.3.1)

(2026-09-14)

Stop exhausted-budget retries before provider dispatch

• OpenAI and Anthropic patches now check their supplied budget before calling the provider, for both sync and async clients. Catching BudgetExceeded cannot send another request after the recorded budget reaches its cap.
• Added BudgetGuard.check(): a non-consuming check of call, token, and cost limits, including zero caps and the current persisted daily budget.
• Successful responses are still charged once. Reset and daily rollover allow new calls. Corrupt persisted counters fail closed.
• This is a preflight check, not a concurrent reservation or an estimate of the next response. In-flight calls can exceed token/cost caps. Streaming usage accounting remains outside this release.
• Reproduce the before/after behavior without network calls with examples/budget_preflight_demo.py. The provider is mocked; the installed AgentGuard patch, guard, and retry loop are real.

Full changelog: CHANGELOG.md