{"_id":"@agentwatch-beta/sdk","_rev":"2-647f91d1ea3f950a77ce34b4f58f4dd2","name":"@agentwatch-beta/sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agentwatch-beta/sdk","version":"0.1.0","keywords":["agentwatch","llm","monitoring","drift","ai-agents","observability"],"license":"MIT","_id":"@agentwatch-beta/sdk@0.1.0","maintainers":[{"name":"pheneron","email":"business.pheneron@gmail.com"}],"dist":{"shasum":"d5282240a70865c49c47962d378065b3c0f5311b","tarball":"https://registry.npmjs.org/@agentwatch-beta/sdk/-/sdk-0.1.0.tgz","fileCount":7,"integrity":"sha512-fSHQcJUPGp84aYLw/5Rk6ojY+xpT+EGo6hEDEtBWkohoUaEasNG1UD4NbH8LY+A/Bp9pk4w+HFcVw34CeXEqEw==","signatures":[{"sig":"MEUCIQC27HzYbI/0kEaOQuC/0ICbNG6G0a5JHhsNwrRLS7zOnQIgf7M/02L71otKRwuiWL0obDmFZvoM5oQ9H21QYQRxuTo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22118},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","//files":"Only the public client bundle is published. dist/internal.* (the engine) is deliberately NOT listed, so it stays out of the npm tarball while remaining available to workspace consumers on disk.","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./internal":{"types":"./dist/internal.d.ts","import":"./dist/internal.js","require":"./dist/internal.cjs"}},"gitHead":"9fb7d795ec852d3b14ffe5b2049799dabdd6587f","scripts":{"dev":"tsup --watch","test":"jest","build":"tsup","typecheck":"tsc --noEmit","test:watch":"jest --watch","test:coverage":"jest --coverage","test:judge:live":"jest judge.integration --testPathIgnorePatterns=/node_modules/"},"_npmUser":{"name":"pheneron","email":"business.pheneron@gmail.com"},"_npmVersion":"10.8.3","description":"Zero-overhead drift monitoring SDK for AI agents","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"packageManager":"pnpm@10.18.0","devDependencies":{"jest":"^29.7.0","tsup":"^8.5.1","dotenv":"^16.6.1","ts-jest":"^29.4.0","typescript":"^6.0.3","@types/jest":"^29.5.14","@types/node":"^22.19.21"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1784931808180_0.9840530441067026","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentwatch-beta/sdk","version":"0.1.1","description":"Zero-overhead drift monitoring SDK for AI agents","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","test:judge:live":"jest judge.integration --testPathIgnorePatterns=/node_modules/"},"keywords":["agentwatch","llm","monitoring","drift","ai-agents","observability"],"license":"MIT","engines":{"node":">=18.0.0"},"packageManager":"pnpm@10.18.0","devDependencies":{"@types/jest":"^29.5.14","@types/node":"^22.19.21","dotenv":"^16.6.1","jest":"^29.7.0","ts-jest":"^29.4.0","tsup":"^8.5.1","typescript":"^6.0.3"},"_id":"@agentwatch-beta/sdk@0.1.1","gitHead":"5f72d457bfdec57bc2659c212cc645f6bd51ca64","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-Lm/sMBXyAEcA+1JKPzMV3eFLXzLmvv6fXcEHgdMfS9CAeWsrm9VVhlXXY49x23sKJkcqSk25szzuNtozPkOiGQ==","shasum":"285c8f99afed049d23f0e02967afec85513920e5","tarball":"https://registry.npmjs.org/@agentwatch-beta/sdk/-/sdk-0.1.1.tgz","fileCount":6,"unpackedSize":56614,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCDVW80d+ua/jbIFGQZ6y9EjxhkpcFIjFuqKSoL0ncSRAIhAImyKS4xeR7Qq68uaR0TSTWe80YKMGqd/4gwWuS12QQ8"}]},"_npmUser":{"name":"pheneron","email":"business.pheneron@gmail.com"},"directories":{},"maintainers":[{"name":"pheneron","email":"business.pheneron@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.1_1786649152764_0.8074917208478847"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-24T22:23:27.960Z","modified":"2026-08-13T19:25:53.124Z","0.1.0":"2026-07-24T22:23:28.308Z","0.1.1":"2026-08-13T19:25:52.955Z"},"license":"MIT","keywords":["agentwatch","llm","monitoring","drift","ai-agents","observability"],"description":"Zero-overhead drift monitoring SDK for AI agents","maintainers":[{"name":"pheneron","email":"business.pheneron@gmail.com"}],"readme":"# AgentWatch SDK\r\n\r\n**Production monitoring for AI agents.**\r\n\r\nAgentWatch helps you capture and monitor AI agent executions with minimal integration code.\r\n\r\nThe TypeScript/JavaScript SDK wraps your existing async agent functions and automatically captures useful execution data such as inputs, outputs, latency, model information, token usage, tool activity, errors, and metadata.\r\n\r\nMonitoring runs outside your application's critical path. Telemetry failures do not interrupt your agent or change its normal error behavior.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @agentwatch-beta/sdk\r\n```\r\n\r\nUsing pnpm:\r\n\r\n```bash\r\npnpm add @agentwatch-beta/sdk\r\n```\r\n\r\nUsing Yarn:\r\n\r\n```bash\r\nyarn add @agentwatch-beta/sdk\r\n```\r\n\r\n**Requirements:** Node.js 18+\r\n\r\nThe package supports both ESM and CommonJS.\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\nWrap any asynchronous agent function with `watch()`:\r\n\r\n```ts\r\nimport { watch } from '@agentwatch-beta/sdk'\r\n\r\nconst monitoredAgent = watch(myAgent, {\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: 'your-agent-id',\r\n})\r\n\r\nconst result = await monitoredAgent(userInput)\r\n```\r\n\r\nThat's it.\r\n\r\nYour function continues to behave normally while AgentWatch captures its execution in the background.\r\n\r\n---\r\n\r\n## What Gets Captured\r\n\r\nFor each execution, AgentWatch can capture:\r\n\r\n* Input and output\r\n* Execution latency\r\n* Success or error status\r\n* Model information\r\n* Token usage\r\n* Tool usage\r\n* Agent instructions\r\n* Tool-call evidence\r\n* Custom metadata\r\n* Trace and session identifiers\r\n* Timestamp\r\n\r\nThe SDK safely serializes captured values and limits large input and output payloads.\r\n\r\nWhen supported provider response formats are detected, AgentWatch automatically extracts available model, token, output, and tool information.\r\n\r\n---\r\n\r\n## Using `watch()`\r\n\r\nSuppose you already have an agent:\r\n\r\n```ts\r\nasync function supportAgent(question: string) {\r\n  return runSupportWorkflow(question)\r\n}\r\n```\r\n\r\nAdd AgentWatch without changing the function itself:\r\n\r\n```ts\r\nimport { watch } from '@agentwatch-beta/sdk'\r\n\r\nconst monitoredSupportAgent = watch(supportAgent, {\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: 'support-agent',\r\n})\r\n\r\nconst result = await monitoredSupportAgent(\r\n  'Where is my order?',\r\n)\r\n```\r\n\r\nThe first argument passed to the wrapped function is captured as the trace input.\r\n\r\nThe function's returned value is inspected for output and supported telemetry fields.\r\n\r\n---\r\n\r\n## Agent Instructions\r\n\r\nYou can attach the instructions or system behavior your agent is expected to follow:\r\n\r\n```ts\r\nconst monitoredAgent = watch(myAgent, {\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: 'support-agent',\r\n\r\n  agentInstructions: `\r\n    You are a customer support agent.\r\n    Answer using the company knowledge base.\r\n    Never invent order information.\r\n  `,\r\n})\r\n```\r\n\r\nThis gives AgentWatch additional context about the expected behavior of the agent.\r\n\r\n---\r\n\r\n## Metadata\r\n\r\nAttach information that is useful for identifying or grouping executions:\r\n\r\n```ts\r\nconst monitoredAgent = watch(myAgent, {\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: 'support-agent',\r\n\r\n  metadata: {\r\n    environment: 'production',\r\n    version: '2.1.0',\r\n    region: 'us-east',\r\n  },\r\n})\r\n```\r\n\r\nMetadata accepts string, number, and boolean values.\r\n\r\n---\r\n\r\n## Reusable Client\r\n\r\nFor applications with multiple monitored functions, create an `AgentWatchClient` once and reuse its configuration:\r\n\r\n```ts\r\nimport { AgentWatchClient } from '@agentwatch-beta/sdk'\r\n\r\nconst agentwatch = new AgentWatchClient({\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: 'support-agent',\r\n  metadata: {\r\n    environment: 'production',\r\n  },\r\n})\r\n\r\nconst monitoredAgent = agentwatch.watch(myAgent)\r\n\r\nconst result = await monitoredAgent(userInput)\r\n```\r\n\r\nThis is useful when several parts of your application use the same AgentWatch configuration.\r\n\r\n---\r\n\r\n## Manual Traces\r\n\r\nIf your architecture cannot use `watch()`, traces can be submitted manually:\r\n\r\n```ts\r\nimport { AgentWatchClient } from '@agentwatch-beta/sdk'\r\n\r\nconst agentwatch = new AgentWatchClient({\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: 'support-agent',\r\n})\r\n\r\nconst result = await agentwatch.trace({\r\n  input: 'Refund order #47829',\r\n  output: 'The refund has been issued.',\r\n  model: 'your-model',\r\n  latencyMs: 812,\r\n  status: 'success',\r\n\r\n  toolsUsed: [\r\n    'search_orders',\r\n    'issue_refund',\r\n  ],\r\n\r\n  promptTokens: 220,\r\n  completionTokens: 180,\r\n  totalTokens: 400,\r\n\r\n  metadata: {\r\n    environment: 'production',\r\n  },\r\n})\r\n```\r\n\r\nManual submission returns a result describing whether the trace was accepted:\r\n\r\n```ts\r\nif (result.accepted) {\r\n  console.log('Trace accepted')\r\n} else {\r\n  console.log('Trace was not accepted:', result.reason)\r\n}\r\n```\r\n\r\n---\r\n\r\n## Tool-Aware Agents\r\n\r\nAgentWatch can capture tool information when it is available in the agent response.\r\n\r\nFor example, an execution may contain:\r\n\r\n```ts\r\n{\r\n  toolsUsed: [\r\n    'search_knowledge_base',\r\n    'lookup_customer',\r\n    'issue_refund'\r\n  ]\r\n}\r\n```\r\n\r\nSupported response structures can be detected automatically.\r\n\r\nFor custom agent frameworks, you can also provide tool information when submitting traces manually.\r\n\r\n---\r\n\r\n## Error Handling\r\n\r\nWrapping a function does **not** change its normal error behavior.\r\n\r\n```ts\r\nconst monitoredAgent = watch(myAgent, {\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: 'support-agent',\r\n})\r\n\r\ntry {\r\n  await monitoredAgent(userInput)\r\n} catch (error) {\r\n  // Handle the original agent error normally.\r\n}\r\n```\r\n\r\nWhen your agent throws:\r\n\r\n1. AgentWatch captures the failed execution.\r\n2. Monitoring is attempted in the background.\r\n3. The original error is re-thrown.\r\n\r\nYour existing application error handling therefore continues to work normally.\r\n\r\n---\r\n\r\n## Non-Blocking Monitoring\r\n\r\nFor automatically wrapped executions, trace submission is fire-and-forget.\r\n\r\nAgentWatch does not wait for monitoring to complete before returning your agent's result.\r\n\r\nIf telemetry cannot be delivered because of a timeout, network issue, authentication problem, rate limit, or server error, the wrapped application continues running normally.\r\n\r\nMonitoring should never become a dependency of your agent's request path.\r\n\r\n---\r\n\r\n## Configuration\r\n\r\n| Option              | Required | Default | Description                                           |\r\n| ------------------- | -------: | ------- | ----------------------------------------------------- |\r\n| `apiKey`            |      Yes | —       | AgentWatch API key                                    |\r\n| `agentId`           |      Yes | —       | Identifier of the agent being monitored               |\r\n| `agentInstructions` |       No | —       | Instructions describing the agent's expected behavior |\r\n| `metadata`          |       No | `{}`    | Metadata attached to traces                           |\r\n| `maxPreviewLength`  |       No | `5000`  | Maximum captured input/output length                  |\r\n| `timeoutMs`         |       No | `5000`  | Maximum telemetry request duration                    |\r\n| `debug`             |       No | `false` | Enables SDK diagnostic logging                        |\r\n\r\n### Debug Mode\r\n\r\nDebug logging can be enabled during development:\r\n\r\n```ts\r\nconst monitoredAgent = watch(myAgent, {\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: 'development-agent',\r\n  debug: true,\r\n})\r\n```\r\n\r\nKeep debug mode disabled unless you need SDK diagnostics.\r\n\r\n---\r\n\r\n## TypeScript\r\n\r\nAgentWatch ships TypeScript declarations.\r\n\r\n```ts\r\nimport type {\r\n  WatchOptions,\r\n  TracePayload,\r\n  AgentWatchClientOptions,\r\n} from '@agentwatch-beta/sdk'\r\n```\r\n\r\nNo separate `@types` package is required.\r\n\r\n---\r\n\r\n## CommonJS\r\n\r\nCommonJS projects are also supported:\r\n\r\n```js\r\nconst {\r\n  watch,\r\n  AgentWatchClient,\r\n} = require('@agentwatch-beta/sdk')\r\n```\r\n\r\n---\r\n\r\n## Recommended Production Setup\r\n\r\nKeep credentials outside your source code:\r\n\r\n```ts\r\nconst monitoredAgent = watch(myAgent, {\r\n  apiKey: process.env.AGENTWATCH_API_KEY!,\r\n  agentId: process.env.AGENTWATCH_AGENT_ID!,\r\n  metadata: {\r\n    environment: 'production',\r\n  },\r\n})\r\n```\r\n\r\nDo not commit API keys to your repository.\r\n\r\n---\r\n\r\n## API Reference\r\n\r\n### `watch(fn, options)`\r\n\r\nWraps an asynchronous function and automatically captures its executions.\r\n\r\n```ts\r\nconst monitored = watch(fn, options)\r\n```\r\n\r\nThe returned function preserves the arguments, return value, and error behavior of the original async function.\r\n\r\n### `new AgentWatchClient(options)`\r\n\r\nCreates a reusable AgentWatch client.\r\n\r\n```ts\r\nconst agentwatch = new AgentWatchClient(options)\r\n```\r\n\r\n### `agentwatch.watch(fn)`\r\n\r\nWraps an asynchronous function using the client's configuration.\r\n\r\n```ts\r\nconst monitored = agentwatch.watch(fn)\r\n```\r\n\r\n### `agentwatch.trace(payload)`\r\n\r\nManually submits an execution trace.\r\n\r\n```ts\r\nconst result = await agentwatch.trace(payload)\r\n```\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}