Metadata-Version: 2.4
Name: agentsec-agentwatch
Version: 0.2.1
Summary: Execution traces for agent behavior - OpenTelemetry-style observability for AI agent workflows
Author-email: Debashish Ghosal <deghosal@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/agentsec-ecosystem/agentwatch
Project-URL: Repository, https://github.com/agentsec-ecosystem/agentwatch
Project-URL: Issues, https://github.com/agentsec-ecosystem/agentwatch/issues
Project-URL: Documentation, https://github.com/agentsec-ecosystem/agentwatch/blob/main/docs/README.md
Project-URL: Changelog, https://github.com/agentsec-ecosystem/agentwatch/blob/main/CHANGELOG.md
Keywords: ai-agents,observability,opentelemetry,agent-security,llm,tracing,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api>=1.24
Requires-Dist: opentelemetry-sdk>=1.24
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: langgraph
Requires-Dist: langgraph>=1.0; extra == "langgraph"
Provides-Extra: codex
Requires-Dist: zstandard>=0.22; python_version < "3.14" and extra == "codex"
Provides-Extra: signing
Requires-Dist: cryptography>=41; extra == "signing"
Provides-Extra: otlp
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.24; extra == "otlp"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"
Requires-Dist: tomli>=2; extra == "dev"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.24; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: zstandard>=0.22; extra == "dev"
Provides-Extra: mutation
Requires-Dist: cosmic-ray>=8.7; extra == "mutation"
Dynamic: license-file

# agentwatch

[![PyPI version](https://img.shields.io/pypi/v/agentsec-agentwatch.svg)](https://pypi.org/project/agentsec-agentwatch/)
[![Python versions](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-green.svg)](https://github.com/agentsec-ecosystem/agentwatch/blob/main/LICENSE)
[![Status: v0.1.0](https://img.shields.io/badge/status-v0.1.0-green.svg)](https://github.com/agentsec-ecosystem/agentwatch/blob/main/docs/release/v0.1.0/release-notes.md)

**Instrumentation SDK for AI agents** — turn agent behavior into OpenTelemetry GenAI
spans and validated, redacted execution records. Part of
[agentwatch](https://github.com/agentsec-ecosystem/agentwatch).

## Installation

```bash
pip install agentsec-agentwatch
```

Optional extras:

```bash
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:

```python
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:

```python
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:

```python
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:

| Mode | What is stored |
|---|---|
| `truncated` (default) | Content-safe truncated values |
| `metadata-only` | Names, timings, and counts; no content |
| `hashed` | One-way digests of content |
| `full` | Raw content (opt-in) |

## Record, replay, verify

The same package installs the CLI:

```bash
agentwatch init            # install Claude Code hooks + start the local daemon
agentwatch sessions        # list recorded sessions
agentwatch replay <id>     # reconstruct a session's action timeline
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](https://github.com/agentsec-ecosystem/agentwatch/blob/main/docs/reference/sdk.md)
- [User guide](https://github.com/agentsec-ecosystem/agentwatch/blob/main/docs/guides/user-guide.md)
- [Record format spec](https://github.com/agentsec-ecosystem/agentwatch/blob/main/docs/reference/record-format-spec.md)
- [Docs index](https://github.com/agentsec-ecosystem/agentwatch/blob/main/docs/README.md)
- [Changelog](https://github.com/agentsec-ecosystem/agentwatch/blob/main/CHANGELOG.md) ·
  [Security policy](https://github.com/agentsec-ecosystem/agentwatch/blob/main/SECURITY.md) ·
  [Issues](https://github.com/agentsec-ecosystem/agentwatch/issues)

## License

Apache-2.0 — see [LICENSE](https://github.com/agentsec-ecosystem/agentwatch/blob/main/LICENSE).
