agentsec-agentwatch

agentwatch

Instrumentation SDK for AI agents — turn agent behavior into OpenTelemetry GenAI spans and validated, redacted execution records. Part of agentwatch.

Installation

pip install agentsec-agentwatch

Optional extras:

pip install "agentsec-agentwatch[langgraph]"   # LangGraph adapter
pip install "agentsec-agentwatch[otlp]"        # OTLP export
pip install "agentsec-agentwatch[signing]"     # cryptographic signing helpers

Requires Python 3.10+.

Quickstart

Trace a plain Python agent — no framework required:

from agentwatch.raw import trace_agent
from agentwatch.spans import plan_span, execute_tool_span

@trace_agent("support-bot", agent_version="v0.1.0", model="gpt-4o", provider="openai")
def answer(request: str) -> str:
    with plan_span("decide next action"):
        ...
    with execute_tool_span("search", arguments={"q": request}):
        ...
    return "done"

Or drive the run context explicitly:

from agentwatch.config import default_config
from agentwatch.tracer import configure_tracing
from agentwatch.context import RunContext
from agentwatch.instrument import invoke_agent

configure_tracing(default_config())          # once at startup
with invoke_agent(RunContext(agent_name="request-triage")):
    ...

LangGraph:

from agentwatch.langgraph import trace_graph

graph = trace_graph(compiled_graph, agent_name="planner")

Privacy

Records are redacted by default. Four privacy modes are available per span/tool call:

Record, replay, verify

The same package installs the CLI:

agentsec-agentwatch init            # install Claude Code hooks + start the local daemon
agentsec-agentwatch sessions        # list recorded sessions
agentsec-agentwatch replay <id>     # reconstruct a session's action timeline
agentsec-agentwatch verify-store    # verify the hash chain

Records are written to a local-first, hash-chained JSONL store; OTLP export is opt-in and gated on a redaction self-test.

Documentation

• SDK reference
• User guide
• Record format spec
• Docs index
• Changelog · Security policy · Issues

License

Apache-2.0 — see LICENSE.