Open Agent SDK

Open Agent SDK is an open-source Agent SDK inspired by @anthropic-ai/claude-agent-sdk. Build autonomous AI agents that can understand codebases, edit files, run commands, search the web, and execute complex multi-step workflows.

Unlike the official @anthropic-ai/claude-agent-sdk which requires a local Claude Code CLI process, Open Agent SDK runs the full agent loop in-process — deploy anywhere: cloud servers, serverless functions, Docker containers, CI/CD pipelines.

Get started

npm install @shipany/open-agent-sdk

Set your API key:

export ANTHROPIC_API_KEY=your-api-key

Or use a third-party provider like OpenRouter:

export ANTHROPIC_BASE_URL=https://openrouter.ai/api
export ANTHROPIC_API_KEY=your-openrouter-api-key
export ANTHROPIC_MODEL=anthropic/claude-sonnet-4-6

Quick start

One-shot query (compatible with official SDK)

import { query } from '@shipany/open-agent-sdk'

for await (const message of query({
  prompt: 'Find and fix the bug in auth.py',
  options: {
    allowedTools: ['Read', 'Edit', 'Bash'],
    permissionMode: 'acceptEdits',
  },
})) {
  if (message.type === 'assistant' && message.message?.content) {
    for (const block of message.message.content) {
      if ('text' in block) console.log(block.text)
      else if ('name' in block) console.log(`Tool: ${block.name}`)
    }
  } else if (message.type === 'result') {
    console.log(`Done: ${message.subtype}`)
  }
}

Simple prompt (blocking)

import { createAgent } from '@shipany/open-agent-sdk'

const agent = createAgent({ model: 'claude-sonnet-4-6' })
const result = await agent.prompt('Read package.json and tell me the project name')

console.log(result.text)
console.log(`Tokens: ${result.usage.input_tokens + result.usage.output_tokens}`)

Multi-turn session

import { createAgent } from '@shipany/open-agent-sdk'

const agent = createAgent({
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You are a senior software engineer. Be concise.',
})

const r1 = await agent.prompt('Read the main entry point and explain the architecture')
console.log(r1.text)

// Full context from turn 1 is preserved
const r2 = await agent.prompt('Now refactor the error handling')
console.log(r2.text)

Custom tools

import { createAgent, getAllBaseTools } from '@shipany/open-agent-sdk'

const weatherTool = {
  name: 'GetWeather',
  description: 'Get weather for a city',
  inputJSONSchema: {
    type: 'object',
    properties: { city: { type: 'string' } },
    required: ['city'],
  },
  get inputSchema() { return { safeParse: (v) => ({ success: true, data: v }) } },
  async prompt() { return this.description },
  async call(input) { return { data: `Weather in ${input.city}: 22°C, sunny` } },
  userFacingName: () => 'GetWeather',
  isReadOnly: () => true,
  isConcurrencySafe: () => true,
  mapToolResultToToolResultBlockParam: (data, id) => ({
    type: 'tool_result', tool_use_id: id, content: data,
  }),
}

const agent = createAgent({
  tools: [...getAllBaseTools(), weatherTool],
})

const result = await agent.prompt('What is the weather in Tokyo?')

MCP server integration

import { createAgent } from '@shipany/open-agent-sdk'

const agent = createAgent({
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
    },
    playwright: {
      command: 'npx',
      args: ['@playwright/mcp@latest'],
    },
  },
})

const result = await agent.prompt('List files in /tmp')

Subagents

import { query } from '@shipany/open-agent-sdk'

for await (const message of query({
  prompt: 'Use the code-reviewer agent to review this codebase',
  options: {
    allowedTools: ['Read', 'Glob', 'Grep', 'Agent'],
    agents: {
      'code-reviewer': {
        description: 'Expert code reviewer for quality and security.',
        prompt: 'Analyze code quality and suggest improvements.',
        tools: ['Read', 'Glob', 'Grep'],
      },
    },
  },
})) {
  // handle messages...
}

Permissions

import { query } from '@shipany/open-agent-sdk'

// Read-only agent: can only analyze, not modify
for await (const message of query({
  prompt: 'Review this code for best practices',
  options: {
    allowedTools: ['Read', 'Glob', 'Grep'],
  },
})) {
  // ...
}

API reference

query({ prompt, options })

Top-level entry point, compatible with @anthropic-ai/claude-agent-sdk. Returns an AsyncGenerator<SDKMessage>.

createAgent(options)

Create a reusable agent with persistent session state.

