用一个模型 url 和一把 Key 把 Mastra Agent 接到 Router One

安装 Mastra 并设置凭证

Mastra v1 要求 Node.js 22.13.0 或更新版本；官方文档还说明 Node.js 22.18.0 及以上可以直接运行 TypeScript 文件，本指南就是这样运行 agent.ts 的。新项目可以用 create-mastra：默认会生成一个按你所选模型 provider（OpenAI、Anthropic、Gemini 或 xAI）配置好的 starter，加 --empty 则生成不含 Agent、不绑定 provider 的空脚手架，更适合这里的用法。在已有项目里加 Mastra，则先确认 package.json 里有 "type": "module"，再安装 Mastra 快速上手文档列出的包，见下方命令。本指南的对象写法不需要安装任何 AI SDK provider 包：@mastra/core 已经内置了它据此对象构造的 OpenAI 兼容 provider。下面是 macOS/Linux 的 shell 示例，把占位符换成为这个 Agent 单独创建的 Router One Key。ROUTER_ONE_API_KEY 是本示例自己定义并显式读取的变量名。模型设置了 url 时，Mastra 不会去读任何环境变量，所以 Key 必须通过 apiKey 传入，也不需要设置 OPENAI_API_KEY。

# New project instead: npx create-mastra@latest my-app --empty
npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest
export ROUTER_ONE_API_KEY="sk-your-router-one-key"

把 Mastra 配置到 Router One base URL

保存为 agent.ts，再运行 node agent.ts。model 字段填的是一个对象，而不是 provider/model 字符串。id 会在第一个斜杠处拆开：第一段（这里的 custom，是 Mastra 文档给自定义端点用的标签）成为 Mastra 日志和 span 里的 provider 名，斜杠之后的全部内容作为请求的 model 字段发出，所以 custom/anthropic/claude-sonnet-5 发出的是 anthropic/claude-sonnet-5，custom/grok-4.6 发出的是 grok-4.6。把占位符换成 /models 里的精确 ID，并保留前面的 custom/。url 填带 /v1 的 base URL，不是聊天端点：内置的 OpenAI 兼容 provider 会自行拼接 /chat/completions，所以每次模型调用都是一个 POST /v1/chat/completions。apiKey 会成为 Authorization: Bearer 请求头。工具用 createTool 定义（id、description、zod 的 inputSchema、execute），并以 addTool 这个键注册；这个键就是模型在请求的 tools 字段里看到的函数名，同时带 tool_choice auto。generate() 在整个循环结束后返回：这个提示词的第一次请求会返回一个工具调用，Mastra 在你的进程里运行 execute，第二次请求返回答案，所以 result.steps 有两项，result.usage 是 API 为这两次请求报告的 token 之和。maxSteps: 3 把循环限制在三次模型调用以内；不设时默认是 5。stream() 发送同样的请求并带 stream: true，文本通过 textStream 边到边输出。在 Mastra 项目里，把 Agent 放在 src/mastra/agents 下，并在 src/mastra/index.ts 里用 new Mastra({ agents: { routerOneAgent } }) 注册；模型对象完全一样。

import { Agent } from "@mastra/core/agent";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

const addTool = createTool({
  id: "add",
  description: "Add two numbers",
  inputSchema: z.object({ a: z.number(), b: z.number() }),
  execute: async ({ a, b }) => ({ sum: a + b }),
});

export const routerOneAgent = new Agent({
  id: "router-one-agent",
  name: "Router One Agent",
  instructions: "You are a concise assistant. Use the add tool for arithmetic.",
  model: {
    // Mastra strips the "custom/" label and sends the rest as the model, e.g. custom/anthropic/claude-sonnet-5
    id: "custom/<exact-model-id-from-/models>",
    url: "https://api.router.one/v1",
    apiKey: process.env.ROUTER_ONE_API_KEY,
  },
  tools: { addTool },
});

// 1. generate(): one POST /v1/chat/completions per step; maxSteps caps the loop (default 5)
const result = await routerOneAgent.generate("What is 2 + 3?", { maxSteps: 3 });
console.log(result.text, result.steps.length, result.usage);

