Open Agent SDK (TypeScript)

Open-source Agent SDK that runs the full agent loop in-process — no subprocess or CLI required. Supports both Anthropic and OpenAI-compatible APIs. Deploy anywhere: cloud, serverless, Docker, CI/CD.

Also available in Go: open-agent-sdk-go

Get started

npm install @codeany/open-agent-sdk

Set your API key:

export CODEANY_API_KEY=your-api-key

OpenAI-compatible models

Works with OpenAI, DeepSeek, Qwen, Mistral, or any OpenAI-compatible endpoint:

export CODEANY_API_TYPE=openai-completions
export CODEANY_API_KEY=sk-...
export CODEANY_BASE_URL=https://api.openai.com/v1
export CODEANY_MODEL=gpt-4o

Third-party Anthropic-compatible providers

export CODEANY_BASE_URL=https://openrouter.ai/api
export CODEANY_API_KEY=sk-or-...
export CODEANY_MODEL=anthropic/claude-sonnet-4

Quick start

One-shot query (streaming)

import { query } from "@codeany/open-agent-sdk";

for await (const message of query({
  prompt: "Read package.json and tell me the project name.",
  options: {
    allowedTools: ["Read", "Glob"],
    permissionMode: "bypassPermissions",
  },
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  }
}

Simple blocking prompt

import { createAgent } from "@codeany/open-agent-sdk";

const agent = createAgent({ model: "claude-sonnet-4-6" });
const result = await agent.prompt("What files are in this project?");

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

OpenAI / GPT models

import { createAgent } from "@codeany/open-agent-sdk";

const agent = createAgent({
  apiType: "openai-completions",
  model: "gpt-4o",
  apiKey: "sk-...",
  baseURL: "https://api.openai.com/v1",
});

const result = await agent.prompt("What files are in this project?");
console.log(result.text);

The apiType is auto-detected from model name — models containing gpt-, o1, o3, deepseek, qwen, mistral, etc. automatically use openai-completions.

Multi-turn conversation

import { createAgent } from "@codeany/open-agent-sdk";

const agent = createAgent({ maxTurns: 5 });

const r1 = await agent.prompt(
  'Create a file /tmp/hello.txt with "Hello World"',
);
console.log(r1.text);

const r2 = await agent.prompt("Read back the file you just created");
console.log(r2.text);

console.log(`Session messages: ${agent.getMessages().length}`);

Custom tools (Zod schema)

import { z } from "zod";
import { query, tool, createSdkMcpServer } from "@codeany/open-agent-sdk";

const getWeather = tool(
  "get_weather",
  "Get the temperature for a city",
  { city: z.string().describe("City name") },
  async ({ city }) => ({
    content: [{ type: "text", text: `${city}: 22°C, sunny` }],
  }),
);

const server = createSdkMcpServer({ name: "weather", tools: [getWeather] });

for await (const msg of query({
  prompt: "What is the weather in Tokyo?",
  options: { mcpServers: { weather: server } },
})) {
  if (msg.type === "result")
    console.log(`Done: $${msg.total_cost_usd?.toFixed(4)}`);
}

Custom tools (low-level)

import {
  createAgent,
  getAllBaseTools,
  defineTool,
} from "@codeany/open-agent-sdk";

const calculator = defineTool({
  name: "Calculator",
  description: "Evaluate a math expression",
  inputSchema: {
    type: "object",
    properties: { expression: { type: "string" } },
    required: ["expression"],
  },
  isReadOnly: true,
  async call(input) {
    const result = Function(`'use strict'; return (${input.expression})`)();
    return `${input.expression} = ${result}`;
  },
});

const agent = createAgent({ tools: [...getAllBaseTools(), calculator] });
const r = await agent.prompt("Calculate 2**10 * 3");
console.log(r.text);

Skills

Skills are reusable prompt templates that extend agent capabilities. Five bundled skills are included: simplify, commit, review, debug, test.

import {
  createAgent,
  registerSkill,
  getAllSkills,
} from "@codeany/open-agent-sdk";

// Register a custom skill
registerSkill({
  name: "explain",
  description: "Explain a concept in simple terms",
  userInvocable: true,
  async getPrompt(args) {
    return [
      {
        type: "text",
        text: `Explain in simple terms: ${args || "Ask what to explain."}`,
      },
    ];
  },
});

console.log(`${getAllSkills().length} skills registered`);

// The model can invoke skills via the Skill tool
const agent = createAgent();
const result = await agent.prompt('Use the "explain" skill to explain git rebase');
console.log(result.text);

Hooks (lifecycle events)

import { createAgent, createHookRegistry } from "@codeany/open-agent-sdk";

const hooks = createHookRegistry({
  PreToolUse: [
    {
      handler: async (input) => {
        console.log(`About to use: ${input.toolName}`);
        // Return { block: true } to prevent tool execution
      },
    },
  ],
  PostToolUse: [
    {
      handler: async (input) => {
        console.log(`Tool ${input.toolName} completed`);
      },
    },
  ],
});

20 lifecycle events: PreToolUse, PostToolUse, PostToolUseFailure, SessionStart, SessionEnd, Stop, SubagentStart, SubagentStop, UserPromptSubmit, PermissionRequest, PermissionDenied, TaskCreated, TaskCompleted, ConfigChange, CwdChanged, FileChanged, Notification, PreCompact, PostCompact, TeammateIdle.

MCP server integration

import { createAgent } from "@codeany/open-agent-sdk";

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

const result = await agent.prompt("List files in /tmp");
console.log(result.text);
await agent.close();

Subagents

import { query } from "@codeany/open-agent-sdk";

for await (const msg of query({
  prompt: "Use the code-reviewer agent to review src/index.ts",
  options: {
    agents: {
      "code-reviewer": {
        description: "Expert code reviewer",
        prompt: "Analyze code quality. Focus on security and performance.",
        tools: ["Read", "Glob", "Grep"],
      },
    },
  },
})) {
  if (msg.type === "result") console.log("Done");
}

Permissions

import { query } from "@codeany/open-agent-sdk";

// Read-only agent — can only analyze, not modify
for await (const msg of query({
  prompt: "Review the code in src/ for best practices.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "dontAsk",
  },
})) {
  // ...
}

