Mastra Agent Builder 模型策略Model Policy完整指南allowlist 配置、默认模型与端到端验证【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文围绕 Mastra 开源仓库中 Agent Builder 的Model Policy模型策略机制展开系统讲解如何通过configuration.agent.models.allowed白名单约束 Agent 可用的模型、用models.default为新 Agent 预选默认模型并确保 Studio 与 Agent Builder 的下拉框严格遵循该策略。读完本文你将掌握模型策略的两种数据形态Builder 配置 vs 存储 Agent API、在member角色下用 curl 完成创建放行/拦截的完整冒烟验证流程以及如何从源码层面理解策略的执行链路。文中所有示例与验证步骤均来自仓库内的 model-policy.md 冒烟测试参考文档及其对应的服务端实现。一、模型策略的核心概念allowed白名单与default默认模型Agent Builder 的模型策略由两段配置共同定义configuration.agent.models.allowed约束哪些模型可以被使用它是一个数组数组元素支持两种匹配形态详见下一节models.default作为新 Agent 创建时的默认选中模型仅在allowed允许的范围内生效。Studio/agents与 Agent Builder/agent-builder/agents/:id的模型下拉框必须尊重这份白名单白名单之外的模型不会出现在下拉框中即便通过 API 强行提交也会在创建时被服务端拦截。从源码结构看这份策略对应的服务端 schema 定义在 editor-builder.tsexport const agentModelsSchema z.object({ allowed: z.array(providerModelEntrySchema).optional(), default: defaultModelEntrySchema.optional(), });策略属于Admin-controlled管理员控制配置嵌入在configuration.agent之下agentConfigurationSchema还预留了tools/agents/workflows等同形态的 picker allowlist 字段editor-builder.ts。二、两种形态同一概念modelId与name模型策略在系统中以两种数据形态出现这是最容易踩坑的地方场景字段名示例Builder 配置TS 源码如脚手架的src/mastra/index.ts{ provider, modelId }{ provider: anthropic, modelId: claude-opus-4-7 }存储 Agent APIPOST /stored/agents{ provider, name }{ provider: openai, name: gpt-4o-mini }当你调用 API创建 Agent时模型字段必须使用name当你从 settings 端点读取策略、或阅读 TypeScript 源码时看到的是modelId。两条规则适用同一个策略校验逻辑。服务端对 API 形态的约束定义在 stored-agents.ts/** Base model config schema (reused across snapshot and response schemas) */ const modelConfigSchema z .object({ provider: z.string().describe(Model provider (e.g., openai, anthropic)), name: z.string().describe(Model name (e.g., gpt-4o, claude-3-opus)), }) .passthrough();值得注意的细节在POST /stored/agents的创建体 schema 中model字段是可选的stored-agents.ts。当请求体省略model时Builder 会在服务端自动套用/editor/builder/settings中的defaults.model作为默认模型——这与下文第六节创建表单默认预选默认模型的 UI 行为互为表里。白名单条目的两种匹配形态allowed数组的每个条目支持两种匹配方式对应 editor-builder.ts 中的providerModelEntrySchemaconst knownProviderEntrySchema z .object({ provider: z.string().min(1), modelId: z.string().min(1).optional(), }) .strict(); const customProviderEntrySchema z .object({ kind: z.literal(custom), provider: z.string().min(1), modelId: z.string().min(1).optional(), }) .strict();通配符形态只写{ provider }不写modelId表示该 provider 下的任意模型都被允许如{ provider: openai }精确形态{ provider, modelId }同时给出表示仅允许这一个模型如{ provider: anthropic, modelId: claude-opus-4-7 }。所有条目 schema 都是.strict()的这意味着一旦出现modelID、Provider之类的字段名拼写错误会在配置校验阶段直接被拒绝而不会静默放宽策略editor-builder.ts 的注释明确说明了这一设计意图。此外schema 层不会把provider与运行时注册表做强校验未知的 provider 字符串会在配置校验阶段以警告warning形式浮现对应builderModelPolicySchema中的modelPolicyWarnings字段editor-builder.ts。三、策略的单一事实来源Source of Truth在脚手架生成的 Mastra 项目中策略的事实来源位于src/mastra/index.ts。以下是一份带注释的完整配置示例models: { allowed: [ { provider: openai }, // wildcard: any openai model { provider: anthropic, modelId: claude-opus-4-7 }, // exact: only this anthropic model ], default: { provider: openai, modelId: gpt-5.4 }, }这份配置通过GET /editor/builder/settings端点对外暴露。服务端会把它解析成结构化的modelPolicyactive/pickerVisible/allowed/default返回给前端UI 层直接消费这份服务端推导好的策略而不是自行从features/configuration再推导一遍——builderModelPolicySchema的注释明确指出这是Server-owned shapeeditor-builder.ts。角色与权限前置条件冒烟验证前需要先明确权限边界脚手架默认授予member角色对 stored agents 的写权限因此创建时的策略校验下述步骤 2–4在--role member下即可触达viewer角色会在策略校验执行之前就收到 403——对 viewer 而言只有步骤 1读取侧验证有意义UI 下拉框的门控见 ui.md是 viewer 场景下验证模型策略的替代路径admin与member角色可完整执行步骤 2–4脚手架已授予 member 该权限。四、端到端冒烟验证六步完整流程以下验证流程假设环境变量$BASE已指向服务端点脚手架已按前序步骤启动并完成登录。步骤 2–4 依赖stored-agents:write权限。步骤 1Settings 端点暴露策略curl -s $BASE/editor/builder/settings | jq .configuration.agent.models验证点allowed是一个数组包含上述两个条目通配符 openai 精确 anthropicdefault等于{ provider: openai, modelId: gpt-5.4 }。步骤 2用通配符放行的模型创建 Agentcurl -s -X POST $BASE/stored/agents \ -H Content-Type: application/json \ -d { name: Policy OK Agent, instructions: test, model: { provider: openai, name: gpt-4o-mini } } | jq .验证点返回200响应中model.name为gpt-4o-mini通过 openai 通配符放行。这里gpt-4o-mini并未出现在allowed的具体条目里但因为{ provider: openai }是通配符形态因此该 provider 下的任意模型都允许。步骤 3用精确放行的模型创建 Agentcurl -s -X POST $BASE/stored/agents \ -H Content-Type: application/json \ -d { name: Policy Exact Agent, instructions: test, model: { provider: anthropic, name: claude-opus-4-7 } } | jq .验证点返回200模型被接受。步骤 4用未放行的模型创建 Agent应被拦截curl -s -o /tmp/policy-err.json -w %{http_code}\n \ -X POST $BASE/stored/agents \ -H Content-Type: application/json \ -d { name: Policy Reject Agent, instructions: test, model: { provider: anthropic, name: claude-haiku-3 } } cat /tmp/policy-err.json | jq .验证点返回422语义校验错误错误信息清晰指出模型不在允许列表model not in allowed list没有创建任何 Agent列表数量保持不变。注意claude-haiku-3与放行的claude-opus-4-7同属 anthropic provider却因精确条目只放行claude-opus-4-7而被拒绝——这正验证了精确形态只允许指定模型的语义。步骤 5浏览器下拉框遵循策略在 Studio/agents与 Agent Builder/agent-builder/agents/:id的模型下拉框中所有 OpenAI 模型都应出现通配符展开Anthropic 下只出现claude-opus-4-7不再出现其他 Anthropic 模型不出现其他 providerGoogle、Mistral 等。从实现上看服务端有专门的GET /editor/builder/models/available端点它会对每个 provider 的模型列表用isModelAllowed做过滤没有任何放行模型的 provider 会被整体省略从而让 Studio 模型选择器可以直接原样渲染响应editor-builder.ts。服务端处理逻辑位于 editor-builder.ts策略本身通过动态导入mastra/core/agent-builder/ee的isModelAllowed执行。步骤 6默认模型在创建时被预选在 Agent 创建表单中模型下拉框默认选中openai / gpt-5.4用户可以切换到任何其他被允许的模型。与之呼应的是服务端行为当POST /stored/agents请求体省略model字段时服务端会自动应用/editor/builder/settings中的 builder 默认模型stored-agents.ts确保 UI 预选与服务端回退逻辑一致。五、收尾清理与验收清单验证结束后删除上述步骤中创建的任何 Agent# remove any agents created above最终的完整验收清单如下Settings 端点暴露alloweddefault通配符 provider 允许该 provider 下任意模型精确(provider, modelId)策略条目在创建时仅放行指定模型未放行的模型在创建时被拒绝UI 下拉框与 allowlist 完全一致创建 Agent 时默认模型被预选。六、从源码理解策略的完整执行链路把以上步骤串起来模型策略在 Mastra 服务端的执行链路可以概括为配置入口脚手架项目的src/mastra/index.ts定义models.allowed与models.defaultschema 校验agentModelsSchemaeditor-builder.ts用.strict()的 entry schema 拒绝拼写错误builder 构造期还会产生非致命警告modelPolicyWarnings设置暴露GET /editor/builder/settings返回结构化modelPolicy含active、pickerVisible、allowed、default前端不再自行推导创建时拦截POST /stored/agents的服务端校验将 API 形态的{ provider, name }与策略比对未放行则返回422语义错误UI 门控GET /editor/builder/models/available用isModelAllowed预过滤模型列表无放行模型的 provider 直接省略下拉框天然遵循白名单。正是API 创建时服务端强校验 UI 下拉框服务端预过滤的双保险保证了无论请求来自 curl 还是浏览器模型策略都不会被绕过。如果需要对 picker 之外的 allowlisttools/agents/workflows做类似验证可以参考同一冒烟测试体系下的 agents.md 与 picker-allowlist.md它们共享相同的角色模型与服务端 schema。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra Agent Builder 模型策略（Model Policy）完整指南：allowlist 配置、默认模型与端到端验证
Mastra Agent Builder 模型策略Model Policy完整指南allowlist 配置、默认模型与端到端验证【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文围绕 Mastra 开源仓库中 Agent Builder 的Model Policy模型策略机制展开系统讲解如何通过configuration.agent.models.allowed白名单约束 Agent 可用的模型、用models.default为新 Agent 预选默认模型并确保 Studio 与 Agent Builder 的下拉框严格遵循该策略。读完本文你将掌握模型策略的两种数据形态Builder 配置 vs 存储 Agent API、在member角色下用 curl 完成创建放行/拦截的完整冒烟验证流程以及如何从源码层面理解策略的执行链路。文中所有示例与验证步骤均来自仓库内的 model-policy.md 冒烟测试参考文档及其对应的服务端实现。一、模型策略的核心概念allowed白名单与default默认模型Agent Builder 的模型策略由两段配置共同定义configuration.agent.models.allowed约束哪些模型可以被使用它是一个数组数组元素支持两种匹配形态详见下一节models.default作为新 Agent 创建时的默认选中模型仅在allowed允许的范围内生效。Studio/agents与 Agent Builder/agent-builder/agents/:id的模型下拉框必须尊重这份白名单白名单之外的模型不会出现在下拉框中即便通过 API 强行提交也会在创建时被服务端拦截。从源码结构看这份策略对应的服务端 schema 定义在 editor-builder.tsexport const agentModelsSchema z.object({ allowed: z.array(providerModelEntrySchema).optional(), default: defaultModelEntrySchema.optional(), });策略属于Admin-controlled管理员控制配置嵌入在configuration.agent之下agentConfigurationSchema还预留了tools/agents/workflows等同形态的 picker allowlist 字段editor-builder.ts。二、两种形态同一概念modelId与name模型策略在系统中以两种数据形态出现这是最容易踩坑的地方场景字段名示例Builder 配置TS 源码如脚手架的src/mastra/index.ts{ provider, modelId }{ provider: anthropic, modelId: claude-opus-4-7 }存储 Agent APIPOST /stored/agents{ provider, name }{ provider: openai, name: gpt-4o-mini }当你调用 API创建 Agent时模型字段必须使用name当你从 settings 端点读取策略、或阅读 TypeScript 源码时看到的是modelId。两条规则适用同一个策略校验逻辑。服务端对 API 形态的约束定义在 stored-agents.ts/** Base model config schema (reused across snapshot and response schemas) */ const modelConfigSchema z .object({ provider: z.string().describe(Model provider (e.g., openai, anthropic)), name: z.string().describe(Model name (e.g., gpt-4o, claude-3-opus)), }) .passthrough();值得注意的细节在POST /stored/agents的创建体 schema 中model字段是可选的stored-agents.ts。当请求体省略model时Builder 会在服务端自动套用/editor/builder/settings中的defaults.model作为默认模型——这与下文第六节创建表单默认预选默认模型的 UI 行为互为表里。白名单条目的两种匹配形态allowed数组的每个条目支持两种匹配方式对应 editor-builder.ts 中的providerModelEntrySchemaconst knownProviderEntrySchema z .object({ provider: z.string().min(1), modelId: z.string().min(1).optional(), }) .strict(); const customProviderEntrySchema z .object({ kind: z.literal(custom), provider: z.string().min(1), modelId: z.string().min(1).optional(), }) .strict();通配符形态只写{ provider }不写modelId表示该 provider 下的任意模型都被允许如{ provider: openai }精确形态{ provider, modelId }同时给出表示仅允许这一个模型如{ provider: anthropic, modelId: claude-opus-4-7 }。所有条目 schema 都是.strict()的这意味着一旦出现modelID、Provider之类的字段名拼写错误会在配置校验阶段直接被拒绝而不会静默放宽策略editor-builder.ts 的注释明确说明了这一设计意图。此外schema 层不会把provider与运行时注册表做强校验未知的 provider 字符串会在配置校验阶段以警告warning形式浮现对应builderModelPolicySchema中的modelPolicyWarnings字段editor-builder.ts。三、策略的单一事实来源Source of Truth在脚手架生成的 Mastra 项目中策略的事实来源位于src/mastra/index.ts。以下是一份带注释的完整配置示例models: { allowed: [ { provider: openai }, // wildcard: any openai model { provider: anthropic, modelId: claude-opus-4-7 }, // exact: only this anthropic model ], default: { provider: openai, modelId: gpt-5.4 }, }这份配置通过GET /editor/builder/settings端点对外暴露。服务端会把它解析成结构化的modelPolicyactive/pickerVisible/allowed/default返回给前端UI 层直接消费这份服务端推导好的策略而不是自行从features/configuration再推导一遍——builderModelPolicySchema的注释明确指出这是Server-owned shapeeditor-builder.ts。角色与权限前置条件冒烟验证前需要先明确权限边界脚手架默认授予member角色对 stored agents 的写权限因此创建时的策略校验下述步骤 2–4在--role member下即可触达viewer角色会在策略校验执行之前就收到 403——对 viewer 而言只有步骤 1读取侧验证有意义UI 下拉框的门控见 ui.md是 viewer 场景下验证模型策略的替代路径admin与member角色可完整执行步骤 2–4脚手架已授予 member 该权限。四、端到端冒烟验证六步完整流程以下验证流程假设环境变量$BASE已指向服务端点脚手架已按前序步骤启动并完成登录。步骤 2–4 依赖stored-agents:write权限。步骤 1Settings 端点暴露策略curl -s $BASE/editor/builder/settings | jq .configuration.agent.models验证点allowed是一个数组包含上述两个条目通配符 openai 精确 anthropicdefault等于{ provider: openai, modelId: gpt-5.4 }。步骤 2用通配符放行的模型创建 Agentcurl -s -X POST $BASE/stored/agents \ -H Content-Type: application/json \ -d { name: Policy OK Agent, instructions: test, model: { provider: openai, name: gpt-4o-mini } } | jq .验证点返回200响应中model.name为gpt-4o-mini通过 openai 通配符放行。这里gpt-4o-mini并未出现在allowed的具体条目里但因为{ provider: openai }是通配符形态因此该 provider 下的任意模型都允许。步骤 3用精确放行的模型创建 Agentcurl -s -X POST $BASE/stored/agents \ -H Content-Type: application/json \ -d { name: Policy Exact Agent, instructions: test, model: { provider: anthropic, name: claude-opus-4-7 } } | jq .验证点返回200模型被接受。步骤 4用未放行的模型创建 Agent应被拦截curl -s -o /tmp/policy-err.json -w %{http_code}\n \ -X POST $BASE/stored/agents \ -H Content-Type: application/json \ -d { name: Policy Reject Agent, instructions: test, model: { provider: anthropic, name: claude-haiku-3 } } cat /tmp/policy-err.json | jq .验证点返回422语义校验错误错误信息清晰指出模型不在允许列表model not in allowed list没有创建任何 Agent列表数量保持不变。注意claude-haiku-3与放行的claude-opus-4-7同属 anthropic provider却因精确条目只放行claude-opus-4-7而被拒绝——这正验证了精确形态只允许指定模型的语义。步骤 5浏览器下拉框遵循策略在 Studio/agents与 Agent Builder/agent-builder/agents/:id的模型下拉框中所有 OpenAI 模型都应出现通配符展开Anthropic 下只出现claude-opus-4-7不再出现其他 Anthropic 模型不出现其他 providerGoogle、Mistral 等。从实现上看服务端有专门的GET /editor/builder/models/available端点它会对每个 provider 的模型列表用isModelAllowed做过滤没有任何放行模型的 provider 会被整体省略从而让 Studio 模型选择器可以直接原样渲染响应editor-builder.ts。服务端处理逻辑位于 editor-builder.ts策略本身通过动态导入mastra/core/agent-builder/ee的isModelAllowed执行。步骤 6默认模型在创建时被预选在 Agent 创建表单中模型下拉框默认选中openai / gpt-5.4用户可以切换到任何其他被允许的模型。与之呼应的是服务端行为当POST /stored/agents请求体省略model字段时服务端会自动应用/editor/builder/settings中的 builder 默认模型stored-agents.ts确保 UI 预选与服务端回退逻辑一致。五、收尾清理与验收清单验证结束后删除上述步骤中创建的任何 Agent# remove any agents created above最终的完整验收清单如下Settings 端点暴露alloweddefault通配符 provider 允许该 provider 下任意模型精确(provider, modelId)策略条目在创建时仅放行指定模型未放行的模型在创建时被拒绝UI 下拉框与 allowlist 完全一致创建 Agent 时默认模型被预选。六、从源码理解策略的完整执行链路把以上步骤串起来模型策略在 Mastra 服务端的执行链路可以概括为配置入口脚手架项目的src/mastra/index.ts定义models.allowed与models.defaultschema 校验agentModelsSchemaeditor-builder.ts用.strict()的 entry schema 拒绝拼写错误builder 构造期还会产生非致命警告modelPolicyWarnings设置暴露GET /editor/builder/settings返回结构化modelPolicy含active、pickerVisible、allowed、default前端不再自行推导创建时拦截POST /stored/agents的服务端校验将 API 形态的{ provider, name }与策略比对未放行则返回422语义错误UI 门控GET /editor/builder/models/available用isModelAllowed预过滤模型列表无放行模型的 provider 直接省略下拉框天然遵循白名单。正是API 创建时服务端强校验 UI 下拉框服务端预过滤的双保险保证了无论请求来自 curl 还是浏览器模型策略都不会被绕过。如果需要对 picker 之外的 allowlisttools/agents/workflows做类似验证可以参考同一冒烟测试体系下的 agents.md 与 picker-allowlist.md它们共享相同的角色模型与服务端 schema。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考