OpenRouter Agent SDK

https://openrouter.ai/docs/agent-sdk/
Admin
The Agent SDK provides primitives for building agentic applications on OpenRouter with multi-turn...
Tokens:68,650
Snippets:819
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Quick Start Example

Source: https://openrouter.ai/docs/agent-sdk/typescript/overview

A quick start example demonstrating basic SDK usage.

```typescript
import OpenRouter from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY
});

const response = await client.chat.send({
  model: "minimax/minimax-m2",
  messages: [
    { role: "user", content: "Hello!" }
  ]
});

console.log(response.choices[0].message.content);
```

--------------------------------

### Install Dependencies

Source: https://openrouter.ai/docs/agent-sdk/call-model/examples/weather-tool

Install the necessary packages for the weather tool example.

```bash
pnpm add @openrouter/sdk zod
```

--------------------------------

### Basic Agent Setup Example

Source: https://openrouter.ai/docs/agent-sdk/usage-for-agents

Example of setting up an OpenRouter agent using callModel for basic AI model calls with type safety and streaming support.

```typescript
import { callModel } from '@openrouter/agent';

const response = await callModel({
  model: 'anthropic/claude-sonnet-4',
  messages: [
    { role: 'user', content: 'Hello!' }
  ]
});
```

--------------------------------

### Quick Start

Source: https://openrouter.ai/docs/agent-sdk/call-model/overview

A basic example demonstrating how to initialize the OpenRouter client and make a simple call to a model, then retrieve the text response.

```typescript
import { OpenRouter } from '@openrouter/agent';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const result = openrouter.callModel({
  model: 'openai/gpt-5-nano',
  input: 'What is the capital of France?',
});

// Get text (simplest pattern)
const text = await result.getText();
console.log(text); // "The capital of France is Paris."
```

--------------------------------

### Install @openrouter/agent with bun

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Install the new @openrouter/agent package using bun.

```bash
bun add @openrouter/agent
```

--------------------------------

### Claude Code Quick Start

Source: https://openrouter.ai/docs/agent-sdk/usage-for-agents

Commands to install the OpenRouter skill for Claude Code.

```bash
/plugin marketplace add OpenRouterTeam/skills
/plugin install openrouter@openrouter
```

--------------------------------

### Quick example

Source: https://openrouter.ai/docs/agent-sdk/overview

A quick example demonstrating the usage of the Agent SDK to call a model with a tool.

```typescript
import { callModel, tool } from '@openrouter/agent';
import { z } from 'zod';

const weatherTool = tool({
  name: 'get_weather',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name'),
  }),
  execute: async ({ location }) => {
    return { temperature: 72, condition: 'sunny', location };
  },
});

const result = await callModel({
  model: 'anthropic/claude-sonnet-4',
  messages: [
    { role: 'user', content: 'What is the weather in San Francisco?' },
  ],
  tools: [weatherTool],
});

const text = await result.getText();
console.log(text);
```

--------------------------------

### Install migration skill

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Command to install the migration skill for AI agents.

```bash
gh skill install OpenRouterTeam/skills openrouter-agent-migration
```

--------------------------------

### Example Usage for getting a workspace

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/workspaces

Shows how to instantiate the OpenRouter SDK and retrieve a workspace by its ID.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.workspaces.get({
    id: "production",
  });

  console.log(result);
}

run();

```

--------------------------------

### Installation

Source: https://openrouter.ai/docs/agent-sdk/typescript/overview

Command to install the OpenRouter SDK using npm.

```bash
npm install @openrouter/sdk
```

--------------------------------

### Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/providers

Demonstrates how to list all providers using the OpenRouter SDK.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.providers.list();

  console.log(result);
}

run();
```

--------------------------------

### Tool definition example

Source: https://openrouter.ai/docs/agent-sdk/overview

Example of defining a tool with the `tool()` helper.

```typescript
import { tool } from '@openrouter/agent';
import { z } from 'zod';

const searchTool = tool({
  name: 'search',
  description: 'Search the web',
  inputSchema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    // Your search implementation
    return { results: ['...'] };
  },
});
```

--------------------------------

### Prerequisites

Source: https://openrouter.ai/docs/agent-sdk/call-model/examples/skills-loader

Install necessary packages and create directories for skills.

