agentguard

AgentGuard

Runtime guardrails for coding agents. Recorded-budget preflight, loops, retries, and timeouts on instrumented Python paths. Zero dependencies. Local-first. This skill is onboarding, not host enforcement. See docs/enforcement-boundary.md.

Install

pip install agentguard47

Verify the install:

agentguard doctor

Quick Start (4 lines)

from agentguard import Tracer, BudgetGuard, 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)
# Chat Completions are tracked. Exhausted recorded budget refuses the next dispatch.

Guards

Guard	What it stops	Example
BudgetGuard	Dollar/token/call overruns	BudgetGuard(max_cost_usd=5.00)
LoopGuard	Exact repeated tool calls	LoopGuard(max_repeats=3)
FuzzyLoopGuard	Similar calls, A-B-A-B patterns	FuzzyLoopGuard(max_tool_repeats=5)
TimeoutGuard	Wall-clock time limits	TimeoutGuard(max_seconds=300)
RateLimitGuard	Calls-per-minute throttling	RateLimitGuard(max_calls_per_minute=60)
RetryGuard	Retry storms on flaky tools	RetryGuard(max_retries=3)

Guards raise exceptions (BudgetExceeded, LoopDetected, TimeoutExceeded, RetryLimitExceeded) on instrumented paths. They do not intercept host tools or provider invoices.

One-Liner Init with Defaults

import agentguard

agentguard.init(local_only=True)
# Reads .agentguard.json if present, sets up tracer + budget guard with sensible defaults

Or drop a .agentguard.json in your repo root:

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

Tracing

from agentguard import Tracer, JsonlFileSink, BudgetGuard

tracer = Tracer(
    sink=JsonlFileSink("traces.jsonl"),
    guards=[BudgetGuard(max_cost_usd=5.00)],
)

with tracer.trace("agent.run") as span:
    span.event("reasoning", data={"thought": "search docs"})
    span.cost.add("gpt-4o", input_tokens=1200, output_tokens=450)