Agent SDK

The Agent SDK (@openrouter/agent) provides the primitives you need to build agentic applications on OpenRouter. Instead of manually wiring up conversation loops, tool dispatch, and state tracking, the Agent SDK handles all of that so you can focus on defining what your agent does.

The Agent SDK is built to work alongside the Client SDKs. Installing @openrouter/agent automatically includes the Client SDKs as well, but each package can work independently.

When to use the Agent SDK

Choose the Agent SDK when you need agentic behavior — multi-step reasoning where the model calls tools, processes results, and decides what to do next:

• Multi-turn agent loops — callModel automatically loops until a stop condition is met
• Tool definitions — define tools with the tool() helper and the SDK executes them for you
• Stop conditions — control when the loop ends with stepCountIs, hasToolCall, maxCost, and more
• Conversation state — the SDK tracks messages, tool results, and context across turns
• Streaming — real-time token output within each agent step
• Dynamic parameters — change model, temperature, or tools between turns based on context

Installation

$
npm install @openrouter/agent

Quick example

1
import { callModel, tool } from '@openrouter/agent';
2
import { z } from 'zod';
3
4
const weatherTool = tool({
5
  name: 'get_weather',
6
  description: 'Get the current weather for a location',
7
  inputSchema: z.object({
8
    location: z.string().describe('City name'),
9
  }),
10
  execute: async ({ location }) => {
11
    return { temperature: 72, condition: 'sunny', location };
12
  },
13
});
14
15
const result = await callModel({
16
  model: 'anthropic/claude-sonnet-4',
17
  messages: [
18
    { role: 'user', content: 'What is the weather in San Francisco?' },
19
  ],
20
  tools: [weatherTool],
21
});
22
23
const text = await result.getText();
24
console.log(text);

The SDK sends the message to the model, receives a tool call, executes get_weather, feeds the result back, and returns the final response — all in one callModel invocation.

Core concepts

callModel

The main entry point. It runs an inference loop that:

1. Sends messages to the model
2. If the model returns tool calls, executes them automatically
3. Appends tool results to the conversation
4. Repeats until a stop condition is met or no more tool calls are made

See the Call Model documentation for the full API.

Tools

Define tools with the tool() helper. Each tool has a name, description, Zod parameter schema, and an execute function. The SDK handles serialization, validation, and dispatch.

1
import { tool } from '@openrouter/agent';
2
import { z } from 'zod';
3
4
const searchTool = tool({
5
  name: 'search',
6
  description: 'Search the web',
7
  inputSchema: z.object({ query: z.string() }),
8
  execute: async ({ query }) => {
9
    // Your search implementation
10
    return { results: ['...'] };
11
  },
12
});

Stop conditions

Control when the agent loop terminates:

1
import { callModel, stepCountIs, maxCost } from '@openrouter/agent';
2
3
const result = await callModel({
4
  model: 'anthropic/claude-sonnet-4',
5
  messages: [{ role: 'user', content: 'Research this topic thoroughly' }],
6
  tools: [searchTool],
7
  stopWhen: [stepCountIs(10), maxCost(0.50)],
8
});

Agent SDK vs Client SDKs

Next steps

• Call Model — the complete callModel API reference
• Tools — defining and using tools
• Stop Conditions — controlling agent loop termination
• Streaming — real-time token output
• DevTools — telemetry capture and visualization for development
• Migrating from @openrouter/sdk — move agent imports to the standalone package