```bash
pnpm add @openrouter/sdk zod

```bash
mkdir -p ~/.claude/skills/pdf-processing
mkdir -p ~/.claude/skills/data-analysis
mkdir -p ~/.claude/skills/code-review
```

--------------------------------

### Install @openrouter/agent with yarn

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Install the new @openrouter/agent package using yarn.

```bash
yarn add @openrouter/agent
```

--------------------------------

### Usage Example

Source: https://openrouter.ai/docs/agent-sdk/call-model/examples/weather-tool

Demonstrates how to call the model with the defined weather tool to get weather information for a city.

```typescript
const result = openrouter.callModel({
  model: 'openai/gpt-5-nano',
  input: 'What is the weather like in Tokyo?',
  tools: [weatherTool],
});

const text = await result.getText();
console.log(text);
// "The current weather in Tokyo, Japan is partly cloudy with a temperature
// of 22°C (feels like 24°C). Humidity is at 65% with winds from the SW
// at 15 km/h."
```

--------------------------------

### Install @openrouter/agent with npm

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Install the new @openrouter/agent package using npm.

```bash
npm install @openrouter/agent
```

--------------------------------

### Usage Example

Source: https://openrouter.ai/docs/agent-sdk/call-model/examples/skills-loader

An example of how to use the skills tool in a call to the OpenRouter API.

```typescript
const result = openrouter.callModel({
  model: 'anthropic/claude-sonnet-4.5',
  input: 'I need to process a PDF and extract tables from it',
  tools: [skillsTool],
});

const text = await result.getText();
// The model will call the Skill tool, loading pdf-processing context
// Subsequent responses will have access to the skill's instructions

```

--------------------------------

### React Example

Source: https://openrouter.ai/docs/agent-sdk/call-model/streaming

This example demonstrates how to use streaming in a React component to display a chat response as it's being generated.

```typescript
import { useState, useEffect } from 'react';

function ChatResponse({ prompt }: { prompt: string }) {
  const [text, setText] = useState('');
  const [isStreaming, setIsStreaming] = useState(true);

  useEffect(() => {
    const openrouter = new OpenRouter({ apiKey: API_KEY });

    const result = openrouter.callModel({
      model: 'openai/gpt-5-nano',
      input: prompt,
    });

    (async () => {
      for await (const delta of result.getTextStream()) {
        setText(prev => prev + delta);
      }
      setIsStreaming(false);
    })();

    return () => {
      result.cancel();
    };
  }, [prompt]);

  return (
    <div>
      <p>{text}</p>
      {isStreaming && <span className="cursor">|</span>}
    </div>
  );
}

```

--------------------------------

### Example Skill File

Source: https://openrouter.ai/docs/agent-sdk/call-model/examples/skills-loader

Content for an example skill file (`~/.claude/skills/pdf-processing/SKILL.md`) that defines capabilities, best practices, and output formats for PDF processing.

```markdown
# PDF Processing Skill

You are now equipped with PDF processing capabilities.

## Available Tools
When processing PDFs, you have access to:
- `extract_text`: Extract all text from a PDF
- `extract_tables`: Extract tables as structured data
- `extract_images`: Extract embedded images
- `split_pdf`: Split PDF into individual pages

## Best Practices
1. Always check PDF file size before processing
2. For large PDFs (>50 pages), process in chunks
3. OCR may be needed for scanned documents
4. Tables may span multiple pages - handle accordingly

## Output Formats
- Text: Plain text or markdown
- Tables: JSON, CSV, or markdown tables
- Images: PNG with sequential naming

## Error Handling
- If a PDF is encrypted, request the password
- If OCR fails, suggest alternative approaches
- Report page numbers for any extraction errors

```

--------------------------------

### Complete Example: Approval Gates with State Persistence

Source: https://openrouter.ai/docs/agent-sdk/call-model/tool-approval-state

An end-to-end example demonstrating approval gates with state persistence, including defining a tool that requires approval, setting up state accessors, making the initial model call, checking for approval needs, presenting pending tool calls, and resuming the model call with approval decisions.

```typescript
import { OpenRouter, tool } from '@openrouter/agent';
import type { ConversationState, StateAccessor } from '@openrouter/agent';
import { z } from 'zod';

// 1. Define a tool with approval required
const sendEmailTool = tool({
  name: 'send_email',
  description: 'Send an email',
  inputSchema: z.object({
    to: z.string().email(),
    subject: z.string(),
    body: z.string(),
  }),
  outputSchema: z.object({ sent: z.boolean(), messageId: z.string() }),
  requireApproval: true,
  execute: async (params) => {
    const result = await sendEmail(params);
    return { sent: true, messageId: result.id };
  },
});

