AgentGuard

Stop runaway Python agents before they burn money.

AgentGuard47 is a zero-dependency runtime control SDK for Python agents. Add hard budget caps, loop detection, retry limits, timeouts, local traces, and incident reports without changing agent frameworks or sending data anywhere by default.

Use it when an agent can call tools, retry work, review code, or run long enough to create surprise spend.

⭐ Star this repo if AgentGuard stops one runaway run for you. It is how other builders find it.

Install

As a Python package

pip install agentguard47
agentguard

The bare agentguard command prints a 60-second local tour. If the script is not on PATH, use python -m agentguard instead. Both run the same CLI.

As a skill (Codex, Claude Code, Cursor, Cline, and more)

npx skills add bmdhodl/agent47

Or with GitHub CLI:

gh skill install bmdhodl/agent47 agentguard

Why AgentGuard

Most agent tooling tells you what happened after the run. AgentGuard stops the bad run while it is happening.

AgentGuard is an in-process agentic-loop guard, not an LLM cost router. It runs inside the agent's process, sees the call graph, and raises exceptions that kill the run before the next bad call lands. Routers and gateways like Manifest or Vercel AI Gateway sit at the network layer and shape egress traffic. The layers are complementary, see the competitive notes for when each fits.

The headline value is the cross-call, cross-provider budget envelope: one ceiling that holds across every tool call, every retry, and every provider in the run. Single-call output caps are table stakes (Anthropic now ships per-tool max_tokens on the advisor tool, on 2026-06-02, see release notes). A single-call cap stops one oversized response. It does not stop a loop that makes 200 small calls, a retry storm across providers, or a run that mixes OpenAI and Anthropic and blows the combined budget. AgentGuard handles that envelope in-process and raises the exception that ends the run.

How AgentGuard Differs (Wedge Map)

AgentGuard's wedge is the runtime envelope: budget, token, rate, retry, and loop caps enforced at the call site while the agent is running.

Design constraints:

• zero runtime dependencies
• MIT licensed
• local-first by default
• no API key required for local proof
• no network calls unless you configure HttpSink
• guards raise exceptions inside the running process

Scope

AgentGuard's scope is the in-process runtime envelope: budget, token, rate, retry, loop, and timeout caps that fire inside the agent's Python process and raise exceptions that end the run.

OS-level containment is out of scope: process sandboxes, VMs, filesystem boundaries, and egress controls live one layer down from AgentGuard. For that layer, see Anthropic's "How we contain Claude across products" (2026-05-30) as the canonical reference. The layers are complementary: containment bounds what the process can touch; AgentGuard bounds what the agent loop inside that process can spend.

Real Incidents AgentGuard Prevents

PocketOS — agent deleted prod DB and backups in 9 seconds (May 2026)

A Cursor agent ran a destructive sequence against PocketOS production and wiped the live database. Backups went with it.

Reported root cause from the team's postmortem:

• one API key had write + delete on both prod and backups
• backups lived in the same Railway environment as prod
• no confirmation step before destructive actions
• the agent was given enough rope to chain the calls in one turn

Source: r/devops thread

The "AI did it" framing buries the actual lesson: the blast radius was infra, not the model. AgentGuard does not replace least-privilege creds or isolated backups. It does kill the run before a loop, retry storm, or runaway turn finishes the job.

A BudgetGuard plus LoopGuard wired around the agent loop caps how much it can do in one session:

from agentguard import BudgetGuard, LoopGuard, RateLimitGuard, Tracer

budget = BudgetGuard(max_calls=20, max_cost_usd=1.00)
loop = LoopGuard(max_repeats=2)
rate = RateLimitGuard(max_calls_per_minute=10)
tracer = Tracer(service="cursor-agent", guards=[loop, rate])

with tracer.trace("agent.run"):
    budget.consume(calls=1)
    # tool call here — guards raise on overrun

A 9-second sequence of destructive calls trips LoopGuard or RateLimitGuard long before it finishes. The exception kills the run in-process. Pair this with scoped credentials and out-of-environment backups for the rest of the blast radius.

Microsoft — engineers told to ease off Claude Code over inference cost (May 2026)

Microsoft engineering management reportedly asked teams to reduce Claude Code usage after monthly inference bills exceeded budget. If Microsoft cannot absorb coding-agent inference cost without a memo, runaway agent spend is no longer a solo-founder problem.