• agent.query(prompt) — streaming response (AsyncGenerator)
• agent.prompt(prompt) — blocking response (Promise<QueryResult>)
• agent.getMessages() — conversation history
• agent.clear() — reset session

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | model | string | claude-sonnet-4-6 | Claude model ID | | apiKey | string | env.ANTHROPIC_API_KEY | API key | | baseURL | string | Anthropic API | API base URL (for third-party providers) | | cwd | string | process.cwd() | Working directory for tools | | systemPrompt | string | — | Custom system prompt | | tools | Tool[] | All built-in | Available tools | | allowedTools | string[] | — | Tool whitelist (e.g. ['Read', 'Glob']) | | permissionMode | string | bypassPermissions | acceptEdits / bypassPermissions / plan / default | | maxTurns | number | 100 | Max agentic turns | | maxBudgetUsd | number | — | Max USD spend | | mcpServers | object | — | MCP server configurations | | agents | object | — | Custom subagent definitions | | hooks | object | — | Lifecycle hooks (PreToolUse, PostToolUse, Stop, etc.) | | thinking | object | — | Extended thinking configuration | | env | object | — | Environment variables (compatible with official SDK) | | resume | string | — | Resume a previous session by ID | | canUseTool | function | — | Custom permission callback | | includePartialMessages | boolean | false | Include raw streaming events |

Environment variables

| Variable | Description | |----------|-------------| | ANTHROPIC_API_KEY | API key | | ANTHROPIC_BASE_URL | API base URL (for third-party providers like OpenRouter) | | ANTHROPIC_MODEL | Default model |

Also supports options.env for passing environment variables programmatically, same as the official SDK.

Built-in tools

| Tool | Description | |------|-------------| | Read | Read files with line numbers, images, PDFs | | Write | Create or overwrite files | | Edit | Precise string replacement in files | | Bash | Execute shell commands | | Glob | Find files by pattern | | Grep | Search file contents with regex (ripgrep) | | WebFetch | Fetch and parse web content | | WebSearch | Search the web | | Agent | Spawn subagents for parallel work | | NotebookEdit | Edit Jupyter notebooks | | Skill | Invoke custom skills | | AskUserQuestion | Ask the user clarifying questions | | TodoWrite | Create/manage todo lists | | ToolSearch | Search available tools | | SendMessage | Send messages to agents/teammates | | TeamCreate / TeamDelete | Create/delete agent teams | | EnterPlanMode / ExitPlanMode | Plan approval mode | | EnterWorktree / ExitWorktree | Git worktree isolation | | ListMcpResources / ReadMcpResource | MCP resource access | | TaskCreate / TaskUpdate / TaskList / TaskGet / TaskStop / TaskOutput | Task management |

Architecture

The official @anthropic-ai/claude-agent-sdk architecture:

Your code → SDK → spawn cli.js subprocess → stdin/stdout JSON → Anthropic API

Open Agent SDK runs everything in-process:

Your code → SDK → QueryEngine → Anthropic API (direct)

What's under the hood

This SDK contains the complete Claude Code engine (2,000+ source files), not a simplified reimplementation:

| Component | Description | |-----------|-------------| | System Prompt | Full prompt construction with static/dynamic boundary caching | | Permission System | 4-layer pipeline: rules → low-risk skip → whitelist → AI classifier + circuit breaker | | Memory System | Auto-memory with 4 types (user/feedback/project/reference), autoDream background organizer | | Context Compression | 9-segment structured extraction (autocompact, microcompact, snip compact) | | Multi-Agent | Leader/Teammate teams, Git worktree isolation, permission bubbling, async mailbox | | MCP Client | Full MCP support: stdio, SSE, HTTP transports | | Search | ripgrep + glob (same as Claude Code — no vector DB needed) | | Tool Execution | Concurrent batching for read-only tools, serial for mutations | | API Client | Streaming, retry with exponential backoff, fallback models, prompt caching |

Comparison with @anthropic-ai/claude-agent-sdk

| | Official SDK | Open Agent SDK | |---|---|---| | Architecture | Spawns local CLI subprocess | In-process agent loop | | Cloud deployment | Requires CLI installed | Works anywhere | | Serverless | Not supported | Fully supported | | Docker | Needs CLI in image | Just npm install | | API surface | query(), tool(), sessions | query(), createAgent(), sessions | | Built-in tools | 26 tools | 26 tools (same set) | | System prompt | Full engine | Full engine (same code) | | Permission system | 4-layer + AI classifier | 4-layer + AI classifier (same code) | | Memory system | Auto-memory + autoDream | Auto-memory + autoDream (same code) | | Context compression | 9-segment structured | 9-segment structured (same code) | | Multi-agent | Teams, worktrees | Teams, worktrees (same code) | | MCP support | Full | Full (same code) | | Custom tools | Via MCP | Native function tools + MCP | | Streaming | Via subprocess stdio | Direct API streaming |

Examples

See the examples/ directory:

| # | Example | What it demonstrates | |---|---------|---------------------| | 01 | Simple Query | Streaming with createAgent().query() | | 02 | Multi-Tool | Glob + Bash orchestration | | 03 | Multi-Turn | Session persistence across turns | | 04 | Prompt API | Blocking agent.prompt() | | 05 | System Prompt | Custom system prompt | | 06 | MCP Server | MCP stdio transport | | 07 | Custom Tools | User-defined tools | | 08 | Official API | query() drop-in compatible | | 09 | Subagents | Agent delegation | | 10 | Permissions | Read-only agent |

Run any example:

npx tsx examples/01-simple-query.ts

Reporting bugs

File issues at github.com/shipany-ai/open-agent-sdk/issues.

Contributors

Star History

License

MIT