// 2. Create a state accessor (in-memory for this example)
const store = new Map<string, ConversationState>();
const conversationId = 'conv-123';

const state: StateAccessor = {
  load: async () => store.get(conversationId) ?? null,
  save: async (s) => { store.set(conversationId, s); },
};

const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

// 3. First callModel — model will try to call the tool
const result = openrouter.callModel({
  model: 'openai/gpt-4o',
  input: 'Send a welcome email to alice@example.com',
  tools: [sendEmailTool] as const,
  state,
});

// 4. Check if approval is needed
if (await result.requiresApproval()) {
  const pending = await result.getPendingToolCalls();

  for (const call of pending) {
    console.log(`Tool: ${call.name}`);
    console.log(`To: ${call.arguments.to}`);
    console.log(`Subject: ${call.arguments.subject}`);
    console.log(`ID: ${call.id}`);
  }

  // 5. Present to user for decision, then resume
  const approved = await askUserForApproval(pending);

  const approvedIds = approved.filter(a => a.decision === 'approve').map(a => a.id);
  const rejectedIds = approved.filter(a => a.decision === 'reject').map(a => a.id);

  // 6. Second callModel — resume with approval decisions
  const resumed = openrouter.callModel({
    model: 'openai/gpt-4o',
    input: [], // No new user input needed for resumption
    tools: [sendEmailTool] as const,
    state,
    approveToolCalls: approvedIds,
    rejectToolCalls: rejectedIds,
  });

  // 7. Get the final response
  const text = await resumed.getText();
  console.log(text);
  // "I've sent the welcome email to alice@example.com."
} else {
  // No approval needed — tool ran automatically
  const text = await result.getText();
  console.log(text);
}

```

--------------------------------

### Example Usage - Create Workspace

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/workspaces

Demonstrates how to create a new workspace using the OpenRouter SDK.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.workspaces.create({
    createWorkspaceRequest: {
      defaultImageModel: "openai/dall-e-3",
      defaultProviderSort: "price",
      defaultTextModel: "openai/gpt-4o",
      description: "Production environment workspace",
      name: "Production",
      slug: "production",
    },
  });

  console.log(result);
}

run();
```

--------------------------------

### Install @openrouter/agent with pnpm

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Install the new @openrouter/agent package using pnpm.

```bash
pnpm add @openrouter/agent
```

--------------------------------

### Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/guardrails

Demonstrates how to fetch a guardrail using the OpenRouter SDK.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.guardrails.get({
    id: "550e8400-e29b-41d4-a716-446655440000",
  });

  console.log(result);
}

run();
```

--------------------------------

### Get API Key - Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/apikeys

Example of how to retrieve a single API key by its hash using the `openRouter.apiKeys.get` method.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.apiKeys.get({
    hash: "f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943",
  });

  console.log(result);
}

run();
```

--------------------------------

### Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/oauth

Demonstrates how to create an authorization code using the OpenRouter SDK for the PKCE flow.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.oAuth.createAuthCode({
    requestBody: {
      callbackUrl: "https://myapp.com/auth/callback",
      codeChallenge: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
      codeChallengeMethod: "S256",
      limit: 100,
    },
  });

  console.log(result);
}

run();

```

--------------------------------

### GitHub CLI Installation

Source: https://openrouter.ai/docs/agent-sdk/usage-for-agents

Command to install the openrouter-typescript-sdk skill using GitHub CLI.

```bash
gh skill install OpenRouterTeam/skills openrouter-typescript-sdk
```

--------------------------------

### List Workspaces Example

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/workspaces

Demonstrates how to list all workspaces for the authenticated user using the OpenRouter SDK.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.workspaces.list();

  for await (const page of result) {
    console.log(page);
  }
}

run();

```

--------------------------------

### Human-in-the-Loop (HITL) Tool Example

Source: https://openrouter.ai/docs/agent-sdk/call-model/tools

An example of a HITL tool that automatically approves small payments and escalates larger ones to a human.

