{"_id":"@agentkitai/agentlens-sdk","_rev":"3-456263263a3bc5b87c3954cc1cb4f706","name":"@agentkitai/agentlens-sdk","dist-tags":{"latest":"0.14.6"},"versions":{"0.14.4":{"name":"@agentkitai/agentlens-sdk","version":"0.14.4","keywords":["agentlens","ai-agents","observability","sdk","client","typescript","api-client"],"author":{"name":"Amit Paz"},"license":"MIT","_id":"@agentkitai/agentlens-sdk@0.14.4","maintainers":[{"name":"amit-paz","email":"amit.paz@gmail.com"}],"homepage":"https://github.com/agentkitai/agentlens/tree/main/packages/sdk","bugs":{"url":"https://github.com/agentkitai/agentlens/issues"},"dist":{"shasum":"9eb6b43229f4b32b3fbbde48eb35057c5b5516db","tarball":"https://registry.npmjs.org/@agentkitai/agentlens-sdk/-/agentlens-sdk-0.14.4.tgz","fileCount":91,"integrity":"sha512-UBgOq/sOXhkDNWy+w/jUn3shpIme4Azbe5uPz+/++TMYPwJ6Vsn9E6u7RkP2B0uSSaUVe+bGdL/jjNUHVtilww==","signatures":[{"sig":"MEUCIAM7lVXRC6ZXC7DzQa6inf69rY9Zpd73s/JBhFGGPQ8bAiEAu4bLxrbz9K9DCqKTrVfePDpAV+piO31ThKxY+R74EFg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":230956},"main":"./dist/index.js","type":"module","_from":"file:agentkitai-agentlens-sdk-0.14.4.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc -b --watch","test":"vitest run","build":"tsc -b","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"amit-paz","email":"amit.paz@gmail.com"},"_resolved":"C:\\Users\\amitp\\AppData\\Local\\Temp\\2ddda6944dde81d4a5af0cc53ff20953\\agentkitai-agentlens-sdk-0.14.4.tgz","_integrity":"sha512-UBgOq/sOXhkDNWy+w/jUn3shpIme4Azbe5uPz+/++TMYPwJ6Vsn9E6u7RkP2B0uSSaUVe+bGdL/jjNUHVtilww==","repository":{"url":"git+https://github.com/agentkitai/agentlens.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.5.2","description":"TypeScript SDK for the AgentLens API — programmatic access to agent observability data","directories":{},"_nodeVersion":"24.12.0","dependencies":{"@agentkitai/agentlens-core":"0.18.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agentlens-sdk_0.14.4_1782494649612_0.2252860223530726","host":"s3://npm-registry-packages-npm-production"}},"0.14.5":{"name":"@agentkitai/agentlens-sdk","version":"0.14.5","keywords":["agentlens","ai-agents","observability","sdk","client","typescript","api-client"],"author":{"name":"Amit Paz"},"license":"MIT","_id":"@agentkitai/agentlens-sdk@0.14.5","maintainers":[{"name":"amit-paz","email":"amit.paz@gmail.com"}],"homepage":"https://github.com/agentkitai/agentlens/tree/main/packages/sdk","bugs":{"url":"https://github.com/agentkitai/agentlens/issues"},"dist":{"shasum":"180d5d80b4e905b0daf8a4f91c035c68216e4b89","tarball":"https://registry.npmjs.org/@agentkitai/agentlens-sdk/-/agentlens-sdk-0.14.5.tgz","fileCount":91,"integrity":"sha512-i7vS1jaxk4gnjRWwAcLXvJJq8J2xy3efQAdb7sm2dbUaBNqqZuExvivTYtc4LtDWPiLAFD9Vbcdxwvak+B4IAw==","signatures":[{"sig":"MEYCIQCMuKENC7qx/yh2BkV5bbFE2MmIjvQSez+BeL6oRwSL/AIhAI4V8Qnef2JSldrMH9b3cHFPMlV6YdB3hFnVgrA5ZLMN","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentkitai%2fagentlens-sdk@0.14.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":230704},"main":"./dist/index.js","type":"module","_from":"file:agentkitai-agentlens-sdk-0.14.5.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc -b --watch","test":"vitest run","build":"tsc -b","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:db4db9f0-7350-4edb-8833-3bc30e203769"}},"_resolved":"/tmp/2a52e9bfe12b895c2e929ab8e618fa16/agentkitai-agentlens-sdk-0.14.5.tgz","_integrity":"sha512-i7vS1jaxk4gnjRWwAcLXvJJq8J2xy3efQAdb7sm2dbUaBNqqZuExvivTYtc4LtDWPiLAFD9Vbcdxwvak+B4IAw==","repository":{"url":"git+https://github.com/agentkitai/agentlens.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.17.0","description":"TypeScript SDK for the AgentLens API — programmatic access to agent observability data","directories":{},"_nodeVersion":"22.23.0","dependencies":{"@agentkitai/agentlens-core":"0.19.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agentlens-sdk_0.14.5_1782578318743_0.22538072462334435","host":"s3://npm-registry-packages-npm-production"}},"0.14.6":{"name":"@agentkitai/agentlens-sdk","version":"0.14.6","description":"TypeScript SDK for the AgentLens API — programmatic access to agent observability data","type":"module","license":"MIT","author":{"name":"Amit Paz"},"repository":{"type":"git","url":"git+https://github.com/agentkitai/agentlens.git","directory":"packages/sdk"},"homepage":"https://github.com/agentkitai/agentlens/tree/main/packages/sdk","bugs":{"url":"https://github.com/agentkitai/agentlens/issues"},"keywords":["agentlens","ai-agents","observability","sdk","client","typescript","api-client"],"exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"main":"./dist/index.js","types":"./dist/index.d.ts","dependencies":{"@agentkitai/agentlens-core":"0.20.0"},"scripts":{"build":"tsc -b","dev":"tsc -b --watch","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest"},"_id":"@agentkitai/agentlens-sdk@0.14.6","_integrity":"sha512-YGt0MnAjrm0xP+jzjb7YAESdGBiFXRZnYi/T94Yjf5mKFFTNq8+np3S/uu+j0WbhT50ZYhS1jf5276fxmq1tLA==","_resolved":"/tmp/34c30f82a4c67b5b2ffcc16a20d9084f/agentkitai-agentlens-sdk-0.14.6.tgz","_from":"file:agentkitai-agentlens-sdk-0.14.6.tgz","_nodeVersion":"22.23.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-YGt0MnAjrm0xP+jzjb7YAESdGBiFXRZnYi/T94Yjf5mKFFTNq8+np3S/uu+j0WbhT50ZYhS1jf5276fxmq1tLA==","shasum":"da683e0b86a963be1f1c03a1ce1530634042e783","tarball":"https://registry.npmjs.org/@agentkitai/agentlens-sdk/-/agentlens-sdk-0.14.6.tgz","fileCount":91,"unpackedSize":230704,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentkitai%2fagentlens-sdk@0.14.6","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCnfMvEBG9QW7woEm8p0lSHFw2IwIi+4oaD5g8YKlDqZQIhALnCp/IFy0VyXT1Zd7ETSHWOsmjkqC6OwzqUmY1QqQtp"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:db4db9f0-7350-4edb-8833-3bc30e203769"}},"directories":{},"maintainers":[{"name":"amit-paz","email":"amit.paz@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentlens-sdk_0.14.6_1782581614692_0.4397991504940171"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-26T17:24:09.444Z","modified":"2026-06-27T17:33:35.100Z","0.14.4":"2026-06-26T17:24:09.761Z","0.14.5":"2026-06-27T16:38:38.897Z","0.14.6":"2026-06-27T17:33:34.826Z"},"bugs":{"url":"https://github.com/agentkitai/agentlens/issues"},"author":{"name":"Amit Paz"},"license":"MIT","homepage":"https://github.com/agentkitai/agentlens/tree/main/packages/sdk","keywords":["agentlens","ai-agents","observability","sdk","client","typescript","api-client"],"repository":{"type":"git","url":"git+https://github.com/agentkitai/agentlens.git","directory":"packages/sdk"},"description":"TypeScript SDK for the AgentLens API — programmatic access to agent observability data","maintainers":[{"name":"amit-paz","email":"amit.paz@gmail.com"}],"readme":"# @agentkitai/agentlens-sdk\n\nTypeScript SDK for the AgentLens observability API.\n\n## Installation\n\n```bash\nnpm install @agentkitai/agentlens-sdk\n```\n\n## Quick Start\n\n```ts\nimport { AgentLensClient } from '@agentkitai/agentlens-sdk';\n\nconst client = AgentLensClient.fromEnv();\n\n// Check server health\nconst health = await client.health();\nconsole.log(health.status); // \"ok\"\n\n// Query events\nconst { events, total } = await client.queryEvents({\n  agentId: 'my-agent',\n  limit: 10,\n});\n```\n\n## Configuration\n\n### `fromEnv()` — Zero-Config Setup\n\n```ts\nconst client = AgentLensClient.fromEnv();\n```\n\nReads from environment variables:\n\n| Env Var | Default | Description |\n|---------|---------|-------------|\n| `AGENTLENS_SERVER_URL` | `http://localhost:3400` | Server URL |\n| `AGENTLENS_API_KEY` | — | API key |\n\nOverride any value:\n\n```ts\nconst client = AgentLensClient.fromEnv({\n  url: 'https://api.agentlens.ai',\n  apiKey: 'als_xxx',\n});\n```\n\n### Constructor Options\n\n```ts\nconst client = new AgentLensClient({\n  url: 'http://localhost:3400',\n  apiKey: 'als_xxx',\n  timeout: 30_000,\n  retry: { maxRetries: 3, backoffBaseMs: 1000, backoffMaxMs: 30000 },\n  failOpen: false,\n  onError: (err) => console.warn(err.message),\n});\n```\n\n## Retry Configuration\n\nBuilt-in exponential backoff with jitter. Retries on:\n- Network errors / timeouts\n- `429 Too Many Requests` (respects `Retry-After` header)\n- `503 Service Unavailable` (backpressure)\n\nNever retries: `400`, `401`, `402`, `404`.\n\n```ts\nconst client = new AgentLensClient({\n  url: 'http://localhost:3400',\n  retry: {\n    maxRetries: 5,\n    backoffBaseMs: 500,\n    backoffMaxMs: 60_000,\n  },\n});\n```\n\n## Fail-Open Mode\n\nWhen `failOpen: true`, all methods catch errors and return safe defaults (`undefined`) instead of throwing. Ideal for production where observability should never crash your app.\n\n```ts\nconst client = new AgentLensClient({\n  url: 'http://localhost:3400',\n  failOpen: true,\n  onError: (err) => myLogger.warn('AgentLens error:', err.message),\n});\n\n// This won't throw even if the server is down\nconst events = await client.queryEvents({ agentId: 'my-agent' });\n```\n\n## Error Handling\n\nAll errors extend `AgentLensError`:\n\n```ts\nimport {\n  AgentLensError,\n  AuthenticationError,   // 401\n  NotFoundError,         // 404\n  ValidationError,       // 400\n  ConnectionError,       // network/timeout\n  RateLimitError,        // 429 (has .retryAfter)\n  QuotaExceededError,    // 402\n  BackpressureError,     // 503\n} from '@agentkitai/agentlens-sdk';\n\ntry {\n  await client.getEvent('bad-id');\n} catch (err) {\n  if (err instanceof NotFoundError) {\n    console.log('Event not found');\n  } else if (err instanceof RateLimitError) {\n    console.log(`Retry after ${err.retryAfter}s`);\n  }\n}\n```\n\n## API Reference\n\n### Events\n\n| Method | Description |\n|--------|-------------|\n| `queryEvents(query?)` | Query events with filters and pagination |\n| `getEvent(id)` | Get a single event by ID |\n\n### Sessions\n\n| Method | Description |\n|--------|-------------|\n| `getSessions(query?)` | Query sessions with filters |\n| `getSession(id)` | Get a single session |\n| `getSessionTimeline(sessionId)` | Full event timeline with hash chain verification |\n\n### LLM Call Tracking\n\n| Method | Description |\n|--------|-------------|\n| `logLlmCall(sessionId, agentId, params)` | Log a complete LLM call (request + response). Supports `redact: true` |\n| `getLlmAnalytics(params?)` | Aggregate metrics by model, time, provider |\n\n```ts\nconst { callId } = await client.logLlmCall('session-1', 'my-agent', {\n  provider: 'openai',\n  model: 'gpt-4',\n  messages: [{ role: 'user', content: 'Hello' }],\n  completion: 'Hi there!',\n  finishReason: 'stop',\n  usage: { inputTokens: 5, outputTokens: 3, totalTokens: 8 },\n  costUsd: 0.001,\n  latencyMs: 450,\n  redact: false,\n});\n```\n\n### Recall (Semantic Search)\n\n| Method | Description |\n|--------|-------------|\n| `recall(query)` | Semantic search over embeddings |\n\n### Reflect (Pattern Analysis)\n\n| Method | Description |\n|--------|-------------|\n| `reflect(query)` | Analyze patterns across sessions |\n\n### Context\n\n| Method | Description |\n|--------|-------------|\n| `getContext(query)` | Cross-session context for a topic |\n\n### Agents & Health\n\n| Method | Description |\n|--------|-------------|\n| `getAgent(agentId)` | Get agent details |\n| `getHealth(agentId, window?)` | Health score for an agent |\n| `getHealthOverview(window?)` | Health overview for all agents |\n| `getHealthHistory(agentId, days?)` | Historical health snapshots |\n\n### Optimization\n\n| Method | Description |\n|--------|-------------|\n| `getOptimizationRecommendations(options?)` | Cost optimization recommendations |\n\n### Guardrails\n\n| Method | Description |\n|--------|-------------|\n| `listGuardrails(options?)` | List all guardrail rules |\n| `getGuardrail(id)` | Get a guardrail rule |\n| `createGuardrail(params)` | Create a guardrail rule |\n| `updateGuardrail(id, updates)` | Update a guardrail rule |\n| `deleteGuardrail(id)` | Delete a guardrail rule |\n| `enableGuardrail(id)` | Enable a guardrail rule |\n| `disableGuardrail(id)` | Disable a guardrail rule |\n| `getGuardrailHistory(options?)` | Trigger history |\n| `getGuardrailStatus(id)` | Status + recent triggers |\n\n### Server\n\n| Method | Description |\n|--------|-------------|\n| `health()` | Server health check (no auth) |\n\n## Lessons API (Deprecated)\n\nLesson methods have been removed. Use [lore-sdk](https://github.com/agentkitai/lore) directly.\n\n```ts\n// ❌ Old\nawait client.createLesson(...); // throws\n\n// ✅ New\nimport { LoreClient } from 'lore-sdk';\nconst lore = new LoreClient();\nawait lore.createLesson(...);\n```\n","readmeFilename":"README.md"}