Source: TheNextWeb

A memo asks engineers to self-throttle. A BudgetGuard makes the cap a config value enforced inside the process:

from agentguard import BudgetGuard

BudgetGuard(max_cost_usd=5.00, max_calls=50, warn_at_pct=0.8)

The guard raises BudgetExceeded before the run blows the cap. Same conversation, one config line instead of a memo.

Local Proof in 60 Seconds

pip install agentguard47
agentguard doctor
agentguard demo
agentguard quickstart --framework raw --write
python agentguard_raw_quickstart.py
agentguard report .agentguard/traces.jsonl

This stays fully local. No API key, dashboard, or network call is required after installation.

What you should see:

• doctor verifies the installed package and writes a local trace.
• demo visibly trips budget, loop, and retry guards offline.
• quickstart --write creates agentguard_raw_quickstart.py.
• The generated file exits cleanly after catching simulated budget and loop stops.
• report shows local trace counts, cost, savings, and guard events.

Notebook version:

Show Your Repo Is Guarded

Once AgentGuard stops a runaway run for you, add the badge to your README so other builders find it:

agentguard badge

[![Guarded by AgentGuard](https://img.shields.io/badge/guarded%20by-AgentGuard-3b82f6)](https://github.com/bmdhodl/agent47)

agentguard badge --format rst and --format html print the same badge for other doc formats.

Copy-Paste Repo Setup

Use this when you want a coding agent or teammate to add AgentGuard safely:

pip install agentguard47
agentguard doctor
agentguard quickstart --framework raw --write
python agentguard_raw_quickstart.py
agentguard report .agentguard/traces.jsonl

Optional shared local defaults, saved as .agentguard.json in the repo root:

{
  "profile": "coding-agent",
  "service": "my-agent",
  "trace_file": ".agentguard/traces.jsonl",
  "budget_usd": 5.0
}

Keep the first PR local-only. Add hosted ingest later only when retained incidents, alerts, or team visibility matter.

Quickstart: Guard One Agent Run

from agentguard import BudgetGuard, JsonlFileSink, LoopGuard, Tracer

budget = BudgetGuard(max_cost_usd=5.00, max_calls=50, warn_at_pct=0.8)
loop = LoopGuard(max_repeats=3)
tracer = Tracer(
    sink=JsonlFileSink(".agentguard/traces.jsonl"),
    service="support-agent",
    guards=[loop],
)

with tracer.trace("agent.run") as span:
    budget.consume(calls=1, cost_usd=0.02)
    loop.check("search", {"query": "refund policy"})
    span.event("tool.call", data={"tool": "search", "query": "refund policy"})
    # Call your agent or tool here.

Inspect the local proof:

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

Auto-Patch Provider SDKs

If you already call OpenAI or Anthropic directly, patch once and keep using the provider normally:

from agentguard import BudgetGuard, Tracer, patch_openai

budget = BudgetGuard(max_cost_usd=5.00, warn_at_pct=0.8)
tracer = Tracer(service="support-agent")
patch_openai(tracer, budget_guard=budget)

# OpenAI chat completions are now traced and budget-enforced.

When accumulated cost crosses the hard limit, BudgetExceeded is raised and the agent stops.

Guards

Guards are static runtime checks. They do not ask another model whether a run is safe. They raise exceptions.

Examples

All examples are local-first. No API key is required unless the example says so.

Sample incident: docs/examples/coding-agent-review-loop-incident.md

Proof gallery: docs/examples/proof-gallery.md

Starter files: examples/starters/

Framework Integrations

AgentGuard can wrap raw Python code or integrate with common agent stacks.

agentguard quickstart --framework raw
agentguard quickstart --framework openai
agentguard quickstart --framework anthropic
agentguard quickstart --framework langchain
agentguard quickstart --framework langgraph
agentguard quickstart --framework crewai

Optional integration extras are opt-in. The core SDK stays stdlib-only.

pip install "agentguard47[langchain]"
pip install "agentguard47[langgraph]"
pip install "agentguard47[crewai]"
pip install "agentguard47[otel]"

Runtime Control vs Observability

AgentGuard is not a generic tracing platform. It is the local runtime stop layer.

Provider-native caps such as Anthropic's per-tool max_tokens cover one call on one provider. AgentGuard covers the whole run across every provider and every call. Use both: set the per-call cap at the provider, set the run-envelope cap in AgentGuard.

Competitive notes:

• AgentGuard vs Vercel AI Gateway
• AgentGuard vs Manifest (LLM router)
• Where AgentGuard fits in the agent security stack

Decision Traces

Capture proposal, human edit, approval, override, and binding events through the same event pipeline:

from agentguard import JsonlFileSink, Tracer, decision_flow

tracer = Tracer(sink=JsonlFileSink(".agentguard/traces.jsonl"))

with tracer.trace("agent.run") as run:
    with decision_flow(
        run,
        workflow_id="deploy-review",
        object_type="pull_request",
        object_id="123",
        actor_type="human",
        actor_id="pat",
    ) as decision:
        decision.proposed({"action": "merge"})
        decision.approved(comment="Looks safe")
        decision.bound(binding_state="merged", outcome="success")

Supported event types:

• decision.proposed
• decision.edited
• decision.overridden
• decision.approved
• decision.bound

Guide: docs/guides/decision-tracing.md

MCP Server

AgentGuard also ships a read-only MCP server for coding-agent workflows:

npx -y @agentguard47/mcp-server

Use the SDK to enforce local safety where the agent runs. Use MCP when a client like Codex, Claude Code, or Cursor needs read access to traces, decisions, costs, usage, and budget health.

Hosted Dashboard Boundary

The SDK is the free local proof path. The hosted dashboard is for retained history, alerts, team visibility, spend trends, hosted decision history, and dashboard-managed remote kill signals.

Start local. Add hosted ingest when the work becomes shared, expensive, or risky enough that local files are no longer enough.

from agentguard import HttpSink, Tracer

tracer = Tracer(
    sink=HttpSink(
        url="https://app.agentguard47.com/api/ingest",
        api_key="ag_...",
    )
)

HttpSink mirrors trace and decision events to the dashboard. It does not execute remote kill signals by itself.

Dashboard contract: docs/guides/dashboard-contract.md

Reports And CI Gates

Generate a local incident report:

agentguard incident .agentguard/traces.jsonl --format markdown
agentguard incident .agentguard/traces.jsonl --format html

Fail CI when a trace violates safety expectations:

from agentguard import EvalSuite

result = (
    EvalSuite(".agentguard/traces.jsonl")
    .assert_no_loops()
    .assert_budget_under(tokens=50_000)
    .assert_no_errors()
    .run()
)

assert result.passed

Package Facts

• Package: agentguard47
• Python: 3.9+
• License: MIT
• Core runtime dependencies: zero
• Trace format: JSONL
• Local commands: welcome, doctor, demo, quickstart, report, incident, eval, badge
• MCP package: @agentguard47/mcp-server
• Glama listing: AgentGuard47

Docs

Architecture

agent code
   |
   v
Tracer
   |
   +-- guards raise exceptions locally
   |
   +-- sinks write traces locally or mirror to hosted ingest

Repository layout:

sdk/          Python SDK package
mcp-server/   read-only MCP server
docs/         guides and competitive notes
examples/     runnable local examples
ops/          repo operating docs
memory/       SDK-only state and decisions

Security

• No secrets are required for local mode.
• Do not put API keys in .agentguard.json.
• Hosted ingest API keys should be stored in environment variables.
• Local guards remain authoritative even when hosted ingest is configured.

Threat model: agent data exfiltration

A recurring class of agent attack uses the agent's own write surface as an outbound channel. Example pattern from Microsoft Copilot Cowork (May 2026): the agent emails the user's own inbox with no approval, the rendered message fetches an external image, and the image URL encodes data the attacker wanted out. AgentGuard does not replace an egress firewall or tool-permission layer, but it gives the agent runtime hard stops for runaway loops, retries, and budget burn that can turn one bad tool call into a sustained incident.

Citation: https://simonwillison.net/2026/May/26/copilot-cowork-exfiltrates-files/

Report security issues through GitHub Security Advisories or by email: pat@bmdpat.com.

Contributing

Contributions are welcome when they keep the SDK small, local-first, and zero-dependency.

Before opening a PR:

python -m pytest sdk/tests/ -v
python -m ruff check sdk/agentguard/
python scripts/sdk_release_guard.py

Useful links:

• CONTRIBUTING.md
• GOLDEN_PRINCIPLES.md

License

MIT. See LICENSE.