{
  "markdown": "# AgentGuard\n\n**Stop runaway agents before they burn money.**\n\nZero-dependency Python kill switch for AI agents. Hard budget caps. Loop detection. Local traces. MIT.\n\n[![PyPI](https://img.shields.io/pypi/v/agentguard47)](https://pypi.org/project/agentguard47/)\n[![Downloads](https://img.shields.io/pypi/dm/agentguard47)](https://pypi.org/project/agentguard47/)\n[![Python](https://img.shields.io/pypi/pyversions/agentguard47)](https://pypi.org/project/agentguard47/)\n[![CI](https://github.com/bmdhodl/agent47/actions/workflows/ci.yml/badge.svg)](https://github.com/bmdhodl/agent47/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n```bash\npip install agentguard47\n```\n\n## Getting started\n\n### 1. Install and verify\n\n```bash\npip install agentguard47\nagentguard doctor   # package ok?\nagentguard demo     # offline proof (no API keys)\n```\n\n### 2. Guard an OpenAI client\n\n```python\nfrom agentguard import BudgetGuard, LoopGuard, Tracer, patch_openai\n\nbudget = BudgetGuard(max_cost_usd=5.00, warn_at_pct=0.8)\nloop = LoopGuard(max_repeats=3)\ntracer = Tracer(service=\"my-agent\", guards=[loop])\n\npatch_openai(tracer, budget_guard=budget)\n# every OpenAI call is now traced + budget-enforced\n```\n\nWhen spend crosses the hard limit, `BudgetExceeded` is raised and the run stops.\n\n### 3. Cap a single task\n\nSession budget can still have headroom. One goal can still be killed:\n\n```python\nwith budget.goal(\"refund\", max_cost_usd=0.50, warn_at_pct=0.8) as g:\n    g.attempt()\n    budget.consume(cost_usd=0.12)\n    # BudgetExceeded names the goal when it crosses\n```\n\n### 4. Read the local proof\n\n```bash\nagentguard report .agentguard/traces.jsonl\nagentguard incident .agentguard/traces.jsonl\n```\n\nOr scaffold a starter file:\n\n```bash\nagentguard quickstart --framework raw --write\npython agentguard_raw_quickstart.py\n```\n\n## What it stops\n\n| Problem | Guard | Exception |\n|---------|-------|-----------|\n| Spend blowup | `BudgetGuard` | `BudgetExceeded` |\n| Same tool forever | `LoopGuard` | `LoopDetected` |\n| Fuzzy / A-B-A-B loops | `FuzzyLoopGuard` | `LoopDetected` |\n| Retry storms | `RetryGuard` | `RetryLimitExceeded` |\n| Hung runs | `TimeoutGuard` | `TimeoutExceeded` |\n| Spam calls | `RateLimitGuard` | — |\n| Wallet drain (x402/USDC) | `X402SpendGuard` | `BudgetExceeded` |\n\nNot a dashboard. Not a model router. An **in-process exception** that kills the bad run mid-flight.\n\n### Cap your agent's x402 wallet spend\n\nAgents that pay per-call via x402 (USDC micropayments) can drain a wallet in a\nsilent loop. `X402SpendGuard` wraps the payment step and refuses before paying:\n\n```python\nfrom agentguard import X402SpendGuard\n\nguard = X402SpendGuard(\n    max_total_usd=5.00,        # wallet cap, add period=\"day\" for a daily reset\n    max_per_endpoint_usd=1.00, # cap per resource URL\n    max_per_call_usd=0.10,     # refuse any single payment above this\n)\nguard.charge(0.001, \"https://api.example.com/search\", my_x402_pay_step)\n```\n\nAgentGuard meters and refuses; it never signs or settles. Amounts come from\nyour x402 client. No crypto dependencies.\n\n## Features\n\n- **Hard stops** — exceptions inside your process, not after-the-fact alerts\n- **Task-level budgets** — `BudgetGuard.goal(...)` for sub-task caps + warn hooks\n- **Local traces** — JSONL by default; no network unless you opt in\n- **Zero deps** — stdlib only; Python 3.9+\n- **Provider patches** — `patch_openai` / `patch_anthropic`\n- **Framework hooks** — LangChain, LangGraph, CrewAI (optional extras)\n\n## Local by default\n\n- No API key required for local proof\n- No network unless you configure `HttpSink`\n- MIT licensed\n\nThe 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.\n\n## Integrations\n\nOpenAI · Anthropic · LangChain · LangGraph · CrewAI · raw agent loops\n\n```bash\npip install \"agentguard47[langchain]\"   # optional extras as needed\n```\n\n## Security\n\nThe base install declares zero runtime dependencies. `pip install agentguard47` pulls nothing, so a default install adds no third-party exposure.\n\nExtras pull real dependency trees. The `[crewai]` extra pulls `chromadb`, which carries [PYSEC-2026-311](https://osv.dev/vulnerability/PYSEC-2026-311): a pre-authentication remote code execution advisory with **no fixed release available**. Nothing in AgentGuard calls the affected endpoint, and installing the extra does not start a ChromaDB server. You are exposed only if you run a ChromaDB server reachable by untrusted callers. A 2026-08-28 `pip-audit` run also flags CVE-2026-45830, CVE-2026-45831, and CVE-2026-45833 against the same `chromadb` release, none with a fixed version. The `[langchain]`, `[langgraph]`, and `[otel]` extras resolve clean under `pip-audit`. See [#702](https://github.com/bmdhodl/agent47/issues/702) for the full finding.\n\n## Docs\n\n- [Getting started guide](docs/guides/getting-started.md)\n- [Examples](examples/)\n- [MCP server](mcp-server/) — `npx -y @agentguard47/mcp-server`\n\n## Links\n\n- PyPI: https://pypi.org/project/agentguard47/\n- Issues: https://github.com/bmdhodl/agent47/issues\n- 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\n\nThe 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.\n\n---\n\nMIT · Built for people who ship agents and hate surprise bills.\n",
  "bytes": 5906,
  "sha": "fcd4294d23c15f64e0653bd4a9d4822c0cda8913e2e69d1fe21cddde1fcc911b",
  "repo_slug": "bmdhodl/agent47",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bmdhodl_agentguard47_09eab382/readme"
}