Open Agent SDK

Get started

npm install @shipany/open-agent-sdk

export ANTHROPIC_API_KEY=your-api-key

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

createAgent(options)

Options

Environment variables

Built-in tools

Architecture

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

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

What's under the hood

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

Examples

npx tsx examples/01-simple-query.ts

Reporting bugs

Contributors

Star History

License