```typescript
const approvePaymentTool = tool({
  name: 'approve_payment',
  description: 'Approve a payment, escalating large amounts to a human',
  inputSchema: z.object({
    amount: z.number(),
    recipient: z.string(),
  }),
  outputSchema: z.object({
    ok: z.boolean(),
    reviewedAt: z.number().optional(),
  }),
  onToolCalled: async (input) => {
    // Auto-approve small amounts
    if (input.amount < 100) {
      return { ok: true };
    }
    // Escalate to a human — pauses the loop
    return null;
  },
  onResponseReceived: async (raw) => {
    // Post-process the caller-supplied result before the model sees it
    return { ...(raw as object), reviewedAt: Date.now() };
  },
});
```

--------------------------------

### DevTools Server Configuration Example

Source: https://openrouter.ai/docs/agent-sdk/dev-tools/devtools

Example of configuring the DevTools server port in the OpenRouter CLI configuration file.

```json
{
  "DEVTOOLS_PORT": 4983
}
```

--------------------------------

### Example Usage for bulkAssignKeys

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/guardrails

Shows how to use the `openRouter.guardrails.bulkAssignKeys` method to assign multiple API keys to a guardrail.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.guardrails.bulkAssignKeys({
    id: "550e8400-e29b-41d4-a716-446655440000",
    bulkAssignKeysRequest: {
      keyHashes: [
        "c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93",
      ],
    },
  });

  console.log(result);
}

run();

```

--------------------------------

### Basic Example of nextTurnParams

Source: https://openrouter.ai/docs/agent-sdk/call-model/next-turn-params

This example demonstrates how to use nextTurnParams to modify instructions and temperature for a tool that enables expert mode.

```typescript
import { tool } from '@openrouter/agent';
import { z } from 'zod';

const expertModeTool = tool({
  name: 'enable_expert_mode',
  description: 'Enable expert mode for detailed technical responses',
  inputSchema: z.object({
    domain: z.string().describe('Technical domain (e.g., "kubernetes", "react")'),
  }),
  outputSchema: z.object({ enabled: z.boolean() }),

  nextTurnParams: {
    instructions: (params, context) => {
      const base = context.instructions ?? '';
      return `${base}` +
`
EXPERT MODE ENABLED for ${params.domain}:
- Provide detailed technical explanations
- Include code examples and best practices
- Reference official documentation
- Assume advanced knowledge`;
    },
    temperature: () => 0.3, // More precise for technical content
  },

  execute: async (params) => {
    return { enabled: true };
  },
});
```

--------------------------------

### Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/guardrails

Demonstrates how to update an existing guardrail using the OpenRouter SDK.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.guardrails.update({
    id: "550e8400-e29b-41d4-a716-446655440000",
    updateGuardrailRequest: {
      description: "Updated description",
      limitUsd: 75,
      name: "Updated Guardrail Name",
      resetInterval: "weekly",
    },
  });

  console.log(result);
}

run();
```

--------------------------------

### Example of using both packages together

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Demonstrates how to import and use components from both the '@openrouter/sdk' and '@openrouter/agent' packages in a TypeScript project.

```typescript
import OpenRouter from '@openrouter/sdk';
import { callModel } from '@openrouter/agent/call-model';
import { tool } from '@openrouter/agent/tool';
```

--------------------------------

### Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/guardrails

Demonstrates how to create a new guardrail using the OpenRouter SDK's `guardrails.create` method.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.guardrails.create({
    createGuardrailRequest: {
      allowedModels: null,
      allowedProviders: [
        "openai",
        "anthropic",
        "deepseek",
      ],
      description: "A guardrail for limiting API usage",
      enforceZdrAnthropic: true,
      enforceZdrGoogle: false,
      enforceZdrOpenai: true,
      enforceZdrOther: false,
      ignoredModels: null,
      ignoredProviders: null,
      limitUsd: 50,
      name: "My New Guardrail",
      resetInterval: "monthly",
    },
  });

  console.log(result);
}

run();

```

--------------------------------

### Message Streaming Example

Source: https://openrouter.ai/docs/agent-sdk/call-model/working-with-items

Demonstrates how message items are emitted progressively with the same ID but updated content during streaming.

```typescript
// Iteration 1
{
  id: "msg_123",
  type: "message",
  content: [{ type: "output_text", text: "Hello" }]
}

// Iteration 2
{
  id: "msg_123",
  type: "message",
  content: [{ type: "output_text", text: "Hello world" }]
}

// Iteration 3
{
  id: "msg_123",
  type: "message",
  content: [{ type: "output_text", text: "Hello world!" }]
}
```

--------------------------------

### Agent with Tool Definition Example

Source: https://openrouter.ai/docs/agent-sdk/usage-for-agents

Example demonstrating how to add a tool to an agent using the tool() helper and Zod schemas for structured input.

```typescript
import { callModel, tool } from '@openrouter/agent';
import { z } from 'zod';

