diff --git a/apps/web/public/llms.txt b/apps/web/public/llms.txt index 4216dc2..ac1f549 100644 --- a/apps/web/public/llms.txt +++ b/apps/web/public/llms.txt @@ -6,19 +6,35 @@ AgentLens helps engineering teams debug, monitor, and improve AI agent applicati ## Getting Started -- [GitHub Repository](https://gitea.repi.fun/repi/agentlens): Source code, issues, and contribution guide +- [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` -- [Dashboard](https://agentlens.vectry.tech/dashboard): Live demo dashboard with sample traces +- [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 -- [Function Calling](https://gitea.repi.fun/repi/agentlens/src/branch/main/examples/moonshot_real_test.py): Real LLM test with tool/function calling + +## 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 @@ -26,6 +42,7 @@ AgentLens helps engineering teams debug, monitor, and improve AI agent applicati ## 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 @@ -34,12 +51,14 @@ AgentLens helps engineering teams debug, monitor, and improve AI agent applicati ## Integrations -- **OpenAI**: `wrap_openai(client)` auto-instruments all chat completions, streaming, and tool calls -- **LangChain**: `AgentLensCallbackHandler` captures chains, agents, tools, and LLM calls +- [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 diff --git a/apps/web/src/app/page.tsx b/apps/web/src/app/page.tsx index d57f8fe..b9f3c24 100644 --- a/apps/web/src/app/page.tsx +++ b/apps/web/src/app/page.tsx @@ -37,9 +37,12 @@ export default function HomePage() { "Agent Decision Tracing", "Real-time Dashboard", "OpenAI Integration", + "Anthropic Integration", "LangChain Integration", + "OpenCode Plugin", "Self-hosting Support", "Python SDK", + "TypeScript SDK", ], }), }} diff --git a/apps/web/src/app/sitemap.ts b/apps/web/src/app/sitemap.ts index 85a6340..2c78ff8 100644 --- a/apps/web/src/app/sitemap.ts +++ b/apps/web/src/app/sitemap.ts @@ -2,8 +2,21 @@ import { MetadataRoute } from "next"; export default function sitemap(): MetadataRoute.Sitemap { const baseUrl = "https://agentlens.vectry.tech"; + const now = new Date(); + return [ - { url: baseUrl, lastModified: new Date(), changeFrequency: "weekly", priority: 1.0 }, - { url: `${baseUrl}/dashboard`, lastModified: new Date(), changeFrequency: "daily", priority: 0.8 }, + { url: baseUrl, lastModified: now, changeFrequency: "weekly", priority: 1.0 }, + { url: `${baseUrl}/dashboard`, lastModified: now, changeFrequency: "daily", priority: 0.8 }, + { url: `${baseUrl}/docs`, lastModified: now, changeFrequency: "weekly", priority: 0.9 }, + { url: `${baseUrl}/docs/getting-started`, lastModified: now, changeFrequency: "monthly", priority: 0.9 }, + { url: `${baseUrl}/docs/concepts`, lastModified: now, changeFrequency: "monthly", priority: 0.7 }, + { url: `${baseUrl}/docs/python-sdk`, lastModified: now, changeFrequency: "monthly", priority: 0.8 }, + { url: `${baseUrl}/docs/typescript-sdk`, lastModified: now, changeFrequency: "monthly", priority: 0.8 }, + { url: `${baseUrl}/docs/opencode-plugin`, lastModified: now, changeFrequency: "monthly", priority: 0.8 }, + { url: `${baseUrl}/docs/integrations/openai`, lastModified: now, changeFrequency: "monthly", priority: 0.7 }, + { url: `${baseUrl}/docs/integrations/anthropic`, lastModified: now, changeFrequency: "monthly", priority: 0.7 }, + { url: `${baseUrl}/docs/integrations/langchain`, lastModified: now, changeFrequency: "monthly", priority: 0.7 }, + { url: `${baseUrl}/docs/api-reference`, lastModified: now, changeFrequency: "monthly", priority: 0.7 }, + { url: `${baseUrl}/docs/self-hosting`, lastModified: now, changeFrequency: "monthly", priority: 0.7 }, ]; } diff --git a/packages/opencode-plugin/README.md b/packages/opencode-plugin/README.md new file mode 100644 index 0000000..b6d6432 --- /dev/null +++ b/packages/opencode-plugin/README.md @@ -0,0 +1,88 @@ +# opencode-agentlens + +OpenCode plugin for AgentLens — trace your coding agent's decisions, tool calls, and sessions. + +[![npm version](https://img.shields.io/npm/v/opencode-agentlens.svg)](https://www.npmjs.com/package/opencode-agentlens) +[![license](https://img.shields.io/npm/l/opencode-agentlens.svg)](https://github.com/repi/agentlens/blob/main/LICENSE) + +## Requirements + +- OpenCode >= 1.1.0 + +## Install + +```bash +npm install opencode-agentlens +``` + +## Configuration + +### Environment Variables + +| Variable | Required | Default | Description | +|---|---|---|---| +| `AGENTLENS_API_KEY` | Yes | — | Your AgentLens API key. | +| `AGENTLENS_ENDPOINT` | No | AgentLens cloud | API endpoint URL. | +| `AGENTLENS_ENABLED` | No | `true` | Set to `false` to disable tracing. | +| `AGENTLENS_CAPTURE_CONTENT` | No | `true` | Capture message and tool output content. | +| `AGENTLENS_MAX_OUTPUT_LENGTH` | No | `10000` | Max characters to capture per output. | +| `AGENTLENS_FLUSH_INTERVAL` | No | `5000` | Flush interval in milliseconds. | +| `AGENTLENS_BATCH_SIZE` | No | `100` | Max items per batch before auto-flush. | + +### OpenCode Setup + +Add the plugin to your OpenCode configuration at `~/.config/opencode/opencode.json`: + +```json +{ + "plugins": [ + { + "name": "agentlens", + "module": "opencode-agentlens" + } + ] +} +``` + +Set your API key: + +```bash +export AGENTLENS_API_KEY="your-api-key" +``` + +The plugin activates automatically when OpenCode starts. No code changes required. + +## What Gets Captured + +The plugin hooks into OpenCode's event system and records: + +- **Sessions** — Full session lifecycle from start to finish, including duration and metadata. +- **Tool calls** — Every tool invocation with input arguments and output results (e.g., file reads, shell commands, code edits). +- **LLM calls** — Chat messages sent to and received from the model, including token usage. +- **Permission flows** — When the agent requests permission and whether it was granted or denied. +- **File edits** — File paths and change summaries produced by the agent. + +All data is sent to your AgentLens instance where you can inspect traces, replay sessions, and analyze agent behavior. + +## How It Works + +The plugin registers handlers for OpenCode's event hooks: + +| Event | What is recorded | +|---|---| +| Session start/end | Trace lifecycle, session metadata | +| `tool.execute.before` | Tool name, input arguments | +| `tool.execute.after` | Tool output, duration, success/failure | +| `chat.message` | LLM responses and assistant messages | +| `chat.params` | Model parameters and prompt configuration | +| `permission.ask` | Permission requests and user decisions | + +Each OpenCode session maps to a single AgentLens trace. Tool calls and LLM interactions become spans within that trace. + +## Documentation + +Full documentation: [agentlens.vectry.tech/docs/opencode-plugin](https://agentlens.vectry.tech/docs/opencode-plugin) + +## License + +MIT diff --git a/packages/opencode-plugin/package.json b/packages/opencode-plugin/package.json index 219789c..be37e46 100644 --- a/packages/opencode-plugin/package.json +++ b/packages/opencode-plugin/package.json @@ -43,5 +43,15 @@ "tracing", "coding-agent" ], - "license": "MIT" + "license": "MIT", + "author": "Vectry ", + "repository": { + "type": "git", + "url": "https://gitea.repi.fun/repi/agentlens", + "directory": "packages/opencode-plugin" + }, + "homepage": "https://agentlens.vectry.tech", + "bugs": { + "url": "https://gitea.repi.fun/repi/agentlens/issues" + } } diff --git a/packages/sdk-ts/README.md b/packages/sdk-ts/README.md new file mode 100644 index 0000000..4cd63b6 --- /dev/null +++ b/packages/sdk-ts/README.md @@ -0,0 +1,124 @@ +# agentlens-sdk + +TypeScript SDK for AgentLens — Agent observability that traces decisions, not just API calls. + +[![npm version](https://img.shields.io/npm/v/agentlens-sdk.svg)](https://www.npmjs.com/package/agentlens-sdk) +[![license](https://img.shields.io/npm/l/agentlens-sdk.svg)](https://github.com/repi/agentlens/blob/main/LICENSE) + +## Install + +```bash +npm install agentlens-sdk +``` + +## Quick Start + +```typescript +import { init, TraceBuilder, shutdown } from "agentlens-sdk"; + +// Initialize the SDK +init({ + apiKey: "your-api-key", + endpoint: "https://agentlens.vectry.tech/api", +}); + +// Create a trace +const trace = new TraceBuilder("agent-run-123", "My Agent Task"); + +// Add a span (tool call, LLM call, etc.) +trace.addSpan({ + name: "search-documents", + type: "tool", + input: { query: "quarterly report" }, + output: { results: 5 }, +}); + +// Record a decision point +trace.addDecision({ + name: "select-tool", + type: "tool_selection", + options: ["search", "calculate", "summarize"], + selected: "search", + reasoning: "User asked for document lookup", +}); + +// Finalize and send +await trace.end(); + +// Flush remaining data before exit +await shutdown(); +``` + +## API Reference + +### Core Functions + +| Function | Description | +|---|---| +| `init(options)` | Initialize the SDK with your API key and configuration. | +| `shutdown()` | Flush pending data and shut down the transport. | +| `flush()` | Manually flush the current batch without shutting down. | +| `getClient()` | Return the initialized client instance. | + +### TraceBuilder + +The primary interface for constructing traces. + +```typescript +const trace = new TraceBuilder(traceId: string, name: string); + +trace.addSpan(span: SpanPayload); // Add a span to the trace +trace.addDecision(decision: DecisionPointPayload); // Record a decision point +trace.end(): Promise; // Finalize and send the trace +``` + +### Standalone Helpers + +| Function | Description | +|---|---| +| `createDecision(decision)` | Create and send a standalone decision point outside a trace. | + +## Types + +Core payload types used throughout the SDK: + +- **`TracePayload`** — Top-level trace structure containing spans and metadata. +- **`SpanPayload`** — Individual unit of work (tool call, LLM request, retrieval, etc.). +- **`DecisionPointPayload`** — A recorded decision: what options existed, what was chosen, and why. +- **`EventPayload`** — Discrete event within a span or trace. +- **`JsonValue`** — Flexible JSON-compatible value type for inputs/outputs. + +## Enums + +| Enum | Values | +|---|---| +| `TraceStatus` | Status of the overall trace (e.g., running, completed, failed). | +| `SpanType` | Category of span (e.g., tool, llm, retrieval). | +| `SpanStatus` | Status of an individual span. | +| `DecisionType` | Category of decision (e.g., tool_selection, routing). | +| `EventType` | Category of event within a span. | + +## Configuration + +Pass `InitOptions` to `init()`: + +```typescript +init({ + apiKey: "your-api-key", // Required. Your AgentLens API key. + endpoint: "https://...", // API endpoint. Defaults to AgentLens cloud. + maxBatchSize: 100, // Max items per batch before auto-flush. + flushInterval: 5000, // Auto-flush interval in milliseconds. +}); +``` + +## Transport + +The SDK ships with `BatchTransport`, which batches payloads and flushes them on an interval or when the batch size threshold is reached. This is used internally by `init()` — you typically do not need to instantiate it directly. + +## Documentation + +Full documentation: [agentlens.vectry.tech/docs/typescript-sdk](https://agentlens.vectry.tech/docs/typescript-sdk) + +## License + +MIT diff --git a/packages/sdk-ts/package.json b/packages/sdk-ts/package.json index b373f80..7bebb62 100644 --- a/packages/sdk-ts/package.json +++ b/packages/sdk-ts/package.json @@ -31,6 +31,24 @@ "node": ">=20" }, "license": "MIT", + "author": "Vectry ", + "repository": { + "type": "git", + "url": "https://gitea.repi.fun/repi/agentlens", + "directory": "packages/sdk-ts" + }, + "homepage": "https://agentlens.vectry.tech", + "bugs": { + "url": "https://gitea.repi.fun/repi/agentlens/issues" + }, + "keywords": [ + "agentlens", + "observability", + "tracing", + "ai-agents", + "sdk", + "typescript" + ], "devDependencies": { "tsup": "^8.3.0", "typescript": "^5.7.0"