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

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 34 built-in tools | | listSessions() | List persisted sessions | | getSessionMessages(id) | Retrieve messages from a session | | 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.close() | Close MCP connections, persist session |

Options

| Option | Type | Default | Description | | -------------------- | --------------------------------------- | ---------------------- | -------------------------------------------------------------------- | | 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