const searchTool = tool({
  name: 'search',
  description: 'Search the web',
  inputSchema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    return { results: ['...'] };
  },
});

const result = await callModel({
  model: 'anthropic/claude-sonnet-4',
  messages: [{ role: 'user', content: 'Search for TypeScript best practices' }],
  tools: [searchTool],
});
```

--------------------------------

### Example Usage of bulkAddMembers

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/workspaces

Demonstrates how to add multiple organization members to a workspace using the SDK.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.workspaces.bulkAddMembers({
    id: "production",
    bulkAddWorkspaceMembersRequest: {
      userIds: [
        "user_abc123",
        "user_def456",
      ],
    },
  });

  console.log(result);
}

run();

```

--------------------------------

### Descriptive Names and Descriptions

Source: https://openrouter.ai/docs/agent-sdk/call-model/tools

Example of good practice for naming and describing tools for clarity.

```typescript
// Good: Clear name and description
const tool1 = tool({
  name: 'search_knowledge_base',
  description: 'Search the company knowledge base for documents, FAQs, and policies. Returns relevant articles with snippets.',
  // ...
});

// Avoid: Vague or generic
const tool2 = tool({
  name: 'search',
  description: 'Searches stuff',
  // ...
});
```

--------------------------------

### Update Workspace Example

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/workspaces

Demonstrates how to update an existing workspace using the OpenRouter SDK.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.workspaces.update({
    id: "production",
    updateWorkspaceRequest: {
      name: "Updated Workspace",
      slug: "updated-workspace",
    },
  });

  console.log(result);
}

run();
```

--------------------------------

### Example Usage for listKeyAssignments

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/guardrails

Demonstrates how to list all API key guardrail assignments using the `listKeyAssignments` method.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.guardrails.listKeyAssignments();

  for await (const page of result) {
    console.log(page);
  }
}

run();

```

--------------------------------

### Update async parameters imports

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Example of updating imports for async parameters.

```diff
- import type {
-   CallModelInput,
- } from '@openrouter/sdk/lib/async-params';
+ import type {
+   CallModelInput,
+ } from '@openrouter/agent/async-params';
```

--------------------------------

### Function Call Streaming Example

Source: https://openrouter.ai/docs/agent-sdk/call-model/working-with-items

Illustrates how function call items are streamed, with arguments being updated incrementally until complete.

```typescript
// Iteration 1
{ type: "function_call", callId: "call_456", arguments: "{\"q" }

// Iteration 2
{
  type: "function_call",
  callId: "call_456",
  arguments: "{\"query": \"weather" 
}

// Iteration 3
{
  type: "function_call",
  callId: "call_456",
  arguments: "{\"query": \"weather in Paris\"}" 
}
```

--------------------------------

### Update core imports

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Example of updating core imports like callModel and ModelResult.

```diff
- import { callModel } from '@openrouter/sdk/funcs/call-model';
+ import { callModel } from '@openrouter/agent/call-model';

- import { ModelResult } from '@openrouter/sdk/lib/model-result';
+ import { ModelResult } from '@openrouter/agent/model-result';

- import { tool } from '@openrouter/sdk/lib/tool';
+ import { tool } from '@openrouter/agent/tool';
```

--------------------------------

### Create API Key

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/apikeys

Example of how to create a new API key for the authenticated user.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.apiKeys.create({
    requestBody: {
      expiresAt: new Date("2027-12-31T23:59:59Z"),
      includeByokInLimit: true,
      limit: 50,
      limitReset: "monthly",
      name: "My New API Key",
    },
  });

  console.log(result);
}

run();
```

--------------------------------

### Example Usage for listForUser

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/models/models

Shows how to list models filtered by user preferences using the `OpenRouter` SDK.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
});

async function run() {
  const result = await openRouter.models.listForUser({
    bearer: process.env["OPENROUTER_BEARER"] ?? "",
  });

  console.log(result);
}

run();
```

--------------------------------

### Update tool types and guards imports

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Example of updating imports for tool types and guards.

```diff
- import type { Tool } from '@openrouter/sdk/lib/tool-types';
+ import type { Tool } from '@openrouter/agent/tool-types';

- import {
-   hasExecuteFunction,
-   isGeneratorTool,
- } from '@openrouter/sdk/lib/tool-types';
+ import {
+   hasExecuteFunction,
+   isGeneratorTool,
+ } from '@openrouter/agent/tool-types';
```

