# AgentLens

> AgentLens is an open-source agent observability platform that traces AI agent decisions, not just API calls. It captures why agents choose specific tools, routes, or strategies — providing visibility into the reasoning behind every action.

AgentLens helps engineering teams debug, monitor, and improve AI agent applications in production. Unlike traditional LLM observability tools that only trace API calls, AgentLens captures the decision-making process: tool selection rationale, routing logic, retry strategies, and planning steps. It includes a real-time dashboard with decision tree visualization, cost analytics, and token tracking.

## Getting Started

- [Documentation](https://agentlens.vectry.tech/docs): Full docs covering SDKs, integrations, API reference, and self-hosting
- [Quick Start](https://agentlens.vectry.tech/docs/getting-started): Install, initialize, and send your first trace in 5 minutes
- [GitHub Repository](https://gitea.repi.fun/repi/agentlens): Source code and issues
- [PyPI Package](https://pypi.org/project/vectry-agentlens/): Install with `pip install vectry-agentlens`
- [npm Package (SDK)](https://www.npmjs.com/package/agentlens-sdk): Install with `npm install agentlens-sdk`
- [npm Package (OpenCode Plugin)](https://www.npmjs.com/package/opencode-agentlens): Install with `npm install opencode-agentlens`
- [Dashboard](https://agentlens.vectry.tech/dashboard): Live dashboard with real-time traces

## Python SDK

- [Python SDK Reference](https://agentlens.vectry.tech/docs/python-sdk): init(), @trace decorator, log_decision(), TraceContext, configuration
- [Basic Usage](https://gitea.repi.fun/repi/agentlens/src/branch/main/examples/basic_agent.py): Minimal SDK usage with trace context and decision logging
- [OpenAI Integration](https://gitea.repi.fun/repi/agentlens/src/branch/main/examples/openai_agent.py): Wrap OpenAI client for automatic LLM call tracing
- [Multi-Agent Example](https://gitea.repi.fun/repi/agentlens/src/branch/main/examples/multi_agent.py): Nested multi-agent workflow tracing

## TypeScript SDK

- [TypeScript SDK Reference](https://agentlens.vectry.tech/docs/typescript-sdk): init(), TraceBuilder, createDecision(), BatchTransport
- Install with `npm install agentlens-sdk`

## OpenCode Plugin

- [OpenCode Plugin Docs](https://agentlens.vectry.tech/docs/opencode-plugin): Capture coding agent sessions, tool calls, LLM calls, permission flows, and file edits
- Install with `npm install opencode-agentlens`
- Configure via AGENTLENS_API_KEY and AGENTLENS_ENDPOINT environment variables

## Key Concepts

- [Concepts](https://agentlens.vectry.tech/docs/concepts): Traces, Spans, Decision Points, Events explained
- **Traces**: Top-level containers for agent execution sessions, with tags and metadata
- **Spans**: Individual operations within a trace (LLM calls, tool calls, chain steps)
- **Decision Points**: The core differentiator — captures what was chosen, what alternatives existed, and why
- **Decision Types**: TOOL_SELECTION, ROUTING, RETRY, ESCALATION, MEMORY_RETRIEVAL, PLANNING, CUSTOM

## API

- [API Reference](https://agentlens.vectry.tech/docs/api-reference): Full REST API contract
- POST /api/traces: Batch ingest traces from SDK (Bearer token auth)
- GET /api/traces: List traces with pagination, search, filters, and sorting
- GET /api/traces/:id: Get single trace with all spans, decisions, and events
- GET /api/traces/stream: Server-Sent Events for real-time trace updates
- GET /api/health: Health check endpoint

## Integrations

- [OpenAI Integration](https://agentlens.vectry.tech/docs/integrations/openai): `wrap_openai(client)` auto-instruments chat completions, streaming, and tool calls
- [Anthropic Integration](https://agentlens.vectry.tech/docs/integrations/anthropic): `wrap_anthropic(client)` auto-instruments Claude API calls
- [LangChain Integration](https://agentlens.vectry.tech/docs/integrations/langchain): `AgentLensCallbackHandler` captures chains, agents, tools, and LLM calls
- **Any Python Code**: `@trace` decorator and `log_decision()` for custom instrumentation

## Self-Hosting

- [Self-Hosting Guide](https://agentlens.vectry.tech/docs/self-hosting): Docker, docker-compose, env vars, reverse proxy
- Docker Compose deployment with PostgreSQL and Redis
- Single `docker compose up -d` to run
- Environment variables: DATABASE_URL, REDIS_URL, AGENTLENS_API_KEY

## Optional

- [Company Website](https://vectry.tech): Built by Vectry, an engineering-first AI consultancy
- [CodeBoard](https://codeboard.vectry.tech): Sister product — understand any codebase in 5 minutes