agentguard47 0.3.0

Lightweight observability and evaluation primitives for multi-agent systems

AgentGuard SDK (Python)

Lightweight, zero-dependency observability for multi-agent AI systems. Trace reasoning steps, catch loops, guard budgets, and replay runs deterministically.

Install

pip install agentguard47

With LangChain support:

pip install agentguard47[langchain]

Quickstart

from agentguard import Tracer, LoopGuard, BudgetGuard

tracer = Tracer()
loop_guard = LoopGuard(max_repeats=3)
budget_guard = BudgetGuard(max_tokens=10000)

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

    loop_guard.check(tool_name="search", tool_args={"query": "agent loops"})
    budget_guard.record_tokens(150)

    with span.span("tool.call", data={"tool": "search"}):
        pass  # call your tool here

Tracing

from agentguard.tracing import Tracer

tracer = Tracer()

with tracer.trace("agent.run", data={"user_id": "u123"}) as span:
    span.event("reasoning.step", data={"step": 1, "thought": "search docs"})
    with span.span("tool.call", data={"tool": "search", "query": "agent loops"}):
        pass

Guards

from agentguard.guards import LoopGuard, BudgetGuard, TimeoutGuard

# Detect repeated tool calls
guard = LoopGuard(max_repeats=3)
guard.check(tool_name="search", tool_args={"query": "agent loops"})

# Track token and call budgets
budget = BudgetGuard(max_tokens=50000, max_calls=100)
budget.record_tokens(150)
budget.record_call()

# Enforce wall-clock time limits
timeout = TimeoutGuard(max_seconds=30)
timeout.start()
timeout.check()  # raises TimeoutExceeded if over limit

Replay

from agentguard.recording import Recorder, Replayer

recorder = Recorder("runs.jsonl")
recorder.record_call("llm", {"prompt": "hi"}, {"text": "hello"})

replayer = Replayer("runs.jsonl")
resp = replayer.replay_call("llm", {"prompt": "hi"})

Evaluation as Code

from agentguard import EvalSuite

result = (
    EvalSuite("traces.jsonl")
    .assert_no_loops()
    .assert_tool_called("search", min_times=1)
    .assert_budget_under(tokens=50000)
    .assert_completes_within(30.0)
    .assert_no_errors()
    .run()
)
print(result.summary)

Auto-Instrumentation

from agentguard import Tracer
from agentguard.instrument import trace_agent, trace_tool

tracer = Tracer()

@trace_agent(tracer)
def my_agent(query):
    return search(query)

@trace_tool(tracer)
def search(q):
    return f"results for {q}"

# Monkey-patch OpenAI/Anthropic (safe if not installed)
from agentguard.instrument import patch_openai, patch_anthropic
patch_openai(tracer)
patch_anthropic(tracer)

CLI

# Summarize trace events
agentguard summarize traces.jsonl

# Human-readable report
agentguard report traces.jsonl

# Open Gantt trace viewer in browser
agentguard view traces.jsonl

# Run evaluation assertions
agentguard eval traces.jsonl

Trace Viewer

agentguard view traces.jsonl --port 8080

Gantt-style timeline with color-coded spans (reasoning, tool, LLM, guard, error), click-to-expand detail panel, and aggregate stats.

Integrations

• LangChain: agentguard.integrations.langchain

Links

• GitHub
• Trace Schema
• Examples