--------------------------------

### Stream reasoning process

Source: https://openrouter.ai/docs/agent-sdk/call-model/streaming

This example shows how to stream the reasoning process for models that support it.

```typescript
const result = openrouter.callModel({
  model: 'openai/o1-preview',
  input: 'Solve this step by step: If x + 5 = 12, what is x?',
});

console.log('Reasoning:');
for await (const delta of result.getReasoningStream()) {
  process.stdout.write(delta);
}

console.log('\n\nFinal answer:');
const text = await result.getText();
console.log(text);
```

--------------------------------

### Type Inference Example

Source: https://openrouter.ai/docs/agent-sdk/call-model/tools

Utilities to extract input, output, and event types from tools.

```typescript
import type { InferToolInput, InferToolOutput, InferToolEvent } from '@openrouter/agent';

// Get the input type
type WeatherInput = InferToolInput<typeof weatherTool>;
// { location: string }

// Get the output type
type WeatherOutput = InferToolOutput<typeof weatherTool>;
// { temperature: number; conditions: string }

// Get event type (generator tools only)
type SearchEvent = InferToolEvent<typeof searchTool>;
// { progress: number; message: string }
```

--------------------------------

### Get API Key - Standalone Function

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/apikeys

Example of how to get a single API key using the standalone `apiKeysGet` function.

```typescript
import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { apiKeysGet } from "@openrouter/sdk/funcs/apiKeysGet.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await apiKeysGet(openRouter, {
    hash: "f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("apiKeysGet failed:", res.error);
  }
}

run();
```

--------------------------------

### Complete Example: Using Multiple Skills

Source: https://openrouter.ai/docs/agent-sdk/call-model/examples/skills-loader

Demonstrates how to use the skill discovery tool, a skills tool, and a multi-skill loader together to handle a complex task involving multiple steps.

```typescript
import { OpenRouter, tool, stepCountIs } from '@openrouter/agent';
import { readFileSync, existsSync, readdirSync } from 'fs';
import path from 'path';
import { z } from 'zod';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const SKILLS_DIR = path.join(process.env.HOME || '~', '.claude', 'skills');

// ... (include skillsTool, multiSkillLoader, skillDiscoveryTool from above)

// Use all skill tools together
const result = openrouter.callModel({
  model: 'anthropic/claude-sonnet-4.5',
  input: `I have a complex task:
1. First, show me what skills are available
2. Load the appropriate skills for PDF analysis
3. Then help me extract and analyze data from report.pdf`,
  tools: [skillDiscoveryTool, skillsTool, multiSkillLoader],
  stopWhen: stepCountIs(10),
});

const text = await result.getText();
console.log(text);
```

--------------------------------

### Get total count of available models

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/models/models

Example usage of the `count` method to get the total number of available models.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.models.count();

  console.log(result);
}

run();
```

--------------------------------

### list Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/endpoints

Demonstrates how to use the `list` method from the OpenRouter SDK to list all endpoints for a model.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.endpoints.list({
    author: "<value>",
    slug: "<value>",
  });

  console.log(result);
}

run();
```

--------------------------------

### Verify build

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Commands to run after migration to verify the build and tests.

```bash
npx tsc --noEmit
npm test
```

--------------------------------

### Stop conditions example

Source: https://openrouter.ai/docs/agent-sdk/overview

Example of controlling agent loop termination with stop conditions.

```typescript
import { callModel, stepCountIs, maxCost } from '@openrouter/agent';

const result = await callModel({
  model: 'anthropic/claude-sonnet-4',
  messages: [{ role: 'user', content: 'Research this topic thoroughly' }],
  tools: [searchTool],
  stopWhen: [stepCountIs(10), maxCost(0.50)],
});
```

--------------------------------

### Install DevTools Package

Source: https://openrouter.ai/docs/agent-sdk/dev-tools/devtools

Installs the DevTools package as a development dependency using npm.

```bash
npm install @openrouter/devtools --save-dev
```

--------------------------------

### Basic Skills Tool

Source: https://openrouter.ai/docs/agent-sdk/call-model/examples/skills-loader

A TypeScript example demonstrating how to create a tool that loads and injects domain-specific skills into the conversation context.

