Skip to main content
When moving an earlier integration to Cognitio 2.0.0, check installation, tool policy, configuration discovery and runtime ownership together.

​
Install the package

Import public APIs from cognitio-agent-sdk. Keep optional dependencies enabled: the package includes a matching runtime for supported platforms. Upgrade the SDK package to update that bundled runtime. Use the chat recipe to check a new installation with a real request. The runtime executable is cognitio, configuration files use .cognitio and cognitio.json, and runtime environment variables use the COGNITIO_ prefix. Old upstream variable names are not fallback aliases. See installation before supplying a separately managed binary.

​
Choose configuration discovery explicitly

Agent, query() and local createAgentClient() use isolated runtime state by default. Sessions default to settingSources: [], so they do not silently inherit local instruction files. Common provider environment variables are forwarded, but host authentication files are not. Supply credentials through supported provider variables or spawn.auth. If your application intentionally relies on user/project configuration, select spawn.isolated: false and the relevant settingSources. This is separate from the system prompt: systemPrompt: { type: "preset", preset: "default" } chooses the coding prompt, while the default remains neutral. It does not restore configuration discovery or hidden tools. See defaults and isolation. Isolation concerns configuration and state. It does not restrict filesystem or network operations with an OS sandbox.

​
Make tool policy explicit

An empty allowedTools array leaves the allowlist unrestricted. A wildcard deny also blocks StructuredOutput, so use its case-sensitive allowlist entry for schema-only results. Custom tool schemas describe arguments to the model. Validate invocation input inside execute before using it. Follow the calculator recipe for a complete example or read its JavaScript source.

​
Close the resources your application owns

Default Agents and query() share a process-wide runtime. Close each Agent or stream when its work is done, then call shutdown() when the application is finished using all facade-owned runtimes. An Agent with explicit spawn options owns a dedicated client and closes it with agent.close(). An Agent with an injected client borrows it: the code that created the client must call client.close(). Closing a remote client does not stop your remote server. See lifecycle.

​
Resume sessions with their policy

Resume can apply explicit runtime overrides. A session’s working directory remains fixed. Callback functions must be provided again by the attaching process; they are not stored with the transcript. Forks preserve serializable policy, while callback registrations must be rebound. deleteSessionsOnClose is opt-in and applies to sessions created or forked by the Agent, not resumed sessions. A default isolated runtime uses temporary state. Keeping a session ID does not make it available after that state is removed. The session memory recipe shows close/resume within one living runtime; use remote runtimes for persistent server ownership.

​
Handle results and errors

Check result.isError or result.subtype after Agent.run(). Setup and transport failures can throw; cleanup belongs in finally. Use the SDK error guard and tagged kind values instead of matching error strings. Low-level session results expose subtype rather than the facade’s added isError field. Reasoning, checkpoint and compaction options have explicit schemas. Check the corresponding guides when migrating these settings: models, checkpoints, and compaction.