Mastra 是 TypeScript AI Agent 框架，通过 @openrouter/ai-sdk-provider 包集成 OpenRouter。核心流程：npx create-mastra@latest 初始化项目 → 替换为 OPENROUTER_API_KEY → 安装 @openrouter/ai-sdk-provider → 用 createOpenRouter() 初始化 Provider 并传入模型 ID 创建 Agent。运行后自动提供 REST API（/api/agents/{name}/generate）和交互式 Playground（localhost:4111），支持 extraBody 传入推理参数和多模型并发配置。

Mastra 是用于构建 TypeScript AI Agent 的框架，通过 @openrouter/ai-sdk-provider 包可以接入 OpenRouter 访问 300+ 模型。

第一步：初始化 Mastra 项目

npx create-mastra@latest

向导中选择：

• 项目名称：如 my-mastra-openrouter-app
• Components：选 Agents
• 默认 Provider：选 OpenAI（后续手动替换为 OpenRouter）

详细安装说明参见 Mastra 官方文档。

第二步：配置环境变量

打开 .env.development，移除或注释 OPENAI_API_KEY，添加：

OPENROUTER_API_KEY=sk-or-...

替换依赖包：

npm uninstall @ai-sdk/openai
npm install @openrouter/ai-sdk-provider

第三步：配置 Agent 使用 OpenRouter

修改 src/mastra/agents/agent.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({
  model: openrouter('anthropic/claude-3-opus'),
  name: 'Assistant',
  instructions: 'You are a helpful assistant with expertise in technology and science.',
});

更新 src/mastra/index.ts：

import { Mastra } from '@mastra/core';
import { assistant } from './agents/agent';

export const mastra = new Mastra({
  agents: { assistant },
});

第四步：启动应用

npm run dev

启动后可访问：

• REST API：http://localhost:4111/api/agents/assistant/generate
• 交互式 Playground：http://localhost:4111

测试 API：

curl -X POST http://localhost:4111/api/agents/assistant/generate \
  -H "Content-Type: application/json" \
  -d '{"messages": ["What are the latest advancements in quantum computing?"]}'

高级配置

传入推理参数

通过 extraBody 传入 OpenRouter 专有参数：

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

const chefAgent = new Agent({
  model: openrouter('anthropic/claude-3.7-sonnet', {
    extraBody: {
      reasoning: { max_tokens: 10 },
    },
  }),
  name: 'Chef',
  instructions: 'You are a chef assistant specializing in French cuisine.',
});

使用多个模型

同一个 openrouter 实例可以创建使用不同模型的多个 Agent：

const claudeAgent = new Agent({
  model: openrouter('anthropic/claude-3-opus'),
  name: 'ClaudeAssistant',
  instructions: 'You are a helpful assistant powered by Claude.',
});

const gptAgent = new Agent({
  model: openrouter('openai/gpt-4'),
  name: 'GPTAssistant',
  instructions: 'You are a helpful assistant powered by GPT-4.',
});

Provider 专属选项

在请求中传入 Provider 特定配置（如 Anthropic 的 Prompt Caching）：

const response = await chefAgent.generate([
  {
    role: 'system',
    content: 'You are Chef Michel...',
    providerOptions: {
      anthropic: {
        cacheControl: { type: 'ephemeral' },
      },
    },
  },
  { role: 'user', content: 'Can you suggest a keto breakfast?' },
]);

更多文档

• Mastra 文档
• AI SDK 文档
• OpenRouter 模型列表

常见问题

Q: @openrouter/ai-sdk-provider 和 @ai-sdk/openai + base URL 有什么区别？

A: @openrouter/ai-sdk-provider 是 OpenRouter 官方维护的 AI SDK Provider，封装了 OpenRouter 专有参数（如 provider routing、extraBody），并随 OpenRouter API 更新维护。@ai-sdk/openai + base URL 也能工作，但需要手动处理 OpenRouter 专有功能。

Q: Mastra Playground 有什么用？

A: Playground 是 Mastra 内置的 Agent 调试界面，可以直接在浏览器里和 Agent 对话，查看每轮请求的 token 消耗、工具调用记录等，无需额外工具。

Q: 如何在 Mastra 中同时使用 OpenRouter 的备用模型功能？

A: 通过 extraBody 传入 models 数组和 route: "fallback" 参数，与直接调用 OpenRouter API 时的语法一致：

const openrouter = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  extraBody: {
    models: ["anthropic/claude-3-opus", "openai/gpt-4"],
    route: "fallback",
  },
});