> ## Documentation Index
> Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to v2

> Update package installation, configuration and session ownership for Cognitio 2.0.0.

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

## Install the package

```sh theme={null}
npm install --save-exact cognitio-agent-sdk@2.0.1
```

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](https://cognitio-agent.mintlify.site/cookbook/chat-cli.md) 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](https://cognitio-agent.mintlify.site/installation.md) 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](https://cognitio-agent.mintlify.site/defaults-and-isolation.md).

Isolation concerns configuration and state. It does not restrict filesystem or network operations with an OS sandbox.

## Make tool policy explicit

| Intended behavior | Configuration |
| - | - |
| No tool execution | `disallowedTools: ["*"]` |
| Selected built-ins only | `allowedTools: ["read", "grep", "glob"]` |
| One custom direct tool | `allowedTools: ["sdk_multiply"]` |
| Structured output without other tools | `allowedTools: ["StructuredOutput"]` |

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](https://cognitio-agent.mintlify.site/cookbook/custom-tool.md) for a complete example or read its [JavaScript source](https://github.com/ozgurugurlu/cognitio-agent-sdk/blob/main/examples/03-custom-tool/index.mjs).

## 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](https://cognitio-agent.mintlify.site/cookbook/lifecycle.md).

## 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](https://cognitio-agent.mintlify.site/cookbook/session-memory.md) shows close/resume within one living runtime; use [remote runtimes](https://cognitio-agent.mintlify.site/cookbook/remote.md) 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](https://cognitio-agent.mintlify.site/concepts/models-and-prompts.md), [checkpoints](https://cognitio-agent.mintlify.site/concepts/checkpoints.md), and [compaction](https://cognitio-agent.mintlify.site/concepts/compaction.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.