OpenRouter
Model-agnostic agent loops over 400+ models, with tools, streaming, and stop conditions built in.
GitHub Stars
—
Contributors
—
npm / Week
—
PyPI / Month
—
OpenRouter Agent SDK is a TypeScript agent toolkit maintained by OpenRouter, designed to eliminate the boilerplate of building multi-turn agent loops. Instead of wiring tool dispatch, conversation state, and loop termination yourself, you get a single callModel function that handles all of that on top of OpenRouter’s gateway to 400+ models.
The framework occupies a specific niche: it is an inference SDK and agent runtime that prioritizes model flexibility and type safety over multi-agent orchestration. It is built for teams who want to build tool-calling agents that can swap between providers (OpenAI, Anthropic, Google, Mistral, and dozens more) without changing application code. This contrasts with frameworks like LangChain or CrewAI, which bundle broader orchestration layers but tie you to specific provider SDK patterns unless you add adapters.
OpenRouter released the SDK in 2026 under Apache 2.0. It is still in public beta, meaning breaking changes between versions are expected. The project has 18 stars on GitHub at the time of writing, reflecting its early stage rather than its utility. Practitioners should evaluate it for what it does well: rapid prototyping and production deployment of single-agent, tool-calling workflows with cost controls and zero provider lock-in.
What the framework gives you out of the box, in plain language.
The jobs this framework is best suited for.
Build tool-calling agents that swap between models from any provider without changing app code.
Use the maxCost stop condition to bound spend on long multi-step loops before they run away.
Single-agent apps that call tools and stream token output back to the UI within each step.
Side-by-Side
Add a second or third framework and see stars, downloads, and capabilities lined up next to each other.
The SDK is imperative and code-first. You write TypeScript functions that call callModel, define tools with the tool() helper and Zod schemas, and set stop conditions to control execution flow.
The core abstraction is the agent loop. callModel accepts a model identifier (or string), an array of messages, an array of tool definitions, and stop conditions. It runs the multi-turn loop internally: call the model, inspect the response for tool calls, execute those tools, append results to the conversation, and repeat until a stop condition fires.
You control the loop declaratively through stop conditions. The SDK ships with stepCountIs, hasToolCall, and maxCost, each of which takes a threshold. You can also pass a custom function that receives the full step history and returns a boolean. This lets you bound agent runs by cost, iteration count, or arbitrary business logic without writing the loop yourself.
Tools are defined with the tool() function and Zod schemas for input validation. The SDK validates the model’s tool call arguments against the schema before execution. If the model produces invalid arguments, you get a runtime error instead of a silent failure. Tools also run separately from model calls, meaning your function code does not live inside the model invocation loop.
Streaming is built in at the step level. Each callModel call within the agent loop streams tokens in real time. You get token-by-token output from the model without sacrificing the loop’s ability to execute tools and continue. Human-in-the-loop approval gates let you pause execution before tool dispatch, which is useful for sensitive operations.
callModel handles the full reasoning loop. You define tools and stop conditions, and the SDK dispatches tools, appends results, and decides whether to continue. This eliminates the pattern of writing while loops with manual message array management.
Every tool has a Zod schema for its inputs. The SDK validates the model’s tool call arguments against the schema at runtime. This catches malformed tool calls early, which is especially important when switching between models that produce different tool call formats.
You call any of 400+ models through a single interface. The SDK does not care whether the underlying provider is OpenAI, Anthropic, Google, or a smaller API. You can change the model string between turns, which is useful for routing cheap models for simple tasks and expensive models for complex reasoning.
Each agent step streams tokens in real time. This matters for UI applications where users expect to see output as it generates, even as the agent calls tools in the background. The streaming does not block the loop, tools execute asynchronously between model responses.
The maxCost stop condition lets you bound spend on long multi-step loops. This is a practical safeguard for production deployments where runaway agent runs can rack up API costs. stepCountIs and hasToolCall provide additional control.
The SDK includes a local DevTools web UI that captures telemetry and visualizes every agent run. You can inspect each step, tool call, and response during development without setting up external observability.
Teams building internal copilots or customer-facing chatbots can swap models without rewriting application code. If a new provider offers better performance at lower cost, you change the model string, not the tool definitions or loop logic.
Use maxCost to deploy agents that search databases, write code, or process documents without unbounded API spend. This is critical for production workloads where agent loops can run 10+ steps and accumulate significant costs.
Single-agent apps that need to stream token output back to the UI while calling tools. Examples include code generation assistants that search documentation, research assistants that query multiple sources, and data analysis agents that run calculations.
The framework is a poor fit for multi-agent coordination. There is no built-in agent-to-agent message passing, shared memory, or role assignment. Teams building swarms or multi-agent pipelines should look at CrewAI, AutoGen, or LangGraph.
1npm install @openrouter/agent
You need an OpenRouter API key. The SDK uses OpenRouter’s gateway to route to 400+ models, so you do not need separate keys for each provider.
The smallest meaningful example defines a tool and calls callModel with a stop condition:
1import { callModel, tool } from '@openrouter/agent';2import { z } from 'zod';34const 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 // Call your weather API here12 return { temperature: 72, condition: 'sunny' };13 },14});1516const response = await callModel({17 model: 'openai/gpt-4o',18 messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],19 tools: [weatherTool],20 stopConditions: { maxCost: 0.05 },21});
Documentation lives at openrouter.ai/docs/agent-sdk/overview. The GitHub repository (OpenRouterTeam/typescript-agent) contains the monorepo with the @openrouter/agent package. Community discussions happen on OpenRouter’s Discord.
OpenRouter Agent SDK vs LangChain: LangChain offers broader ecosystem support (document loaders, vector stores, retrievers) and multi-agent orchestration. OpenRouter Agent SDK is simpler and more focused: you get tools, loops, and cost controls out of the box without configuring chains, memory, or callbacks. Choose OpenRouter Agent SDK when you want a thin layer over any model and do not need LangChain’s abstraction stack. Choose LangChain when you need document pipelines, RAG, or multi-step chains beyond tool-calling loops.
OpenRouter Agent SDK vs CrewAI: CrewAI is built for multi-agent teams with defined roles, tasks, and delegation. OpenRouter Agent SDK handles single-agent loops only. If your workload requires parallel agents, hierarchical task decomposition, or agent-to-agent communication, CrewAI is the better fit. If you need a single, reliable tool-calling agent with cost controls and model flexibility, OpenRouter Agent SDK requires less configuration and eliminates the overhead of role definitions.
The primary limitation is the TypeScript-only SDK and reliance on the OpenRouter gateway. Teams with Python-heavy stacks should wait for the Python SDK or evaluate alternatives. Teams that need bring-your-own-endpoint flexibility will find the gateway requirement restrictive. For TypeScript teams building single-agent applications with multi-provider flexibility, the SDK delivers a clean, type-safe developer experience with minimal abstraction overhead.
callModel runs the reasoning loop automatically, executing tools and looping until a stop condition is met.
Define tools with the tool() helper and Zod schemas, then bound runs with stepCountIs, hasToolCall, maxCost, or custom logic.
Reach 400+ models from every major provider through a single interface, with streaming token output within each step.