Web UI

A built-in web chat interface is included for testing:

npx tsx examples/web/server.ts
# Open http://localhost:8081

API reference

Top-level functions

| Function | Description | | ------------------------------------- | -------------------------------------------------------------- | | query({ prompt, options }) | One-shot streaming query, returns AsyncGenerator<SDKMessage> | | createAgent(options) | Create a reusable agent with session persistence | | tool(name, desc, schema, handler) | Create a tool with Zod schema validation | | createSdkMcpServer({ name, tools }) | Bundle tools into an in-process MCP server | | defineTool(config) | Low-level tool definition helper | | getAllBaseTools() | Get all 35+ built-in tools | | registerSkill(definition) | Register a custom skill | | getAllSkills() | Get all registered skills | | createProvider(apiType, opts) | Create an LLM provider directly | | createHookRegistry(config) | Create a hook registry for lifecycle events | | listSessions() | List persisted sessions | | forkSession(id) | Fork a session for branching |

Agent methods

| Method | Description | | ------------------------------- | ----------------------------------------------------- | | agent.query(prompt) | Streaming query, returns AsyncGenerator<SDKMessage> | | agent.prompt(text) | Blocking query, returns Promise<QueryResult> | | agent.getMessages() | Get conversation history | | agent.clear() | Reset session | | agent.interrupt() | Abort current query | | agent.setModel(model) | Change model mid-session | | agent.setPermissionMode(mode) | Change permission mode | | agent.getApiType() | Get current API type | | agent.close() | Close MCP connections, persist session |

Options

| Option | Type | Default | Description | | -------------------- | --------------------------------------- | ---------------------- | -------------------------------------------------------------------- | | apiType | string | auto-detected | 'anthropic-messages' or 'openai-completions' | | model | string | claude-sonnet-4-6 | LLM model ID | | apiKey | string | CODEANY_API_KEY | API key | | baseURL | string | — | Custom API endpoint | | cwd | string | process.cwd() | Working directory | | systemPrompt | string | — | System prompt override | | appendSystemPrompt | string | — | Append to default system prompt | | tools | ToolDefinition[] | All built-in | Available tools | | allowedTools | string[] | — | Tool allow-list | | disallowedTools | string[] | — | Tool deny-list | | permissionMode | string | bypassPermissions | default / acceptEdits / dontAsk / bypassPermissions / plan | | canUseTool | function | — | Custom permission callback | | maxTurns | number | 10 | Max agentic turns | | maxBudgetUsd | number | — | Spending cap | | thinking | ThinkingConfig | { type: 'adaptive' } | Extended thinking | | effort | string | high | Reasoning effort: low / medium / high / max | | mcpServers | Record<string, McpServerConfig> | — | MCP server connections | | agents | Record<string, AgentDefinition> | — | Subagent definitions | | hooks | Record<string, HookCallbackMatcher[]> | — | Lifecycle hooks | | resume | string | — | Resume session by ID | | continue | boolean | false | Continue most recent session | | persistSession | boolean | true | Persist session to disk | | sessionId | string | auto | Explicit session ID | | outputFormat | { type: 'json_schema', schema } | — | Structured output | | sandbox | SandboxSettings | — | Filesystem/network sandbox | | settingSources | SettingSource[] | — | Load AGENT.md, project settings | | env | Record<string, string> | — | Environment variables | | abortController | AbortController | — | Cancellation controller |

Environment variables

