Open Agent Sdk

# Open Agent SDK

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Open Agent SDK (`@shipany/open-agent-sdk`) is a fully open-source, in-process AI agent framework for TypeScript/Node.js. It runs the complete Claude Code agent engine directly — no local CLI subprocess required — making it suitable for cloud servers, serverless functions, Docker containers, and CI/CD pipelines. It is API-compatible with `@anthropic-ai/claude-agent-sdk`.

---

## Installation

```sh
npm install @shipany/open-agent-sdk
```

Requires Node.js 18+.

---

## Authentication & Configuration

Set the Anthropic API key as an environment variable:

```sh
export ANTHROPIC_API_KEY=your-api-key
```

Or use a third-party provider (e.g. OpenRouter):

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

These can also be passed programmatically via `options.env` or `apiKey`/`baseURL` in `createAgent()`.

---

## Core API

### `query({ prompt, options })` — Streaming, compatible with official SDK

Returns an `AsyncGenerator<SDKMessage>`. Drop-in replacement for `@anthropic-ai/claude-agent-sdk`.

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

for await (const message of query({
  prompt: 'Find and fix the bug in auth.ts',
  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) process.stdout.write(block.text)
      else if ('name' in block) console.log(`\n[Tool used: ${block.name}]`)
    }
  } else if (message.type === 'result') {
    console.log(`\nDone: ${message.subtype}`)
  }
}
```

---

### `createAgent(options)` — Reusable agent with session state

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

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

// Blocking call
const result = await agent.prompt('Read package.json and describe the project')
console.log(result.text)
console.log(`Tokens used: ${result.usage.input_tokens + result.usage.output_tokens}`)

// Streaming call
for await (const msg of agent.query('Now add JSDoc to all exported functions')) {
  if (msg.type === 'assistant' && msg.message?.content) {
    for (const block of msg.message.content) {
      if ('text' in block) process.stdout.write(block.text)
    }
  }
}

// Session management
const history = agent.getMessages()  // full conversation history
agent.clear()                        // reset session
```

---

## Options Reference

| Option | Type | Default | Description |
|---|---|---|---|
| `model` | `string` | `claude-sonnet-4-6` | Claude model ID |
| `apiKey` | `string` | `ANTHROPIC_API_KEY` env | API key |
| `baseURL` | `string` | Anthropic API | Override for third-party providers |
| `cwd` | `string` | `process.cwd()` | Working directory for file/shell tools |
| `systemPrompt` | `string` | — | Custom system prompt prepended to agent |
| `tools` | `Tool[]` | All built-in | Override the full tool list |
| `allowedTools` | `string[]` | all | Whitelist specific tools by name |
| `permissionMode` | `string` | `bypassPermissions` | `acceptEdits`, `bypassPermissions`, `plan`, `default` |
| `maxTurns` | `number` | `100` | Maximum agentic lo