Skip to main content
Use Node.js 22+ or Bun 1.3.11+. Cognitio is an ESM package with TypeScript declarations included. A model provider API key is required when you run a model request, but not to install the SDK.

​
Install the package

Choose the package manager your application already uses:
Keep optional dependencies enabled. They provide the native runtime for your platform; there is no separate CLI to download or start. Commit your application’s lockfile for reproducible installs.

​
JavaScript projects

Save scripts as .mjs, as in the quickstart, or set "type": "module" in your application’s package.json to use ESM in .js files.
Use --env-file when your provider key is in .env. If you already exported the key in the same shell, node agent.mjs is sufficient.

​
TypeScript projects

For a Node.js project, install a TypeScript runner and enable ESM:
Save a guide’s complete TypeScript example as agent.ts, then run:
Bun can run the same TypeScript file directly:
Guides that import zod also need it in your application:

​
Supported local runtimes

The x64 packages use the baseline runtime build. Install dependencies on the target platform instead of copying node_modules from a different operating system or architecture. See troubleshooting if your package manager omitted the runtime package. For an environment where you run the server separately, use remote connections.

​
Upgrade an application

Upgrade the main package and commit the updated lockfile:
The SDK pins its platform packages to the matching version. You do not need to upgrade a background runtime separately. Review the changelog before upgrading an existing application.

​
Custom runtime binaries

Most applications should use the bundled runtime. For a custom runtime build, pass an absolute executable path with spawn.binaryPath or set COGNITIO_BIN_PATH. Explicit overrides bypass the automatic bundled-version check, so the custom runtime must implement the SDK’s protocol.
Replace the placeholder path before running this advanced example. Explicit spawn options give this Agent its own runtime, which close() releases. See lifecycle and cleanup for shared and borrowed clients.