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

Environment variables

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

Built-in tools

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:

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