Skip to main content
Glama

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.

PyPI Downloads Python CI Coverage License: MIT OpenSSF Scorecard GitHub stars

pip install agentguard47

Why AgentGuard

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

Problem

What AgentGuard does

Agent loops on the same tool

Raises LoopDetected

Flaky tool retries forever

Raises RetryLimitExceeded

Run spends too much

Raises BudgetExceeded

Run hangs

Raises TimeoutExceeded

Team needs proof

Writes local JSONL traces and incident reports

Dashboard comes later

HttpSink mirrors events only when you opt in

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

Related MCP server: Langfuse MCP Server

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.

Local Proof In 60 Seconds

agentguard doctor
agentguard demo
agentguard quickstart --framework raw

doctor verifies the install and local trace writing. demo proves budget, loop, and retry stops offline. quickstart prints the smallest starter for your stack.

Installed-package proof:

agentguard demo

Source-checkout proof with local incident output and hosted-compatible NDJSON:

git clone https://github.com/bmdhodl/agent47.git
cd agent47
PYTHONPATH=sdk python examples/sticky_agent_proof.py --out-dir proof/sticky-agent-proof
agentguard incident proof/sticky-agent-proof/sticky_agent_proof_traces.jsonl

Expected first value moment:

BudgetGuard stops simulated spend.
LoopGuard stops repeated tool calls.
RetryGuard stops a retry storm.
No API keys. No dashboard. No network calls.

Notebook version: Open In Colab

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

Guard

Stops

Example

BudgetGuard

dollar, token, or call overruns

BudgetGuard(max_cost_usd=5.00)

LoopGuard

exact repeated tool calls

LoopGuard(max_repeats=3)

FuzzyLoopGuard

similar calls and A-B-A-B loops

FuzzyLoopGuard(max_tool_repeats=5)

RetryGuard

retry storms on the same tool

RetryGuard(max_retries=3)

TimeoutGuard

long-running jobs

TimeoutGuard(max_seconds=300)

RateLimitGuard

calls per minute

RateLimitGuard(max_calls_per_minute=60)

BudgetAwareEscalation

hard turns that need a stronger model

BudgetAwareEscalation(...)

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.

Example

What it proves

examples/try_it_now.py

budget, loop, and retry stops

examples/sticky_agent_proof.py

one CrewAI-style retry storm proof with local incident and hosted NDJSON outputs

examples/coding_agent_review_loop.py

review/refinement loop stopped by budget and retry guards

examples/per_token_budget_spike.py

one oversized token-heavy turn can blow a run budget

examples/budget_aware_escalation.py

when to escalate from a cheap model to a stronger one

examples/decision_trace_workflow.py

proposal, edit, approval, and binding decision events

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.

Capability

AgentGuard

In-process hard budget caps

Yes

Kill a bad run by raising an exception

Yes

Loop and retry-storm detection

Yes

Local JSONL traces

Yes

Local incident reports

Yes

Hosted ingest

Optional

Required dashboard

No

Runtime dependencies

None

Competitive notes:

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.

Use local SDK when

Use hosted dashboard when

You are proving AgentGuard in one repo

Multiple people need the same incident history

You need hard stops for loops, retries, timeouts, or budget burn

Runs need retained alerts and follow-up outside the terminal

You want JSONL traces and reports without an API key

You need spend trends across traces, services, or teammates

You are testing an agent before production

Operators need 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: doctor, demo, quickstart, report, incident, eval

  • MCP package: @agentguard47/mcp-server

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.

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:

License

MIT. See LICENSE.

Available Tools

7 tools
check_budgetA
Read-onlyIdempotent

Read-only hosted event-quota health check. Combines dashboard event quota and recorded cost summaries. This is not SDK BudgetGuard, not a provider invoice cap, and it does not refuse the next model call.

Inputs: no named parameters.

get_alertsA
Read-onlyIdempotent

Read-only recent guard alerts (loop detection, budget exceeded) and errors from the hosted Read API. This reports stored alerts; it does not stop a running agent.

Inputs: limit, since.

get_costsA
Read-onlyIdempotent

Read-only hosted cost breakdown for the current month from the AgentGuard Read API. Estimated savings are recorded guard events, not an invoice credit.

Inputs: no named parameters.

get_traceA
Read-onlyIdempotent

Read-only full event tree for one retained trace. Shows spans, tool calls, LLM calls, guard triggers, and errors. Does not enforce BudgetGuard or intercept provider calls.

Inputs: trace_id (required).

get_trace_decisionsA
Read-onlyIdempotent

Read-only normalized decision.* events from one retained trace. Use this when a workflow includes proposal, override, approval, or binding steps. Does not approve, bind, or enforce those decisions.

Inputs: trace_id (required).

get_usageA
Read-onlyIdempotent

Read-only hosted event quota usage and plan limits from the AgentGuard Read API. This is dashboard event quota, not SDK BudgetGuard and not a provider invoice cap.

Inputs: no named parameters.

query_tracesA
Read-onlyIdempotent

Read-only search for retained AgentGuard trace summaries from the AgentGuard Read API. Requires AGENTGUARD_API_KEY with read access; create keys in the AgentGuard dashboard. Returns JSON with a traces array, newest traces first when the API supports ordering; items include trace_id, service, root_name, event_count, error_count, duration_ms, started_at, API key metadata, and total_cost when available. Defaults to a small page, accepts offset pagination, exact service filtering, and ISO 8601 since/until bounds. Use this to find candidate trace_id values; use get_trace for the full event tree of one trace or get_trace_decisions for decision.* events from a known trace.

Inputs: limit, since, until, offset, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct read-only aspect: trace search, full trace retrieval, decision events, alerts, usage, costs, and budget health check. The descriptions clearly separate them even where they overlap (e.g., usage vs. costs are explicitly differentiated).

    Naming Consistency4/5

    All tools follow a verb_noun pattern with mostly 'get_' prefixes; query_traces and check_budget deviate slightly but are still predictable. The naming is consistent enough that an agent would not be confused.

    Tool Count5/5

    Seven tools is well-scoped for a read-only monitoring API. Each tool has a clear, non-redundant purpose, covering search, detail, decisions, alerts, usage, costs, and budget—neither too few nor too many.

    Completeness5/5

    For a read-only trace and monitoring surface, the tool set is complete: it covers listing/searching traces, retrieving full traces, filtering decisions, and accessing alerts, usage, costs, and budget status. No obvious read operations are missing for the stated purpose.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A remote Model Context Protocol server acting as middleware to the Sentry API, allowing AI assistants like Claude to access Sentry data and functionality through natural language interfaces.
      74
      973
      Functional Source , Version 1.1, ALv2 Future
    • A
      license
      B
      quality
      D
      maintenance
      Enables querying Langfuse analytics, cost metrics, and usage data across multiple projects. Provides tools for trace analysis, model/service cost breakdowns, and daily usage trends through natural language queries.
      24
      73 npm
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI agents to query Prometheus metrics and Loki logs for intelligent alert investigation and troubleshooting. Provides service discovery, metric querying, log searching, and correlation tools to help identify root causes of issues.
      9
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local-first security gateway and visual dashboard for AI agents that enforces cost caps, blocks prompt injections, and requires approval for dangerous actions.
      3
      -