{"_id":"@agentsmith-app/staging-sdk","_rev":"8-6d7132e6630c64a475eca9b6f7a8b0dc","name":"@agentsmith-app/staging-sdk","dist-tags":{"latest":"0.0.8-staging.1"},"versions":{"0.0.2-staging.1":{"name":"@agentsmith-app/staging-sdk","version":"0.0.2-staging.1","_id":"@agentsmith-app/staging-sdk@0.0.2-staging.1","maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"homepage":"https://github.com/chad-syntax/agentsmith#readme","bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"dist":{"shasum":"b4531ff28289f08540b5e2dc72c760e02b6e50b0","tarball":"https://registry.npmjs.org/@agentsmith-app/staging-sdk/-/staging-sdk-0.0.2-staging.1.tgz","fileCount":9,"integrity":"sha512-MpLKiWcFU9UWZSLhOmy2MhUNMpESM36BU5J6oAXPgMHakTc5BhajNzemGy+007C7azmB0Oxz2Oz6TgLaZZXtEg==","signatures":[{"sig":"MEUCIQDMTVpqir5yi/YaITppbfRHgOQ2N9s8wwRoeMtepiWEaAIgKY4J5OhoGBfC6+oyG7eGtfaG42uGWVZp2tsvj9d+Kb8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2394799},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"5dc1b32501bb18ec76d39bf8dbc4207d8f5b7346","scripts":{"build":"tsup"},"_npmUser":{"name":"chad_syntax","actor":{"name":"chad_syntax","type":"user","email":"chad@chadsyntax.com"},"email":"chad@chadsyntax.com"},"repository":{"url":"git+https://github.com/chad-syntax/agentsmith.git","type":"git"},"_npmVersion":"10.9.2","description":"Agentsmith TypeScript SDK","directories":{},"_nodeVersion":"22.14.0","dependencies":{"dotenv":"^16.4.7","p-queue":"^8.1.0","nunjucks":"^3.2.4","lodash.merge":"^4.6.2","@supabase/supabase-js":"latest"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.7.2","@types/lodash.merge":"^4.6.9"},"_npmOperationalInternal":{"tmp":"tmp/staging-sdk_0.0.2-staging.1_1751416743954_0.10236417608416937","host":"s3://npm-registry-packages-npm-production"}},"0.0.2-staging.2":{"name":"@agentsmith-app/staging-sdk","version":"0.0.2-staging.2","_id":"@agentsmith-app/staging-sdk@0.0.2-staging.2","maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"homepage":"https://github.com/chad-syntax/agentsmith#readme","bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"dist":{"shasum":"86985cf57c12547e07477ba1e1586afbb7cbfa2d","tarball":"https://registry.npmjs.org/@agentsmith-app/staging-sdk/-/staging-sdk-0.0.2-staging.2.tgz","fileCount":9,"integrity":"sha512-mUv+D2RUgyyKMNWJ+NB54yVm+7K/ilHGxDHXp4CmLu5G7eXaWZ+TE0m1zQKySllmUUiLsPgFk+0I0Px9uw2zYg==","signatures":[{"sig":"MEUCICZfoNH2PRopFYzJO70IiFpOvELaPeZ1YwWJzmkJkuSuAiEAu9Qr8obahqH9K/4CF9bQNmPaK1KTCU3Jg/1dB0qOGpg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2394506},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"653b5eeac8e041bccb8d0e70776365775021a78f","scripts":{"build":"tsup"},"_npmUser":{"name":"chad_syntax","actor":{"name":"chad_syntax","type":"user","email":"chad@chadsyntax.com"},"email":"chad@chadsyntax.com"},"repository":{"url":"git+https://github.com/chad-syntax/agentsmith.git","type":"git"},"_npmVersion":"10.9.2","description":"Agentsmith TypeScript SDK","directories":{},"_nodeVersion":"22.14.0","dependencies":{"dotenv":"^16.4.7","p-queue":"^8.1.0","nunjucks":"^3.2.4","lodash.merge":"^4.6.2","@supabase/supabase-js":"latest"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.7.2","@types/lodash.merge":"^4.6.9"},"_npmOperationalInternal":{"tmp":"tmp/staging-sdk_0.0.2-staging.2_1751486569527_0.3929613934944918","host":"s3://npm-registry-packages-npm-production"}},"0.0.3-staging.1":{"name":"@agentsmith-app/staging-sdk","version":"0.0.3-staging.1","_id":"@agentsmith-app/staging-sdk@0.0.3-staging.1","maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"homepage":"https://github.com/chad-syntax/agentsmith#readme","bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"dist":{"shasum":"b6e3ab2e95c5fa05c31e5c9054f9cb0955ceec28","tarball":"https://registry.npmjs.org/@agentsmith-app/staging-sdk/-/staging-sdk-0.0.3-staging.1.tgz","fileCount":9,"integrity":"sha512-Wf4w13AyyoQyzsbWReDXC9c4WgSADRJNi7FNtQ2MiAVX5P0tydch9ZISzy9TFw1d+l8Zg4sLLrS23M5w8ITzKg==","signatures":[{"sig":"MEQCIGwfnb0mnLe2MRj0Z+THQfEc02AFhwu+jpDvDsutUtNFAiARj0aZ7nWZ4nKaESxp30Yx4UBa98Kj+gjInfmjY25IKQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2394506},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"28342fbfc35cff67c1502fdc1fc8b19cd9790e30","scripts":{"build":"tsup"},"_npmUser":{"name":"chad_syntax","actor":{"name":"chad_syntax","type":"user","email":"chad@chadsyntax.com"},"email":"chad@chadsyntax.com"},"repository":{"url":"git+https://github.com/chad-syntax/agentsmith.git","type":"git"},"_npmVersion":"10.9.2","description":"Agentsmith TypeScript SDK","directories":{},"_nodeVersion":"22.14.0","dependencies":{"dotenv":"^16.4.7","p-queue":"^8.1.0","nunjucks":"^3.2.4","lodash.merge":"^4.6.2","@supabase/supabase-js":"latest"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.7.2","@types/lodash.merge":"^4.6.9"},"_npmOperationalInternal":{"tmp":"tmp/staging-sdk_0.0.3-staging.1_1751486695361_0.6790446494493994","host":"s3://npm-registry-packages-npm-production"}},"0.0.4-staging.1":{"name":"@agentsmith-app/staging-sdk","version":"0.0.4-staging.1","_id":"@agentsmith-app/staging-sdk@0.0.4-staging.1","maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"homepage":"https://github.com/chad-syntax/agentsmith#readme","bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"dist":{"shasum":"2deb06eb5f7678a571cfcb329df61f873edd6135","tarball":"https://registry.npmjs.org/@agentsmith-app/staging-sdk/-/staging-sdk-0.0.4-staging.1.tgz","fileCount":9,"integrity":"sha512-Lxk3b3EP2XjSQkwf7T0Skz5Q/xmfW32MFIDukm0MhCvcl1T9e9Rl4O2jy7JFVkTC9bB2hkNFAut+DZIR9HTdJw==","signatures":[{"sig":"MEQCIAlmBOY4oMEudCV5eIGXm5u2P1UqflaVQETml2RMoP+zAiALGjTSoLJHBv6bl+o5BODs2nJj4qRWOPRBOCs15ju4CQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2395381},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"baa9e229c3056188c2f87e3d99f02550dd6bab4b","scripts":{"build":"tsup"},"_npmUser":{"name":"chad_syntax","email":"chad@chadsyntax.com"},"repository":{"url":"git+https://github.com/chad-syntax/agentsmith.git","type":"git"},"_npmVersion":"10.9.2","description":"Agentsmith TypeScript SDK","directories":{},"_nodeVersion":"22.14.0","dependencies":{"dotenv":"^16.4.7","p-queue":"^8.1.0","nunjucks":"^3.2.4","lodash.merge":"^4.6.2","@supabase/supabase-js":"latest"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.7.2","@types/lodash.merge":"^4.6.9"},"_npmOperationalInternal":{"tmp":"tmp/staging-sdk_0.0.4-staging.1_1752517267739_0.0910452977800642","host":"s3://npm-registry-packages-npm-production"}},"0.0.5-staging.1":{"name":"@agentsmith-app/staging-sdk","version":"0.0.5-staging.1","_id":"@agentsmith-app/staging-sdk@0.0.5-staging.1","maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"homepage":"https://github.com/chad-syntax/agentsmith#readme","bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"dist":{"shasum":"b4b67eb5c450f6afd8f83c289f3935714e0e8292","tarball":"https://registry.npmjs.org/@agentsmith-app/staging-sdk/-/staging-sdk-0.0.5-staging.1.tgz","fileCount":9,"integrity":"sha512-2BrKb51WW5kE//to8c1fKZiz6LRAoSJFG8qJ9RvCu6cRVQbYqfX08b3vOa3Nltbp2svpIXuDqYPslqKU8CuVog==","signatures":[{"sig":"MEUCIQCnt6WZGJ+XNkMqepcfGeQ/KFdVeAt/zltpPRk9FsSa4wIgRFiTDBLxaFr2EU9/RieY5A1W0maLpmhNhA3oXs/zC4o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2472480},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"298c7d84adab032e191a8fb3c6295e011c5b9106","scripts":{"build":"tsup"},"_npmUser":{"name":"chad_syntax","email":"chad@chadsyntax.com"},"repository":{"url":"git+https://github.com/chad-syntax/agentsmith.git","type":"git"},"_npmVersion":"10.9.2","description":"Agentsmith TypeScript SDK","directories":{},"_nodeVersion":"22.14.0","dependencies":{"dotenv":"^16.4.7","p-queue":"^8.1.0","nunjucks":"^3.2.4","lodash.merge":"^4.6.2","@supabase/supabase-js":"latest"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.7.2","@types/lodash.merge":"^4.6.9"},"_npmOperationalInternal":{"tmp":"tmp/staging-sdk_0.0.5-staging.1_1753390056110_0.6742133075478141","host":"s3://npm-registry-packages-npm-production"}},"0.0.6-staging.1":{"name":"@agentsmith-app/staging-sdk","version":"0.0.6-staging.1","_id":"@agentsmith-app/staging-sdk@0.0.6-staging.1","maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"homepage":"https://github.com/chad-syntax/agentsmith#readme","bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"dist":{"shasum":"2f9a8abd83932cc629968f76c0b427e038badc57","tarball":"https://registry.npmjs.org/@agentsmith-app/staging-sdk/-/staging-sdk-0.0.6-staging.1.tgz","fileCount":9,"integrity":"sha512-WGF9XDvxS29iEORLeXR0nCB36hEGFzd5Gl8H6xdPD47Uw83ADWflVxVS+eKtI/OvKUjrNT988Vw6/oXMbdrnnw==","signatures":[{"sig":"MEUCIQDCxPBeFQTfW/jw0ok9INgBUJPgATTJnmvvbkq45pmHHQIgMGszzfw9dBj3sz38pJtivBih56xpLnH+fqTOqOyVNFM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2480174},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"e0b690ec90199ba7706ca4b01a90cd2339313d3e","scripts":{"build":"tsup"},"_npmUser":{"name":"chad_syntax","email":"chad@chadsyntax.com"},"repository":{"url":"git+https://github.com/chad-syntax/agentsmith.git","type":"git"},"_npmVersion":"10.9.2","description":"Agentsmith TypeScript SDK","directories":{},"_nodeVersion":"22.14.0","dependencies":{"dotenv":"^16.4.7","p-queue":"^8.1.0","nunjucks":"^3.2.4","lodash.merge":"^4.6.2","@supabase/supabase-js":"latest"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.7.2","@types/lodash.merge":"^4.6.9"},"_npmOperationalInternal":{"tmp":"tmp/staging-sdk_0.0.6-staging.1_1753473952416_0.9424608271017907","host":"s3://npm-registry-packages-npm-production"}},"0.0.7-staging.1":{"name":"@agentsmith-app/staging-sdk","version":"0.0.7-staging.1","_id":"@agentsmith-app/staging-sdk@0.0.7-staging.1","maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"homepage":"https://github.com/chad-syntax/agentsmith#readme","bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"dist":{"shasum":"4e9ef872c4febbd17f195af5fdcd3ea4851335af","tarball":"https://registry.npmjs.org/@agentsmith-app/staging-sdk/-/staging-sdk-0.0.7-staging.1.tgz","fileCount":9,"integrity":"sha512-mIxVfqPIC6RdeRFqv1h8gY3v1JY6EpsCciMWih+oEd6ShoZ9eQT+YbtxfG98mKYQLEHl2RyDkVu5fGNyJNHnYQ==","signatures":[{"sig":"MEUCIQDfSMhN3g3E01gsfmnPpHA5qtJKdCK3bUrmPZpNsv5dKQIgfZ7MkOwMCUUGcAuXONcqweVNSMvFf01WYhFfuEUdEDA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2481150},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"1bf1ae1c61c17f59d3d457c50b30b82feba5113f","scripts":{"build":"tsup"},"_npmUser":{"name":"chad_syntax","email":"chad@chadsyntax.com"},"repository":{"url":"git+https://github.com/chad-syntax/agentsmith.git","type":"git"},"_npmVersion":"10.9.2","description":"Agentsmith TypeScript SDK","directories":{},"_nodeVersion":"22.14.0","dependencies":{"dotenv":"^16.4.7","p-queue":"^8.1.0","nunjucks":"^3.2.4","lodash.merge":"^4.6.2","@supabase/supabase-js":"latest"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.7.2","@types/lodash.merge":"^4.6.9"},"_npmOperationalInternal":{"tmp":"tmp/staging-sdk_0.0.7-staging.1_1753485940281_0.15378201090197585","host":"s3://npm-registry-packages-npm-production"}},"0.0.8-staging.1":{"name":"@agentsmith-app/staging-sdk","version":"0.0.8-staging.1","description":"Agentsmith TypeScript SDK","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","scripts":{"build":"tsup"},"repository":{"type":"git","url":"git+https://github.com/chad-syntax/agentsmith.git"},"devDependencies":{"@types/lodash.merge":"^4.6.9","tsup":"^8.5.0","typescript":"^5.7.2"},"dependencies":{"@supabase/supabase-js":"latest","dotenv":"^16.4.7","lodash.merge":"^4.6.2","nunjucks":"^3.2.4","p-queue":"^8.1.0"},"_id":"@agentsmith-app/staging-sdk@0.0.8-staging.1","gitHead":"22d05e61a483a04ad472943d3a40d9a979ca1045","bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"homepage":"https://github.com/chad-syntax/agentsmith#readme","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-6CbkDzWqYI0HNYcoV1qEeajD9gBN3Jppa5TaUcitJ5efltnsR7GvhiuP8ToHddnf5AWesRvbtLegWmMexTESYA==","shasum":"500ddb5e6cb97864337f5db34d68983a6945f9ac","tarball":"https://registry.npmjs.org/@agentsmith-app/staging-sdk/-/staging-sdk-0.0.8-staging.1.tgz","fileCount":9,"unpackedSize":2492202,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDxW7CFVYw1R2S821qogjtjHUKueAAliwMIa1ltETKHEwIhAP3cbUDmf19ZegdYvuHNxSCBUSp5NPFsEetkRTKvKS0e"}]},"_npmUser":{"name":"chad_syntax","email":"chad@chadsyntax.com"},"directories":{},"maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/staging-sdk_0.0.8-staging.1_1754489017790_0.3371128004458859"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-02T00:39:03.883Z","modified":"2025-08-06T14:03:38.165Z","0.0.2-staging.1":"2025-07-02T00:39:04.138Z","0.0.2-staging.2":"2025-07-02T20:02:49.783Z","0.0.3-staging.1":"2025-07-02T20:04:55.611Z","0.0.4-staging.1":"2025-07-14T18:21:07.974Z","0.0.5-staging.1":"2025-07-24T20:47:36.322Z","0.0.6-staging.1":"2025-07-25T20:05:52.787Z","0.0.7-staging.1":"2025-07-25T23:25:40.515Z","0.0.8-staging.1":"2025-08-06T14:03:37.957Z"},"bugs":{"url":"https://github.com/chad-syntax/agentsmith/issues"},"homepage":"https://github.com/chad-syntax/agentsmith#readme","repository":{"type":"git","url":"git+https://github.com/chad-syntax/agentsmith.git"},"description":"Agentsmith TypeScript SDK","maintainers":[{"name":"chad_syntax","email":"chad@chadsyntax.com"}],"readme":"> [!WARNING]\n> Agentsmith is currently in alpha. Changes are pushed frequently and may include breaking changes. If you encounter any issues, please reach out to support@agentsmith.dev for assistance.\n\n# @agentsmith-app/sdk\n\nThe Agentsmith SDK provides a type-safe way to interact with your AI agents and prompts. It enables you to:\n\n- Fetch and compile prompts with full TypeScript type safety\n- Execute prompts against various AI models through OpenRouter\n- Integrate AI capabilities into your applications with confidence\n\nThe SDK is designed to work seamlessly with the Agentsmith platform, ensuring that your prompts are always in sync and properly typed.\n\n## Getting Started\n\n### 1. Install the SDK\n\n```sh\nnpm install @agentsmith-app/sdk\n```\n\n### 2. Initialize the SDK in your code\n\n```ts\n// import the generated types (default location is in the agentsmith folder after sync)\nimport { Agency } from '../agentsmith/agentsmith.types';\n\nconst sdkApiKey = 'sdk_********************************'; // copy from your project page/organization settings page\nconst projectId = '123456-abcde-7890-fghij-klmnopqrstuv'; // copy from your project page\n\nconst client = new AgentsmithClient<Agency>(sdkApiKey, projectId);\n```\n\n### 3. Fetch your prompts\n\n```ts\n// pass in the slug, or a string in `slug@version` format\nconst helloWorldLatest = await client.getPrompt('hello-world');\nconst helloWorldLatestAlt = await client.getPrompt('hello-world@latest');\nconst helloWorld0dot0dot1 = await client.getPrompt('hello-world@0.0.1');\n```\n\n### 4. Compile or Execute your prompts\n\n```ts\nconst helloWorldPrompt = await client.getPrompt('hello-world');\n\n// variable typing enforced\nconst { compiledPrompt, finalVariables } = helloWorldPrompt.compile({\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\nconsole.log('Compiled prompt:', compiledPrompt);\nconsole.log('Final Variables prompt compiled with:' finalVariables);\n\n// variable typing enforces\nconst { completion } = await helloWorldPrompt.execute({\n  firstName: 'John',\n  lastName: 'Doe,\n});\n\nconsole.log('Completion', completion); // LLM response\n```\n\n### 5. Customize compilation or execution\n\n```ts\nconst helloWorldPrompt = await client.getPrompt('hello-world');\n\n// Override global context variables during compilation\nconst { compiledPrompt } = await helloWorldPrompt.compile(\n  { firstName: 'John', lastName: 'Doe' },\n  {\n    globals: {\n      companyName: 'Acme Corp', // Override global context variable\n      environment: 'production',\n    },\n  },\n);\n\n// Override both global context and model config during execution\nconst { completion } = await helloWorldPrompt.execute(\n  { firstName: 'John', lastName: 'Doe' },\n  {\n    globals: {\n      companyName: 'Acme Corp',\n      environment: 'production',\n    },\n    config: {\n      temperature: 0.7,\n      model: 'x-ai/grok-3-mini-beta',\n    },\n  },\n);\n```\n\nThe config object you pass extends the prompt config object defined in the studio.\nYou can pass whatever values are supported by [OpenRouter's API](https://openrouter.ai/docs/api-reference/overview):\n\n### 6. Shutdown the client when finished\n\n**Important:** Always call `shutdown()` when your application is done using the SDK to prevent scripts from hanging:\n\n```ts\nconst client = new AgentsmithClient<Agency>(sdkApiKey, projectId);\n\n// Your application logic...\nconst helloWorldPrompt = await client.getPrompt('hello-world');\nconst { content } = await helloWorldPrompt.execute({\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\nconsole.log('Response:', content);\n\n// Shutdown the client before exiting\nawait client.shutdown();\n```\n\nWithout calling `shutdown()`, your Node.js process may hang indefinitely due to:\n\n- Background HTTP connections staying open\n- Internal processing queues waiting for more work\n- JWT refresh timers continuing to run\n\nThis is especially important in:\n\n- CLI tools and scripts\n- Serverless functions\n- Applications that process requests and exit\n\n## Advanced Usage\n\n### Client configuration\n\nThe `AgentsmithClient` constructor accepts an optional third parameter with advanced configuration options:\n\n```ts\nimport { Agency } from '../agentsmith/agentsmith.types';\n\nconst client = new AgentsmithClient<Agency>(\n  'sdk_********************************', // API key\n  '123456-abcde-7890-fghij-klmnopqrstuv', // Project ID\n  {\n    // Configuration options\n    fetchStrategy: 'remote-fallback',\n    logLevel: 'warn',\n    agentsmithDirectory: './custom-agentsmith-folder',\n    logger: customLogger,\n    queueOptions: { concurrency: 5 },\n  },\n);\n```\n\n#### Available configuration options\n\n**`fetchStrategy`** - Controls how prompts and globals are fetched:\n\n- `'remote-fallback'` (default) - Try filesystem first, fallback to remote API\n- `'fs-fallback'` - Try remote API first, fallback to filesystem\n- `'remote-only'` - Always fetch from remote API, fail if unavailable\n- `'fs-only'` - Always fetch from filesystem, fail if files don't exist\n\n**`logLevel`** - Controls SDK logging verbosity:\n\n- `'debug'` - Show all logs including debug information\n- `'info'` - Show info, warnings, and errors\n- `'warn'` (default) - Show warnings and errors only\n- `'error'` - Show errors only\n- `'silent'` - No logging output\n\n**`logger`** - Custom logger implementation (optional):\n\n```ts\nconst customLogger = {\n  debug: (message: string, ...args: any[]) => myLogger.debug(message, args),\n  info: (message: string, ...args: any[]) => myLogger.info(message, args),\n  warn: (message: string, ...args: any[]) => myLogger.warn(message, args),\n  error: (message: string, ...args: any[]) => myLogger.error(message, args),\n};\n```\n\n**`agentsmithDirectory`** - Path to your agentsmith folder (default: `'./agentsmith'`)\n\n**`queueOptions`** - Options for the internal processing queue (uses [p-queue](https://github.com/sindresorhus/p-queue)):\n\n```ts\nqueueOptions: {\n  concurrency: 3,     // Number of concurrent operations\n  interval: 1000,     // Minimum time between operations\n  intervalCap: 10,    // Max operations per interval\n}\n```\n\n**`agentsmithApiRoot`**, **`supabaseUrl`**, **`supabaseAnonKey`** - Override default API endpoints (typically only needed for self-hosted instances)\n\n#### Graceful shutdown\n\nWhen your application is shutting down, call the `shutdown()` method to ensure all background operations complete gracefully:\n\n```ts\nconst client = new AgentsmithClient<Agency>(apiKey, projectId);\n\n// Your application code...\nawait client.getPrompt('hello-world').execute({ name: 'John' });\n\n// Before exiting your application\nawait client.shutdown();\n```\n\nThe `shutdown()` method will:\n\n- Cancel any ongoing HTTP requests\n- Wait for all queued operations (like log saving) to complete\n- Clean up timers and connections\n- Allow your application to exit cleanly\n\nThis is especially important in serverless environments or when processing multiple requests concurrently.\n\n### Execute method return values\n\nThe SDK's `execute` method returns different fields depending on whether you're using streaming or non-streaming execution. You can destructure these fields to access specific parts of the response:\n\n### Non-streaming execution\n\n```ts\nconst helloWorldPrompt = await client.getPrompt('hello-world');\n\n// Access the content directly without diving into completion.choices[0].message.content\nconst { content } = await helloWorldPrompt.execute({\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\nconsole.log('AI Response:', content);\n\n// Access the full OpenRouter response object for additional metadata\nconst { completion, response } = await helloWorldPrompt.execute({\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\nconsole.log('Full completion:', completion);\nconsole.log('HTTP response status:', response.status);\nconsole.log('Usage info:', completion.usage);\n\n// Access the compiled prompt and variables that were used in execution\nconst { compiledPrompt, finalVariables } = await helloWorldPrompt.execute({\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\nconsole.log('Compiled prompt sent to LLM:', compiledPrompt);\nconsole.log('Final variables used:', finalVariables);\n```\n\n### Streaming execution\n\n```ts\nconst helloWorldPrompt = await client.getPrompt('hello-world');\n\n// Stream tokens as they arrive\nconst { tokens } = await helloWorldPrompt.execute(\n  { firstName: 'John', lastName: 'Doe' },\n  { config: { stream: true } },\n);\n\n// Simple token streaming\nfor await (const token of tokens) {\n  if (token) {\n    process.stdout.write(token);\n  }\n}\n\n// Access the raw SSE stream for more control\nconst { stream } = await helloWorldPrompt.execute(\n  { firstName: 'John', lastName: 'Doe' },\n  { config: { stream: true } },\n);\n\n// Process parsed SSE events\nfor await (const event of stream) {\n  // Each event contains parsed data from the SSE stream\n  if (event.data?.choices?.[0]?.delta?.content) {\n    process.stdout.write(event.data.choices[0].delta.content);\n  }\n\n  // Handle usage information when streaming completes\n  if (event.data?.usage) {\n    console.log('\\nUsage:', event.data.usage);\n  }\n}\n\n// Access other fields like the HTTP response and compiled prompt\nconst { response, compiledPrompt, finalVariables } = await helloWorldPrompt.execute(\n  { firstName: 'John', lastName: 'Doe' },\n  { config: { stream: true } },\n);\n\nconsole.log('HTTP response headers:', response.headers);\nconsole.log('Compiled prompt:', compiledPrompt);\nconsole.log('Variables used:', finalVariables);\n```\n\n### Custom message arrays\n\nBy default, `execute` compiles your prompt and sends it as a single user message. For advanced use cases, you can compile the prompt separately and create your own message array:\n\n```ts\nconst helloWorldPrompt = await client.getPrompt('hello-world');\n\n// First, compile the prompt to get the final content\nconst { compiledPrompt } = await helloWorldPrompt.compile({\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\n// Create a custom messages array for multi-turn conversations\nconst customMessages = [\n  { role: 'system', content: 'You are a helpful assistant.' },\n  { role: 'user', content: 'Hello, I need help with something.' },\n  { role: 'assistant', content: 'Of course! How can I assist you today?' },\n  { role: 'user', content: compiledPrompt }, // Use your compiled prompt\n];\n\n// Execute with custom messages array\nconst { completion } = await helloWorldPrompt.execute(\n  { firstName: 'John', lastName: 'Doe' },\n  {\n    config: {\n      messages: customMessages, // Override the default single-message behavior\n      temperature: 0.7,\n    },\n  },\n);\n\nconsole.log('Multi-turn response:', completion.choices[0].message.content);\n```\n\nThis is particularly useful for:\n\n- Building multi-turn conversations\n- Adding system prompts or context\n- Creating few-shot examples with assistant responses\n- Implementing conversation flows where your compiled prompt is just one part of a larger exchange\n\n### Available return fields\n\n**Non-streaming execution** returns:\n\n- `content` - The AI response content (shortcut for `completion.choices[0].message.content`)\n- `reasoning` - The AI response reasoning content (shortcut for `completion.choices[0].message.reasoning`)\n- `toolCalls` - The AI response tool calls\n- `completion` - Full OpenRouter completion object with choices, usage, etc.\n- `response` - Raw HTTP Response object\n- `compiledPrompt` - The final prompt sent to the LLM\n- `finalVariables` - Variables used in compilation (includes defaults and globals)\n- `logUuid` - UUID of the log entry created for this execution\n\n**Streaming execution** returns:\n\n- `tokens` - AsyncGenerator that yields content tokens as strings\n- `reasoningTokens` - AsyncGenerator that yields reasoning tokens as strings\n- `toolCalls` - AsyncGenerator that yields tool calls\n- `completion` - A Promise of the final completion data in NonStreamingResponse format\n- `stream` - Raw SSE stream as an AsyncIterable of parsed events\n- `response` - Raw HTTP Response object\n- `compiledPrompt` - The final prompt sent to the LLM\n- `finalVariables` - Variables used in compilation (includes defaults and globals)\n- `logUuid` - UUID of the log entry created for this execution\n\n## Development\n\n1.  **Install dependencies**\n\n    Navigate to the `sdk` directory and install the necessary dependencies:\n\n    ```sh\n    cd sdk\n    npm install\n    ```\n\n2.  **Build the SDK**\n\n    Run the build command which will build esm, cjs, and dts files into the `sdk/dist` directory\n\n    ```sh\n    npm run build\n    ```\n\n3.  **Link the SDK**\n\n    To test local changes in a consuming project without publishing to npm, use `npm link`:\n\n    - **In the `sdk` directory:**\n      Create a global symbolic link.\n\n      ```sh\n      npm link\n      ```\n\n      Remember to rebuild the SDK (step 2) after making changes.\n\n    - **In your consuming project:**\n      Link the globally created symbolic link to your project's `node_modules` directory.\n      ```sh\n      npm link @agentsmith-app/sdk\n      ```\n\n    Now, your consuming project will use your local version of `@agentsmith-app/sdk`. Changes in the SDK (followed by a rebuild) will be reflected immediately.\n\n### Unlinking the SDK\n\nOnce you're done with local development and testing, you might want to unlink the SDK to revert to using the version from npm.\n\n1.  **In your consuming project:**\n\n    ```sh\n    npm unlink @agentsmith-app/sdk\n    # Optionally, reinstall the package from npm if you were using a published version before linking\n    # npm install @agentsmith-app/sdk\n    ```\n\n2.  **In the `agentsmith/sdk` directory (optional but good practice):**\n    This removes the global link.\n    ```sh\n    npm unlink\n    ```\n\nThis will remove the symbolic links and restore the normal package resolution.\n\n## Roadmap\n\n- [ ] Add background check for latest prompts in db and hold in memory\n- [ ] Add memoization for prompts to reduce calls to fs/db\n","readmeFilename":"README.md"}