| Variable | Description | | -------------------- | -------------------------------------------------------- | | CODEANY_API_KEY | API key (required) | | CODEANY_API_TYPE | anthropic-messages (default) or openai-completions | | CODEANY_MODEL | Default model override | | CODEANY_BASE_URL | Custom API endpoint | | CODEANY_AUTH_TOKEN | Alternative auth token |

Built-in tools

| Tool | Description | | ------------------------------------------ | -------------------------------------------- | | Bash | Execute shell commands | | Read | Read files with line numbers | | Write | Create / overwrite files | | Edit | Precise string replacement in files | | Glob | Find files by pattern | | Grep | Search file contents with regex | | WebFetch | Fetch and parse web content | | WebSearch | Search the web | | NotebookEdit | Edit Jupyter notebook cells | | Agent | Spawn subagents for parallel work | | Skill | Invoke registered skills | | TaskCreate/List/Update/Get/Stop/Output | Task management system | | TeamCreate/Delete | Multi-agent team coordination | | SendMessage | Inter-agent messaging | | EnterWorktree/ExitWorktree | Git worktree isolation | | EnterPlanMode/ExitPlanMode | Structured planning workflow | | AskUserQuestion | Ask the user for input | | ToolSearch | Discover lazy-loaded tools | | ListMcpResources/ReadMcpResource | MCP resource access | | CronCreate/Delete/List | Scheduled task management | | RemoteTrigger | Remote agent triggers | | LSP | Language Server Protocol (code intelligence) | | Config | Dynamic configuration | | TodoWrite | Session todo list |

Bundled skills

| Skill | Description | | ------------ | -------------------------------------------------------------- | | simplify | Review changed code for reuse, quality, and efficiency | | commit | Create a git commit with a well-crafted message | | review | Review code changes for correctness, security, and performance | | debug | Systematic debugging using structured investigation | | test | Run tests and analyze failures |

Register custom skills with registerSkill().

Architecture

┌──────────────────────────────────────────────────────┐
│                   Your Application                    │
│                                                       │
│   import { createAgent } from '@codeany/open-agent-sdk' │
└────────────────────────┬─────────────────────────────┘
                         │
              ┌──────────▼──────────┐
              │       Agent         │  Session state, tool pool,
              │  query() / prompt() │  MCP connections, hooks
              └──────────┬──────────┘
                         │
              ┌──────────▼──────────┐
              │    QueryEngine      │  Agentic loop:
              │   submitMessage()   │  API call → tools → repeat
              └──────────┬──────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
   ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
   │  Provider  │  │  35 Tools │  │    MCP     │
   │ Anthropic  │  │ Bash,Read │  │  Servers   │
   │  OpenAI    │  │ Edit,...  │  │ stdio/SSE/ │
   │ DeepSeek   │  │ + Skills  │  │ HTTP/SDK   │
   └───────────┘  └───────────┘  └───────────┘

Key internals:

| Component | Description | | --------------------- | ------------------------------------------------------------------ | | Provider layer | Abstracts Anthropic / OpenAI API differences | | QueryEngine | Core agentic loop with auto-compact, retry, tool orchestration | | Skill system | Reusable prompt templates with 5 bundled skills | | Hook system | 20 lifecycle events integrated into the engine | | Auto-compact | Summarizes conversation when context window fills up | | Micro-compact | Truncates oversized tool results | | Retry | Exponential backoff for rate limits and transient errors | | Token estimation | Rough token counting with pricing for Claude, GPT, DeepSeek models | | File cache | LRU cache (100 entries, 25 MB) for file reads | | Session storage | Persist / resume / fork sessions on disk | | Context injection | Git status + AGENT.md automatically injected into system prompt |

Examples

| # | File | Description | | --- | ------------------------------------- | -------------------------------------- | | 01 | examples/01-simple-query.ts | Streaming query with event handling | | 02 | examples/02-multi-tool.ts | Multi-tool orchestration (Glob + Bash) | | 03 | examples/03-multi-turn.ts | Multi-turn session persistence | | 04 | examples/04-prompt-api.ts | Blocking prompt() API | | 05 | examples/05-custom-system-prompt.ts | Custom system prompt | | 06 | examples/06-mcp-server.ts | MCP server integration | | 07 | examples/07-custom-tools.ts | Custom tools with defineTool() | | 08 | examples/08-official-api-compat.ts | query() API pattern | | 09 | examples/09-subagents.ts | Subagent delegation | | 10 | examples/10-permissions.ts | Read-only agent with tool restrictions | | 11 | examples/11-custom-mcp-tools.ts | tool() + createSdkMcpServer() | | 12 | examples/12-skills.ts | Skill system usage | | 13 | examples/13-hooks.ts | Lifecycle hooks | | 14 | examples/14-openai-compat.ts | OpenAI / DeepSeek models | | web | examples/web/ | Web chat UI for testing |

Run any example:

npx tsx examples/01-simple-query.ts

Start the web UI:

npx tsx examples/web/server.ts

Star History

License

MIT