Getting Started

Installation

Install the SDK with your preferred package manager:

npm

npm install one-agent-sdk

pnpm

pnpm add one-agent-sdk

yarn

yarn add one-agent-sdk

bun

bun add one-agent-sdk

Then install the provider SDK for your backend:

Claude

npm install @anthropic-ai/claude-agent-sdk

Codex

npm install @openai/codex-sdk

Copilot

npm install @github/copilot-sdk

Kimi

npm install @moonshot-ai/kimi-agent-sdk

OpenAI API

npm install openai

Anthropic API

npm install @anthropic-ai/sdk

OpenRouter

npm install openai

Quick Start

one-agent-sdk is a drop-in replacement for @anthropic-ai/claude-agent-sdk. Same API, multiple providers:

import { z } from "zod";
import { query, tool, createSdkMcpServer } from "one-agent-sdk";

// Define a tool (same as @anthropic-ai/claude-agent-sdk)
const weatherTool = tool(
  "get_weather",
  "Get the current weather for a city",
  { city: z.string().describe("City name") },
  async ({ city }) => ({
    content: [{ type: "text" as const, text: JSON.stringify({ city, temperature: 72, condition: "sunny" }) }],
  }),
);

const mcpServer = createSdkMcpServer({
  name: "tools",
  version: "1.0.0",
  tools: [weatherTool],
});

// query() defaults to claude-code — pass options.provider to switch
const conversation = query({
  prompt: "What's the weather in San Francisco?",
  options: {
    systemPrompt: "You are a helpful assistant. Use the weather tool when asked about weather.",
    mcpServers: { tools: mcpServer },
    allowedTools: ["mcp__tools__get_weather"],
  },
});

for await (const msg of conversation) {
  if (msg.type === "assistant" && msg.message?.content) {
    for (const block of msg.message.content) {
      if ("text" in block && block.text) process.stdout.write(block.text);
    }
  }
}

Switching Providers

Pass options.provider to route to a different backend:

// Use Codex instead of Claude
const conversation = query({
  prompt: "What's the weather in San Francisco?",
  options: {
    provider: "codex", // or "openai", "anthropic", "openrouter", "kimi-cli", ...
    systemPrompt: "You are a helpful assistant.",
  },
});

The output stream emits the same SDKMessage format regardless of backend.

What's Next?

• Learn about Tools with type-safe parameters
• Understand the Streaming interface
• Compare Providers and register custom ones
• Add Middleware to transform streams
• Manage Sessions for multi-turn conversations
• Get typed responses with Structured Output