> ## 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.

# From Claude Agent SDK

> Move an integration to Cognitio's agents, sessions, tools and permissions.

Cognitio is built on OpenCode and has its own API and message shapes. When moving an application, replace the SDK calls and check the behavior of permissions, credentials and session storage. Changing the import name alone is not enough.

## 1. Install Cognitio

Use Node.js 22 or newer. In your application directory:

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

Keep optional dependencies enabled so npm installs the matching runtime. Set your provider's API key explicitly; a Claude CLI login or authentication file is not automatically imported into Cognitio's isolated runtime.

## 2. Replace a one-task call

Create `.env` with your Anthropic key and keep it out of Git:

```dotenv theme={null}
ANTHROPIC_API_KEY=replace_with_your_key
```

Save this complete example as `agent.mjs`:

```js theme={null}
import { Agent } from "cognitio-agent-sdk"

const key = process.env.ANTHROPIC_API_KEY?.trim()
if (!key || key === "replace_with_your_key") throw new Error("Set ANTHROPIC_API_KEY in .env.")

const agent = new Agent({
  model: "anthropic/claude-sonnet-4-5",
  instructions: "Summarize the supplied text in one sentence.",
  disallowedTools: ["*"],
  maxTurns: 1,
  maxBudgetUsd: 0.05,
  spawn: { auth: { anthropic: { type: "api", key } } },
})
try {
  const result = await agent.run("The team moved its nightly database backup from 02:00 to 03:00.", {
    signal: AbortSignal.timeout(90_000),
  })
  if (result.isError) throw new Error(`Agent ended: ${result.subtype}`)
  console.log(result.text)
} finally {
  await agent.close()
}
```

```sh theme={null}
node --env-file=.env agent.mjs
```

A successful run prints a summary such as “The team's nightly database backup now runs at 03:00 instead of 02:00.” Wording varies. The explicit `spawn` option makes this Agent own a dedicated runtime, so `close()` stops it. The estimated budget does not guarantee a provider billing ceiling.

For a complete OpenAI version, follow the [chat recipe](https://cognitio-agent.mintlify.site/cookbook/chat-cli.md) or open the [chat application source](https://github.com/ozgurugurlu/cognitio-agent-sdk/blob/main/examples/01-chat/index.mjs).

## 3. Map the features your application uses

| Your application needs | Cognitio API | Guide |
| - | - | - |
| One task | `Agent.run()` | [Agents](https://cognitio-agent.mintlify.site/concepts/agents.md) |
| Stream a task | `Agent.stream()` or `query()` | [Streaming](https://cognitio-agent.mintlify.site/concepts/streaming.md) |
| A conversation | `agent.createSession()` and `session.send()` | [Sessions](https://cognitio-agent.mintlify.site/concepts/sessions.md) |
| Resume or branch | `agent.resume()` and `agent.fork()` | [Sessions](https://cognitio-agent.mintlify.site/concepts/sessions.md) |
| An application function | `defineTool()` and `tools` | [Custom tool recipe](https://cognitio-agent.mintlify.site/cookbook/custom-tool.md) |
| External tools and data | `sdkMcpServers` | [MCP](https://cognitio-agent.mintlify.site/concepts/mcp.md) |
| Approval decisions | `permission`, `permissionMode`, `canUseTool` | [Permissions](https://cognitio-agent.mintlify.site/concepts/permissions.md) |
| Lifecycle callbacks | `hooks` | [Hooks](https://cognitio-agent.mintlify.site/concepts/hooks.md) |
| Task delegation | `defineAgent()` and `agents` | [Subagents](https://cognitio-agent.mintlify.site/concepts/subagents.md) |
| Schema-shaped results | `defineOutputFormat()` | [Extraction recipe](https://cognitio-agent.mintlify.site/cookbook/structured-extraction.md) |
| File rewind | `session.checkpoint()` and `session.rewind()` | [Checkpoints](https://cognitio-agent.mintlify.site/concepts/checkpoints.md) |
| Skills, commands and local plugins | `skills`, `commands`, `plugins` | [Extensions](https://cognitio-agent.mintlify.site/concepts/skills-commands-plugins.md) |

Use `provider/model` identifiers such as `anthropic/claude-sonnet-4-5`. Built-in tool names are Cognitio names such as `read`, `grep` and `glob`; a direct custom tool named `multiply` is exposed as `sdk_multiply`.

Rewrite message handling against the `AgentMessage` union. An event with `type: "result"` contains its terminal result in `message.result`; partial text is opt-in. Do not reuse another SDK's message parser unchanged.

## Check these behavior differences

* **Configuration:** local runtimes isolate state by default and sessions use `settingSources: []`. Opt into local instruction discovery deliberately.
* **Tools:** `allowedTools: []` leaves the allowlist unrestricted. Use `disallowedTools: ["*"]` for text-only work. Custom tool input must be validated inside `execute`.
* **Permissions:** explicit rules and modes can decide before `canUseTool`. A callback is not an interceptor for every tool call.
* **Lifecycle:** default Agents share a process-wide runtime until `shutdown()`. Agents with explicit `spawn` options close their own runtime; injected clients are borrowed.
* **Persistence:** an isolated runtime's transcript disappears with its temporary state. Reuse a persistent runtime when sessions must survive application restarts.
* **Hooks and reasoning:** use Cognitio's documented hook names and provider-specific reasoning options. Matching names in another SDK do not guarantee matching semantics.

Python bindings, managed sandbox adapters, durable detached tasks, and remote plugin marketplace installation are outside Cognitio 2.0.0. Direct SDK MCP supports tools; SDK-hosted HTTP MCP also supports resources and prompts and requires local spawn. See [MCP](https://cognitio-agent.mintlify.site/concepts/mcp.md) for remote alternatives.

Use the [Claude Agent SDK documentation](https://code.claude.com/docs/en/agent-sdk/overview) for the original integration and [Cognitio's API reference](https://cognitio-agent.mintlify.site/api-reference/index.md) for the replacement calls.


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