在 Mastra 中为文件化子代理编写指令以weather-fs/forecaster/instructions.md为例【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读在 Mastra 的文件化file-basedAgent体系中instructions.md是定义 Agent 行为灵魂的纯文本文件它决定模型何时调用工具、如何汇报结果、何时把任务委派给子代理。本文以 examples/agent/src/mastra/agents/weather-fs 示例中forecaster子代理的 instructions.md 为骨架完整还原该指令文本并结合其配套的config.ts、get_forecast工具、嵌套子代理historian以及mastra/core的文件路由源码讲透“如何给一个子代理写出高可用指令、它如何被父代理发现与委派、最深可以嵌套几层”。读完你将能照葫芦画瓢在自己的 Mastra 项目中用纯文件方式组织出多层协作的 Agent 团队。一、关联文档原文forecaster/instructions.md的完整内容该子代理的指令文件全文如下原样保留You are a forecasting specialist. When asked for a forecast, call the get_forecast tool for the named city and summarize the result day by day in a short list. Call out any precipitation. If no city is named, ask which city.虽然只有四行但它是一份结构完整、可运行的子代理指令包含了三条关键的行为约束指令内容行为含义You are a forecasting specialist.角色设定System Prompt 的身份让模型以“预报专家”的身份回答call the get_forecast tool for the named city and summarize the result day by day in a short list. Call out any precipitation.明确工具调用触发条件用户要预报 → 调get_forecast、输出格式逐日短列表与输出重点突出降水If no city is named, ask which city.兜底交互策略参数缺失时主动追问而不是臆造城市在 Mastra 的文件化约定中这份文件不需要任何export目录结构本身即声明subagents/forecaster/instructions.md就是forecaster子代理的instructions。正如 forecaster/config.ts 中的注释所说// instructions omitted - taken from instructions.md——即 config 中省略instructions字段时框架自动从同名目录下的instructions.md读取。二、instructions.md 在文件化 Agent 布局中的位置forecaster并不是孤立存在的它是文件化示例weather-fs的一级子代理。完整目录布局如下来自 weather-fs/README.mdweather-fs/ config.ts # model config overrides (uses agentConfig() for typing) instructions.md # the agent instructions memory.ts # default-exported Memory instance tools/ get_weather.ts # default-exported tool, keyed by filename skills/ units.md # flat skill severe-weather/ SKILL.md # packaged skill references/ thresholds.md workspace/ # seed files mirrored into the agents workspace cities.json README.md subagents/ forecaster/ # a declared subagent, same layout as an agent config.ts # MUST set a description instructions.md tools/ get_forecast.ts subagents/ historian/ # a nested subagent (depth 2) config.ts instructions.md tools/ get_climate_normals.ts从布局可以看出子代理与顶层 Agent 的关系子代理的布局与顶层 Agent 完全一致——config.ts、instructions.md、tools/*可选skills/、workspace/、以及自己的subagents/父代理通过“委托工具”调用子代理——forecaster目录会被组装成一个独立的Agent以目录名forecaster为键挂到父代理的agents映射中成为模型可见的委派工具子代理可以继续嵌套——forecaster又声明了自己的子代理historian形成weather-fs → forecaster → historian的委派链。三、父代理如何把任务“交给” forecaster指令与 description 的分工3.1 父代理指令中的委派触发条件顶层weather-fs的 instructions.md 明确写有委派策略When the user asks for a multi-day forecast (or this week, next few days), delegate to the forecaster subagent instead of answering directly.也就是说委派行为本身也是一条指令父模型根据用户请求判断“是否多日预报”命中则调用名为forecaster的工具。这正是示例设计的分层意图——单日天气由get_weather直接回答多日预报下沉给预报专家。3.2 description父模型决策委派的唯一依据与顶层 Agent 不同子代理的config.ts必须提供非空的description。forecaster的配置如下config.tsimport { agentConfig } from mastra/core/agent; export default agentConfig({ model: openai/gpt-5.4-mini, description: Produces a multi-day weather forecast for a city., // instructions omitted - taken from instructions.md // tools omitted - taken from tools/*.ts });这条description是父模型在选择是否委派时唯一能看到的描述性文本子代理内部的instructions.md不会暴露给父模型。在 packages/core/src/agent/fs-routing/index.ts 的源码中这条规则被强制校验L587-L667const description child.getDescription(); if (!description || description.trim() ) { throw new MastraError({ id: AGENT_FS_ROUTING_SUBAGENT_DESCRIPTION_REQUIRED, ... text: Agent ${name}: subagent ${childId} requires a non-empty description. Set one in agents/${name}/subagents/${childId}/config.ts., }); }所以实践上description要写成“一句话能说清这个子代理擅长什么”的摘要例如Produces a multi-day weather forecast for a city.而instructions.md则写“拿到任务后具体怎么干”的完整规程。两者一个对外父模型选人、一个对内子代理执行。四、指令引用的工具get_forecast 的契约定义forecaster/instructions.md要求调用get_forecast工具。该工具在 tools/get_forecast.ts 中用createTool定义核心是输入/输出 Schema 契约import { createTool } from mastra/core/tools; import { z } from zod; export default createTool({ id: get-forecast, description: Fetches a multi-day weather forecast for a given city, inputSchema: z.object({ city: z.string().describe(The city to forecast), days: z.number().int().min(1).max(7).default(3).describe(Number of days), }), outputSchema: z.object({ city: z.string(), days: z.array( z.object({ day: z.number(), conditions: z.string(), highCelsius: z.number(), lowCelsius: z.number(), }), ), }), execute: async ({ city, days }) { // Stubbed response — swap in a real API for production use. const conditions [sunny, partly cloudy, rain, clear]; return { city, days: Array.from({ length: days }, (_, i) ({ day: i 1, conditions: conditions[i % conditions.length]!, highCelsius: 22 - i, lowCelsius: 14 - i, })), }; }, });几个与指令编写直接相关的细节输入 Schema 的约束即指令的“可执行范围”days限定为1..7的整数、默认3这意味着指令中不必再写“预报几天”模型只要传city即可缺失参数由框架默认值兜底输出 Schema 定义了“day by day”的数据形状数组中的每一项含day、conditions、highCelsius、lowCelsius指令中要求“summarize the result day by day in a short list”正好与这个结构对应execute目前是桩实现代码注释明确写着Stubbed response — swap in a real API for production use.实际生产环境替换为真实天气 API 即可Schema 与指令无需改动。文件化发现机制上工具以文件名为键注册get_forecast.ts→ 工具名get_forecast与指令中call the get_forecast tool完全一致指令里的工具名必须与文件名对齐。五、嵌套子代理historian 与委派深度上限forecaster还拥有自己的子代理historian目录subagents/forecaster/subagents/historian/用于回答“某地某月通常什么天气”这类气候问题。它的 instructions.md 遵循同样的写作模式You are a climate history specialist. When asked how the weather usually is somewhere, call the get_climate_normals tool for the named city and month and report the typical high, low, and rainy days in one short sentence. If no month is named, use the current month.其配套工具 get_climate_normals.ts 接收city与month1..12输出avgHighCelsius、avgLowCelsius、rainyDays同样为桩实现用正弦函数模拟季节温差。其config.ts也遵循“description 必填”规则export default agentConfig({ model: openai/gpt-5.4-mini, description: Looks up historical climate normals (typical temperatures and rainfall) for a city and month., });关于嵌套深度fs-routing/index.ts 中定义export const MAX_FS_SUBAGENT_DEPTH 3;即顶层 Agent 记为 depth 0其子代理为 depth 1依此类推声明超过 3 层的子代理会被忽略并发出警告ignoring its subagents — subagents may only nest 3 levels below a top-level agent。该上限一方面防止委派树无限膨胀另一方面可保护assembleAgentFromFsEntry免受循环目录对象的影响。weather-fs → forecaster → historian这条链正好处于 depth 2是“合理嵌套”的典型示范。六、组合起来完整委派链路与运行验证将上面所有文件组合就得到一条完整的分层 Agent 链路用户请求示例处理链路依据“whats the weather in Tokyo?”weather-fs直接调get_weather同时报 °C 与 °F顶层指令 skills/units.md 技能“give me a 5-day forecast for London”weather-fs委派给forecaster后者调get_forecast逐日汇报顶层指令的委派条款 forecaster/instructions.md“how is the weather in Paris usually in April?”forecaster再委派给historian后者调get_climate_normalshistorian/instructions.md在仓库根目录运行即可在 Studio 中看到weather-fs与代码定义的 Agent 并列出现pnpm --filter ./examples/agent mastra dev需要强调的是weather-fs是纯文件定义的 Agent没有new Agent()调用也没有在src/mastra/index.ts中注册任何内容mastra dev/mastra build会自动发现并注册它——这也正是instructions.md这类文件之所以重要的前提在文件化体系里目录与 Markdown 本身就是声明。七、写给子代理指令的实践要点基于本示例的提炼结合forecaster与historian两份指令及其源码佐证可以总结出编写高质量子代理指令的四条经验先定角色再给行为以You are a ... specialist.开头明确专业身份随后用“When asked for X, do Y”的条件句式把触发场景与动作绑定减少模型误判工具名必须与文件名严格一致指令中写的get_forecast要能在 tools/get_forecast.ts 中找到对应文件否则模型无法调用把“怎么答”写进指令包括输出格式逐日短列表、重点强调Call out any precipitation和缺失参数时的兜底ask which city这些细节决定回答质量对外靠 description、对内靠 instructions在 config.ts 中用一句话描述子代理职责供父模型决策缺失即构建报错把完整执行规程放进instructions.md两者职责分离。结语forecaster/instructions.md虽只有四行却是 Mastra 文件化子代理机制的浓缩样本它展示了指令与工具契约get_forecast的 Zod Schema、指令与 description 的分工、以及子代理间的多层委派受MAX_FS_SUBAGENT_DEPTH 3约束。以它为模板你可以在agents/name/subagents/下用纯 Markdown 与目录结构快速搭建分工明确的 Agent 团队——这也是 Mastra 文件化开发范式最直观的入门路径。更多背景可参考 weather-fs 的 README。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Mastra 中为文件化子代理编写指令以weather-fs/forecaster/instructions.md为例【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读在 Mastra 的文件化file-basedAgent体系中instructions.md是定义 Agent 行为灵魂的纯文本文件它决定模型何时调用工具、如何汇报结果、何时把任务委派给子代理。本文以 examples/agent/src/mastra/agents/weather-fs 示例中forecaster子代理的 instructions.md 为骨架完整还原该指令文本并结合其配套的config.ts、get_forecast工具、嵌套子代理historian以及mastra/core的文件路由源码讲透“如何给一个子代理写出高可用指令、它如何被父代理发现与委派、最深可以嵌套几层”。读完你将能照葫芦画瓢在自己的 Mastra 项目中用纯文件方式组织出多层协作的 Agent 团队。一、关联文档原文forecaster/instructions.md的完整内容该子代理的指令文件全文如下原样保留You are a forecasting specialist. When asked for a forecast, call the get_forecast tool for the named city and summarize the result day by day in a short list. Call out any precipitation. If no city is named, ask which city.虽然只有四行但它是一份结构完整、可运行的子代理指令包含了三条关键的行为约束指令内容行为含义You are a forecasting specialist.角色设定System Prompt 的身份让模型以“预报专家”的身份回答call the get_forecast tool for the named city and summarize the result day by day in a short list. Call out any precipitation.明确工具调用触发条件用户要预报 → 调get_forecast、输出格式逐日短列表与输出重点突出降水If no city is named, ask which city.兜底交互策略参数缺失时主动追问而不是臆造城市在 Mastra 的文件化约定中这份文件不需要任何export目录结构本身即声明subagents/forecaster/instructions.md就是forecaster子代理的instructions。正如 forecaster/config.ts 中的注释所说// instructions omitted - taken from instructions.md——即 config 中省略instructions字段时框架自动从同名目录下的instructions.md读取。二、instructions.md 在文件化 Agent 布局中的位置forecaster并不是孤立存在的它是文件化示例weather-fs的一级子代理。完整目录布局如下来自 weather-fs/README.mdweather-fs/ config.ts # model config overrides (uses agentConfig() for typing) instructions.md # the agent instructions memory.ts # default-exported Memory instance tools/ get_weather.ts # default-exported tool, keyed by filename skills/ units.md # flat skill severe-weather/ SKILL.md # packaged skill references/ thresholds.md workspace/ # seed files mirrored into the agents workspace cities.json README.md subagents/ forecaster/ # a declared subagent, same layout as an agent config.ts # MUST set a description instructions.md tools/ get_forecast.ts subagents/ historian/ # a nested subagent (depth 2) config.ts instructions.md tools/ get_climate_normals.ts从布局可以看出子代理与顶层 Agent 的关系子代理的布局与顶层 Agent 完全一致——config.ts、instructions.md、tools/*可选skills/、workspace/、以及自己的subagents/父代理通过“委托工具”调用子代理——forecaster目录会被组装成一个独立的Agent以目录名forecaster为键挂到父代理的agents映射中成为模型可见的委派工具子代理可以继续嵌套——forecaster又声明了自己的子代理historian形成weather-fs → forecaster → historian的委派链。三、父代理如何把任务“交给” forecaster指令与 description 的分工3.1 父代理指令中的委派触发条件顶层weather-fs的 instructions.md 明确写有委派策略When the user asks for a multi-day forecast (or this week, next few days), delegate to the forecaster subagent instead of answering directly.也就是说委派行为本身也是一条指令父模型根据用户请求判断“是否多日预报”命中则调用名为forecaster的工具。这正是示例设计的分层意图——单日天气由get_weather直接回答多日预报下沉给预报专家。3.2 description父模型决策委派的唯一依据与顶层 Agent 不同子代理的config.ts必须提供非空的description。forecaster的配置如下config.tsimport { agentConfig } from mastra/core/agent; export default agentConfig({ model: openai/gpt-5.4-mini, description: Produces a multi-day weather forecast for a city., // instructions omitted - taken from instructions.md // tools omitted - taken from tools/*.ts });这条description是父模型在选择是否委派时唯一能看到的描述性文本子代理内部的instructions.md不会暴露给父模型。在 packages/core/src/agent/fs-routing/index.ts 的源码中这条规则被强制校验L587-L667const description child.getDescription(); if (!description || description.trim() ) { throw new MastraError({ id: AGENT_FS_ROUTING_SUBAGENT_DESCRIPTION_REQUIRED, ... text: Agent ${name}: subagent ${childId} requires a non-empty description. Set one in agents/${name}/subagents/${childId}/config.ts., }); }所以实践上description要写成“一句话能说清这个子代理擅长什么”的摘要例如Produces a multi-day weather forecast for a city.而instructions.md则写“拿到任务后具体怎么干”的完整规程。两者一个对外父模型选人、一个对内子代理执行。四、指令引用的工具get_forecast 的契约定义forecaster/instructions.md要求调用get_forecast工具。该工具在 tools/get_forecast.ts 中用createTool定义核心是输入/输出 Schema 契约import { createTool } from mastra/core/tools; import { z } from zod; export default createTool({ id: get-forecast, description: Fetches a multi-day weather forecast for a given city, inputSchema: z.object({ city: z.string().describe(The city to forecast), days: z.number().int().min(1).max(7).default(3).describe(Number of days), }), outputSchema: z.object({ city: z.string(), days: z.array( z.object({ day: z.number(), conditions: z.string(), highCelsius: z.number(), lowCelsius: z.number(), }), ), }), execute: async ({ city, days }) { // Stubbed response — swap in a real API for production use. const conditions [sunny, partly cloudy, rain, clear]; return { city, days: Array.from({ length: days }, (_, i) ({ day: i 1, conditions: conditions[i % conditions.length]!, highCelsius: 22 - i, lowCelsius: 14 - i, })), }; }, });几个与指令编写直接相关的细节输入 Schema 的约束即指令的“可执行范围”days限定为1..7的整数、默认3这意味着指令中不必再写“预报几天”模型只要传city即可缺失参数由框架默认值兜底输出 Schema 定义了“day by day”的数据形状数组中的每一项含day、conditions、highCelsius、lowCelsius指令中要求“summarize the result day by day in a short list”正好与这个结构对应execute目前是桩实现代码注释明确写着Stubbed response — swap in a real API for production use.实际生产环境替换为真实天气 API 即可Schema 与指令无需改动。文件化发现机制上工具以文件名为键注册get_forecast.ts→ 工具名get_forecast与指令中call the get_forecast tool完全一致指令里的工具名必须与文件名对齐。五、嵌套子代理historian 与委派深度上限forecaster还拥有自己的子代理historian目录subagents/forecaster/subagents/historian/用于回答“某地某月通常什么天气”这类气候问题。它的 instructions.md 遵循同样的写作模式You are a climate history specialist. When asked how the weather usually is somewhere, call the get_climate_normals tool for the named city and month and report the typical high, low, and rainy days in one short sentence. If no month is named, use the current month.其配套工具 get_climate_normals.ts 接收city与month1..12输出avgHighCelsius、avgLowCelsius、rainyDays同样为桩实现用正弦函数模拟季节温差。其config.ts也遵循“description 必填”规则export default agentConfig({ model: openai/gpt-5.4-mini, description: Looks up historical climate normals (typical temperatures and rainfall) for a city and month., });关于嵌套深度fs-routing/index.ts 中定义export const MAX_FS_SUBAGENT_DEPTH 3;即顶层 Agent 记为 depth 0其子代理为 depth 1依此类推声明超过 3 层的子代理会被忽略并发出警告ignoring its subagents — subagents may only nest 3 levels below a top-level agent。该上限一方面防止委派树无限膨胀另一方面可保护assembleAgentFromFsEntry免受循环目录对象的影响。weather-fs → forecaster → historian这条链正好处于 depth 2是“合理嵌套”的典型示范。六、组合起来完整委派链路与运行验证将上面所有文件组合就得到一条完整的分层 Agent 链路用户请求示例处理链路依据“whats the weather in Tokyo?”weather-fs直接调get_weather同时报 °C 与 °F顶层指令 skills/units.md 技能“give me a 5-day forecast for London”weather-fs委派给forecaster后者调get_forecast逐日汇报顶层指令的委派条款 forecaster/instructions.md“how is the weather in Paris usually in April?”forecaster再委派给historian后者调get_climate_normalshistorian/instructions.md在仓库根目录运行即可在 Studio 中看到weather-fs与代码定义的 Agent 并列出现pnpm --filter ./examples/agent mastra dev需要强调的是weather-fs是纯文件定义的 Agent没有new Agent()调用也没有在src/mastra/index.ts中注册任何内容mastra dev/mastra build会自动发现并注册它——这也正是instructions.md这类文件之所以重要的前提在文件化体系里目录与 Markdown 本身就是声明。七、写给子代理指令的实践要点基于本示例的提炼结合forecaster与historian两份指令及其源码佐证可以总结出编写高质量子代理指令的四条经验先定角色再给行为以You are a ... specialist.开头明确专业身份随后用“When asked for X, do Y”的条件句式把触发场景与动作绑定减少模型误判工具名必须与文件名严格一致指令中写的get_forecast要能在 tools/get_forecast.ts 中找到对应文件否则模型无法调用把“怎么答”写进指令包括输出格式逐日短列表、重点强调Call out any precipitation和缺失参数时的兜底ask which city这些细节决定回答质量对外靠 description、对内靠 instructions在 config.ts 中用一句话描述子代理职责供父模型决策缺失即构建报错把完整执行规程放进instructions.md两者职责分离。结语forecaster/instructions.md虽只有四行却是 Mastra 文件化子代理机制的浓缩样本它展示了指令与工具契约get_forecast的 Zod Schema、指令与 description 的分工、以及子代理间的多层委派受MAX_FS_SUBAGENT_DEPTH 3约束。以它为模板你可以在agents/name/subagents/下用纯 Markdown 与目录结构快速搭建分工明确的 Agent 团队——这也是 Mastra 文件化开发范式最直观的入门路径。更多背景可参考 weather-fs 的 README。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