```typescript
import { OpenRouter, tool } from '@openrouter/agent';
import { readFileSync, existsSync, readdirSync } from 'fs';
import path from 'path';
import { z } from 'zod';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const SKILLS_DIR = path.join(process.env.HOME || '~', '.claude', 'skills');

// List available skills
const listAvailableSkills = (): string[] => {
  if (!existsSync(SKILLS_DIR)) return [];
  return readdirSync(SKILLS_DIR, { withFileTypes: true })
    .filter((dirent) => dirent.isDirectory())
    .filter((dirent) => existsSync(path.join(SKILLS_DIR, dirent.name, 'SKILL.md')))
    .map((dirent) => dirent.name);
};

const skillsTool = tool({
  name: 'Skill',
  description: `Load a specialized skill to enhance the assistant's capabilities.
Available skills: ${listAvailableSkills().join(', ') || 'none configured'}
Each skill provides domain-specific instructions and capabilities.`, 

  inputSchema: z.object({
    type: z.string().describe("The skill type to load (e.g., 'pdf-processing')"),
  }),

  outputSchema: z.string(),

  // This is where the magic happens - modify context for next turn
  nextTurnParams: {
    input: (params, context) => {
      // Prevent duplicate skill loading
      const skillMarker = `[Skill: ${params.type}]`;
      if (JSON.stringify(context.input).includes(skillMarker)) {
        return context.input;
      }

      // Load the skill's instructions
      const skillPath = path.join(SKILLS_DIR, params.type, 'SKILL.md');
      if (!existsSync(skillPath)) {
        return context.input;
      }

      const skill = readFileSync(skillPath, 'utf-8');
      const skillDir = path.join(SKILLS_DIR, params.type);

      // Inject skill context into the conversation
      const currentInput = Array.isArray(context.input) ? context.input : [context.input];

      return [
        ...currentInput,
        {
          role: 'user',
          content: `${skillMarker}
Base directory for this skill: ${skillDir}

${skill}`,
        },
      ];
    },
  },

  execute: async (params, context) => {
    const skillMarker = `[Skill: ${params.type}]`;

    // Check if already loaded
    if (JSON.stringify(context?.turnRequest?.input || []).includes(skillMarker)) {
      return `Skill ${params.type} is already loaded`;
    }

    const skillPath = path.join(SKILLS_DIR, params.type, 'SKILL.md');
    if (!existsSync(skillPath)) {
      const available = listAvailableSkills();
      return `Skill "${params.type}" not found. Available skills: ${available.join(', ') || 'none'}`;
    }

    return `Launching skill ${params.type}`;
  },
});

```

--------------------------------

### Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/rerank

Submits a rerank request to the rerank router.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.rerank.rerank({
    requestBody: {
      documents: [
        "Paris is the capital of France.",
        "Berlin is the capital of Germany.",
      ],
      model: "cohere/rerank-v3.5",
      query: "What is the capital of France?",
    },
  });

  console.log(result);
}

run();

```

--------------------------------

### Launch DevTools Viewer

Source: https://openrouter.ai/docs/agent-sdk/dev-tools/devtools

Launches the DevTools web interface from the command line.

```bash
openrouter devtools
```

--------------------------------

### getToolCalls()

Source: https://openrouter.ai/docs/agent-sdk/call-model/api-reference

Get all tool calls from initial response.

```typescript
getToolCalls(): Promise<ParsedToolCall[]>
```

--------------------------------

### Context-Aware Instructions Pattern

Source: https://openrouter.ai/docs/agent-sdk/call-model/dynamic-parameters

An example of dynamically generating instructions for the AI model based on the conversation's state, such as the number of turns.

```typescript
const result = openrouter.callModel({
  model: 'openai/gpt-5-nano',
  instructions: (ctx) => {
    const base = 'You are a helpful assistant.';
    const turnInfo = `This is turn ${ctx.numberOfTurns} of the conversation.`;

    // Add context based on history length
    if (ctx.numberOfTurns > 5) {
      return `${base}\n${turnInfo}\nKeep responses concise - this is a long conversation.`;
    }

    return `${base}\n${turnInfo}`;
  },
  input: 'Continue helping me...', 
  tools: [helpTool],
});
```

--------------------------------

### Update stop conditions imports

Source: https://openrouter.ai/docs/agent-sdk/agent-migration

Example of updating imports for stop conditions.

```diff
- import {
-   stepCountIs,
-   hasToolCall,
-   maxCost,
- } from '@openrouter/sdk/lib/stop-conditions';
+ import {
+   stepCountIs,
+   hasToolCall,
+   maxCost,
+ } from '@openrouter/agent/stop-conditions';
```

--------------------------------

### getText()

Source: https://openrouter.ai/docs/agent-sdk/call-model/api-reference

Get text content after tool execution completes.

```typescript
getText(): Promise<string>
```

--------------------------------

### Delete an existing guardrail

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/guardrails

Example usage of the `delete` method to remove a guardrail by its ID.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.guardrails.delete({
    id: "550e8400-e29b-41d4-a716-446655440000",
  });

  console.log(result);
}

run();
```

