Using OpenRouter

Integrate OpenRouter with Mastra to leverage the numerous models available on OpenRouter.

1. The simplest way to get started with Mastra is to use the mastra CLI to initialize a new project:

   npx create-mastra@beta

   You'll be guided through prompts to set up your project. For this example, select:

   • Name your project: my-mastra-openrouter-app
   • Components: Agents (recommended)
   • For default provider, select OpenAI (recommended) - we'll configure OpenRouter manually later
   • Optionally include example code

2. After creating your project with create-mastra, you'll find a .env file in your project root. Since we selected OpenAI during setup, we'll configure OpenRouter manually:

   .env

   OPENROUTER_API_KEY=

   We remove the @ai-sdk/openai package from the project:

   npm uninstall @ai-sdk/openai

   Then, we install the @openrouter/ai-sdk-provider package:

   npm install @openrouter/ai-sdk-provider

3. We will now configure our agent to use OpenRouter.

   src/mastra/agents/assistant.ts

   import { Agent } from "@mastra/core/agent";
   import { createOpenRouter } from "@openrouter/ai-sdk-provider";
   
   const openrouter = createOpenRouter({
     apiKey: process.env.OPENROUTER_API_KEY,
   });
   
   export const assistant = new Agent({
     id: "assistant",
     name: "assistant",
     instructions: "You are a helpful assistant.",
     model: openrouter("anthropic/claude-sonnet-4"),
   });

   Make sure to register your agent to the Mastra instance:

   src/mastra/index.ts

   import { assistant } from "./agents/assistant";
   
   export const mastra = new Mastra({
     agents: { assistant },
   });

4. npm run dev

   This will start the Mastra development server.

   You can now test your agent by visiting http://localhost:4111 and using Studio or via the Mastra API at http://localhost:4111/api/agents/assistant/stream.

Advanced Configuration

For more control over your OpenRouter requests, you can pass additional configuration options.

Provider-wide options:

You can pass provider-wide options to the OpenRouter provider:

src/mastra/agents/assistant.ts

import { Agent } from "@mastra/core/agent";
import { createOpenRouter } from "@openrouter/ai-sdk-provider";

const openrouter = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  extraBody: {
    reasoning: {
      max_tokens: 10,
    },
  },
});

export const assistant = new Agent({
  id: "assistant",
  name: "assistant",
  instructions: "You are a helpful assistant.",
  model: openrouter("anthropic/claude-sonnet-4"),
});

Model-specific options:

You can pass model-specific options to the OpenRouter provider:

src/mastra/agents/assistant.ts

import { Agent } from "@mastra/core/agent";
import { createOpenRouter } from "@openrouter/ai-sdk-provider";

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

export const assistant = new Agent({
  id: "assistant",
  name: "assistant",
  instructions: "You are a helpful assistant.",
  model: openrouter("anthropic/claude-sonnet-4", {
    extraBody: {
      reasoning: {
        max_tokens: 10,
      },
    },
  }),
});

Provider-specific options:

You can pass provider-specific options to the OpenRouter provider:

// Get a response with provider-specific options
const response = await assistant.generate([
  {
    role: "system",
    content:
      "You are Chef Michel, a culinary expert specializing in ketogenic (keto) diet...",
    providerOptions: {
      // Provider-specific options - key can be 'anthropic' or 'openrouter'
      anthropic: {
        cacheControl: { type: "ephemeral" },
      },
    },
  },
  {
    role: "user",
    content: "Can you suggest a keto breakfast?",
  },
]);