Getting Started with AgentGuard

Get from zero to your first traced agent run in under 5 minutes.

Install

pip install agentguard47

Zero dependencies. Python 3.9+.

Fastest safe activation path

Copy-paste this when you want the shortest local proof before touching a real agent or provider key:

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

This path proves local trace writing, budget stops, loop stops, retry stops, and a runnable starter file without any network calls.

Verify the install

Start with a local verification pass:

agentguard doctor

This stays fully local:

• no dashboard
• no network calls
• no hosted control-plane dependency

It verifies that AgentGuard can initialize in local-only mode, write a local trace, and recommend the smallest correct next step for the current environment.

Generate the right starter

Once the SDK is verified locally, print the starter for the stack you actually use:

agentguard quickstart --framework raw
agentguard quickstart --framework openai
agentguard quickstart --framework langchain --json

This is intentionally high-signal:

• no framework auto-detection
• no dashboard dependency
• no hidden file writes

It gives you the install command, the starter file contents, and the next commands to run.

Optional repo-local defaults

If you want a repo to carry safe local defaults, create .agentguard.json:

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

This stays intentionally narrow:

• safe local defaults only
• no secrets
• no API keys
• no hosted control-plane behavior

After that, agentguard.init() can stay minimal:

import agentguard

agentguard.init(local_only=True)

For coding-agent and repo-automation setups, follow coding-agents.md after doctor, then use coding-agent-safety-pack.md for copy-paste repo instructions.

If you want AgentGuard to generate those repo-local instruction files instead of copying snippets by hand:

agentguard skillpack --write

That writes .agentguard.json plus agent-specific instruction files into agentguard_skillpack/ for review before you copy or merge them into a real repo.

Offline demo

Before wiring a real agent, prove the SDK locally:

agentguard demo

This is fully offline:

• no API keys
• no dashboard
• no network calls

It writes a local trace file, demonstrates budget enforcement, loop detection, and retry protection, then shows how to inspect the trace with agentguard report and agentguard incident.

For a more realistic coding-agent failure mode, run the local review-loop proof:

python examples/coding_agent_review_loop.py
agentguard incident coding_agent_review_loop_traces.jsonl

This simulates repeated review/edit attempts and a stuck patch retry storm. It uses BudgetGuard and RetryGuard, writes a local JSONL trace, and still makes no network calls. A checked-in sample incident is available at ../examples/coding-agent-review-loop-incident.md.

If your agent runtime uses disposable workers or managed-agent harnesses, add a runtime session_id to correlate those short-lived traces:

import agentguard

agentguard.init(
    service="managed-harness-a",
    session_id="support-session-001",
    local_only=True,
)

Guide: managed-agent-sessions.md

1. Trace an agent run

from agentguard import Tracer, JsonlFileSink

tracer = Tracer(sink=JsonlFileSink(".agentguard/traces.jsonl"), service="my-agent")

with tracer.trace("agent.run") as span:
    span.event("reasoning.step", data={"thought": "search for docs"})

    with span.span("tool.search", data={"query": "python asyncio"}) as tool:
        result = "found 3 results"  # your tool call here
        tool.event("tool.result", data={"result": result})

    span.event("reasoning.step", data={"thought": "summarize results"})

This writes every step to .agentguard/traces.jsonl — reasoning, tool calls, timing, everything. The parent directory is created automatically.

2. View the trace

agentguard report .agentguard/traces.jsonl

AgentGuard report
  Total events: 6
  Spans: 2  Events: 4
  Approx run time: 0.3 ms
  Savings ledger: exact 0 tokens / \$0.0000, estimated 0 tokens / \$0.0000

Render an incident report:

agentguard incident .agentguard/traces.jsonl

3. Add a loop guard

Stop agents that repeat themselves. Guards auto-check on every span.event() call:

from agentguard import Tracer, LoopGuard, LoopDetected, JsonlFileSink

tracer = Tracer(
    sink=JsonlFileSink(".agentguard/traces.jsonl"),
    service="my-agent",
    guards=[LoopGuard(max_repeats=3)],
)

with tracer.trace("agent.run") as span:
    for step in range(10):
        try:
            # LoopGuard checks fire on event(), not on span()
            span.event("tool.call", data={"tool": "search", "query": "test"})
        except LoopDetected as e:
            print(f"Loop caught: {e}")
            break

4. Add a budget guard

Cap spend per agent run:

from agentguard import Tracer, BudgetGuard, JsonlFileSink

budget = BudgetGuard(max_cost_usd=5.00, warn_at_pct=0.8)
tracer = Tracer(
    sink=JsonlFileSink(".agentguard/traces.jsonl"),
    service="my-agent",
)

# Record usage where model calls happen.
budget.consume(calls=1, cost_usd=0.02)

# Raises BudgetExceeded when the limit is hit.
# Fires BudgetWarning at 80% of the limit.

If you want a local proof that token-based pricing can spike on one oversized turn, run:

python examples/per_token_budget_spike.py
agentguard report per_token_budget_spike_traces.jsonl

That example prices each turn from token counts, then shows BudgetGuard catching a single high-context spike before the run drifts further.

5. Auto-instrument OpenAI

Skip manual tracing — let AgentGuard patch the OpenAI client:

from agentguard import BudgetGuard, Tracer, JsonlFileSink, patch_openai

budget = BudgetGuard(max_cost_usd=5.00, warn_at_pct=0.8)
tracer = Tracer(sink=JsonlFileSink(".agentguard/traces.jsonl"), service="my-agent")
patch_openai(tracer, budget_guard=budget)

# OpenAI chat completions are now traced with token counts, cost estimates, and budget checks.
# Works with openai>=1.0 client instances.

Same for Anthropic:

from agentguard import patch_anthropic
patch_anthropic(tracer, budget_guard=budget)

6. Use with LangChain

pip install agentguard47[langchain]

from agentguard import LoopGuard, BudgetGuard
from agentguard.integrations.langchain import AgentGuardCallbackHandler

handler = AgentGuardCallbackHandler(
    loop_guard=LoopGuard(max_repeats=3),
    budget_guard=BudgetGuard(max_cost_usd=5.00),
)

# Pass to any LangChain LLM or agent:
result = agent.invoke(
    {"input": "your question"},
    config={"callbacks": [handler]},
)

7. Create an incident report

When a run blows through budget or hits a loop, render a shareable report:

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

The incident report highlights guard events, the exact-vs-estimated savings ledger, and the upgrade path to retained alerts, team visibility, and remote kill signal management.

8. Send traces to the dashboard

Swap the file sink for an HTTP sink when you need retained incidents, alerts, team visibility, or hosted decision history:

from agentguard import Tracer, HttpSink

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

Sign up at app.agentguard47.com to get an API key.

HttpSink mirrors trace and decision events to the dashboard. It does not poll or execute dashboard remote kill signals by itself; local guards remain the authoritative runtime stop path.

Hosted contract details: dashboard-contract.md

Next steps

• Examples — LangChain, CrewAI, OpenAI integration examples
• Coding agents — repo-local onboarding for Codex, Claude Code, Cursor, and similar tools
• Guards reference — LoopGuard, FuzzyLoopGuard, BudgetGuard, TimeoutGuard, RateLimitGuard, RetryGuard
• Evaluation — assertion-based trace analysis for CI
• Incident Reports — local postmortem-style summaries for guard trips
• Dashboard Contract - hosted ingest, decision history, and remote-kill boundaries
• Async support — AsyncTracer, async decorators