open-agent-sdk-typescript

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)

…

Custom tools (low-level)

…

Skills

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

…

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