// 2. stream(): the same request with stream: true
const stream = await routerOneAgent.stream("Say hello in five words.");
for await (const chunk of stream.textStream) process.stdout.write(chunk);

Mastra 的哪个设置发出哪种请求

连接信息由模型对象携带，一次调用发出多少请求、每个请求要什么则由 Agent 的选项决定。下表按本指南涉及的设置，给出该填的值、它产生的请求，以及使用前要确认的内容。

给一个 Agent 定预算，并逐次核对请求

一次 generate() 或 stream() 调用是一个循环：每一步是一个 POST /v1/chat/completions，返回工具调用的那一步之后，Mastra 运行工具并再发下一步；模型不再调用工具而直接回答，或到达 maxSteps（默认 5）时，循环结束。每个请求都会重新发送指令、对话以及此前所有的工具调用和结果，所以输入 token 会逐步增长：maxSteps 限制的是请求数，不是花费。重试只有在你要求时才会增加请求：当前 API 里 Agent 的 maxRetries 选项默认是 0，失败的调用不会重发；设为 maxRetries: 2 时，持续的 5xx 会让这一步变成三次请求。可重试的情况是 408、409、429、5xx 或非 HTTP 响应类错误；401、402 和 404 从不重试。旧的 generateLegacy() 路径保留自己的 maxRetries，默认值是 2。带回退项的 model 数组会再乘一层，因为每一项有自己的重试次数；网关在 5xx 和超时时的同系列回退发生在响应到达 Mastra 之前，所以客户端的回退列表只会在网关自己返回错误时增加请求。一些可选功能会发出自己的模型请求：给 structuredOutput 单独指定 model 时每个回答是两次调用，generateTitle 会在 Agent 的模型上多一次调用（除非另外给它指定模型），Observational Memory 会在后台运行 Observer 和 Reflector 两个 Agent。每一次到达网关的尝试在 Dashboard → Logs 里都是独立一行，有各自的 request_id、费用和状态。给每个 Agent 单独一把设了 maxSpend 的 Key：失控的循环会在你设的上限处收到 HTTP 402，表现为 statusCode 为 402 的 AI_APICallError，钱包和其他 Key 不受影响。result.usage、result.steps 里每一步的 usage，以及 Mastra tracing 里的 token 和成本数字，是 Mastra 对 API 报告用量的统计和估算；费用以 Logs 记录为准。按 Key、时间、模型和 token 数对账，报障时保留 request_id。Router One 只记录模型调用元数据，不运行 Agent 循环、你的工具、工作流、记忆或存储。

记忆、semantic recall 和 embedder 都留在你这一侧

记忆是 Mastra 的功能，由你自己的存储支撑：安装 @mastra/memory 和一个存储适配器（例如 @mastra/libsql），并在每次调用时传入 resource 和 thread。之后消息历史默认会把最近 10 条消息（lastMessages）带进每个请求，这会增加每一步的输入 token，但不会多发请求。semantic recall 默认关闭，开启还需要另外两样东西：向量库和 embedder；每一轮对话都会调用 embedder，先为检索给新提示词生成向量，之后再为索引给新消息生成向量。Router One 不提供 /v1/embeddings，所以不要把 embedder 指向网关：让它留在提供 embeddings 的 provider 上，例如 ModelRouterEmbeddingModel('openai/text-embedding-3-small') 配该 provider 自己的 Key，或者用 @mastra/fastembed 里的 fastembed 在本地运行。这些调用不会出现在 Dashboard → Logs 里。Observational Memory 则不同：它的 Observer 和 Reflector 是聊天模型调用，不指定模型时默认使用一个 Google 模型，经 Mastra 的模型路由、用你环境里的 Google API Key 解析，不经过网关。它的 model 选项接受的类型与 Agent 的 model 相同，所以传入同一个带 id、url 和 apiKey 的对象，这些后台调用就会走你的 Router One Key 并出现在 Logs 里。generateTitle 同样可以指定 model，不指定时使用 Agent 自己的模型。线程、向量和 working memory 都保存在你配置的存储里，网关只看到每次模型请求里的消息。

Mastra 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Mastra 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

Mastra 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 Mastra 的调用

先在 Mastra 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题