From Claude Agent SDK

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:

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:

ANTHROPIC_API_KEY=replace_with_your_key

Save this complete example as agent.mjs:

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()
}

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 or open the chat application source.

3. Map the features your application uses

Your application needs	Cognitio API	Guide
One task	`Agent.run()`	Agents
Stream a task	`Agent.stream()` or `query()`	Streaming
A conversation	`agent.createSession()` and `session.send()`	Sessions
Resume or branch	`agent.resume()` and `agent.fork()`	Sessions
An application function	`defineTool()` and `tools`	Custom tool recipe
External tools and data	`sdkMcpServers`	MCP
Approval decisions	`permission`, `permissionMode`, `canUseTool`	Permissions
Lifecycle callbacks	`hooks`	Hooks
Task delegation	`defineAgent()` and `agents`	Subagents
Schema-shaped results	`defineOutputFormat()`	Extraction recipe
File rewind	`session.checkpoint()` and `session.rewind()`	Checkpoints
Skills, commands and local plugins	`skills`, `commands`, `plugins`	Extensions

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 for remote alternatives. Use the Claude Agent SDK documentation for the original integration and Cognitio’s API reference for the replacement calls.

Get started

Models and conversations

Tools and extensions

Control and observe

Cookbooks

Run in an application

Help and migration

1. Install Cognitio

2. Replace a one-task call

3. Map the features your application uses

Check these behavior differences

​1. Install Cognitio

​2. Replace a one-task call

​3. Map the features your application uses

​Check these behavior differences

1. Install Cognitio

2. Replace a one-task call

3. Map the features your application uses

Check these behavior differences