--------------------------------

### New Models Available Instantly

Source: https://openrouter.ai/docs/agent-sdk/typescript/overview

Demonstrates how new models are immediately available for use with the SDK.

```typescript
// When new models launch, they're available instantly
const response = await client.chat.send({
  model: "minimax/minimax-m2",
});
```

--------------------------------

### List all models and their properties

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/models/models

Example usage of the `list` method to retrieve all models and their properties.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.models.list();

  console.log(result);
}

run();
```

--------------------------------

### Tool Methods

Source: https://openrouter.ai/docs/agent-sdk/call-model/overview

Examples for retrieving and streaming tool calls from a model's response, including streaming tool deltas and preliminary results.

```typescript
// Get all tool calls from the response
const toolCalls = await result.getToolCalls();

// Stream tool calls as they complete
for await (const toolCall of result.getToolCallsStream()) {
  console.log(`Tool: ${toolCall.name}`, toolCall.arguments);
}

// Stream tool deltas and preliminary results
for await (const event of result.getToolStream()) {
  if (event.type === 'delta') {
    process.stdout.write(event.content);
  } else if (event.type === 'preliminary_result') {
    console.log('Progress:', event.result);
  }
}
```

--------------------------------

### Actionable Error Messages

Source: https://openrouter.ai/docs/agent-sdk/typescript/overview

Example of specific, actionable error messages provided by the SDK.

```typescript
// Instead of generic errors, get specific guidance:
// "Model 'openai/o1-preview' requires at least 2 messages.
//  You provided 1 message. Add a system or user message."
```

--------------------------------

### Standalone Function Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/endpoints

Example of how to use the standalone `endpointsList` function from the OpenRouter SDK.

```typescript
import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { endpointsList } from "@openrouter/sdk/funcs/endpointsList.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await endpointsList(openRouter, {
    author: "<value>",
    slug: "<value>",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("endpointsList failed:", res.error);
  }
}

run();
```

--------------------------------

### System Instructions

Source: https://openrouter.ai/docs/agent-sdk/call-model/text-generation

Shows how to set the model's behavior using the `instructions` parameter.

```typescript
const result = openrouter.callModel({
  model: 'openai/gpt-5-nano',
  instructions: 'You are a helpful coding assistant. Be concise and provide working code examples.',
  input: 'How do I read a file in Node.js?',
});
```

--------------------------------

### Basic Chat Completion

Source: https://openrouter.ai/docs/agent-sdk/typescript/overview

A basic example of sending a chat message using the SDK.

```typescript
import OpenRouter from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY
});

const response = await client.chat.send({
  model: "minimax/minimax-m2",
  messages: [
    { role: "user", content: "Explain quantum computing" }
  ]
});
```

--------------------------------

### Example Usage

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/videogeneration

Demonstrates how to use the getVideoContent method from the OpenRouter SDK to retrieve video generation job content.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.videoGeneration.getVideoContent({
    jobId: "job-abc123",
  });

  console.log(result);
}

run();
```

--------------------------------

### getResponse()

Source: https://openrouter.ai/docs/agent-sdk/call-model/api-reference

Get full response with usage data (inputTokens, outputTokens, cachedTokens).

```typescript
getResponse(): Promise<OpenResponsesNonStreamingResponse>
```

--------------------------------

### Example Usage of bulkRemoveMembers

Source: https://openrouter.ai/docs/agent-sdk/typescript/api-reference/workspaces

Demonstrates how to use the `bulkRemoveMembers` method to remove multiple members from a workspace.

```typescript
import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.workspaces.bulkRemoveMembers({
    id: "production",
    bulkRemoveWorkspaceMembersRequest: {
      userIds: [
        "user_abc123",
        "user_def456",
      ],
    },
  });

  console.log(result);
}

run();
```
Tokens:
Raw