Mastra 中的 System Prompt 理解与编写指南从五要素到源码级实践【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraSystem prompt系统提示词是 Mastra Agent 的行为基石它定义了 Agent 的定位、能力边界与交互方式直接决定响应的稳定性和质量。本篇基于 Mastra 官方入门课程docs/src/course/01-first-agent中关于 system prompt 的讲解展开并结合 packages/core/src/agent 的源码与测试用例帮助你掌握 system prompt 的五大构成要素、在 Mastra 中的配置方式静态与动态指令以及如何在真实 Agent 中落地一份可运行的高质量系统提示词。为什么 system prompt 至关重要在 Mastra 中Agent 是面向任务的核心原语而instructions即 system prompt是 Agent 构造参数中最具决定性的字段之一。一个清晰的 system prompt 相当于给 Agent 一份岗位说明书它帮助模型在每次交互前建立一致的上下文我是谁、我能做什么、我应该怎样做、我不能做什么、怎样才算做得好。从源码看instructions字段在 Agent 类型中被定义为AgentInstructions其具体类型在 packages/core/src/agent/types.ts 中声明为SystemMessage而SystemMessage的完整定义位于 packages/core/src/llm/index.ts支持以下形式export type SystemMessage | string | string[] | CoreSystemMessage // 如 { role: system, content: ... } | SystemModelMessage // 带 providerOptions 的系统消息 | CoreSystemMessage[] | SystemModelMessage[];这意味着你可以用最朴素的字符串编写 prompt也可以用结构化的系统消息对象甚至携带面向特定模型厂商的providerOptions例如 Anthropic 的cache_control或 OpenAI 的reasoning_effort。一份好 system prompt 的五个必备要素系统提示词并没有唯一正确的格式但一份好的 system prompt 应当覆盖以下五个维度这也是 Mastra 入门课程给出的权威骨架角色定义Role definitionAgent 是什么、负责做什么。例如你是一名财务助手帮助用户分析交易数据。核心能力Core capabilitiesAgent 能够执行的具体任务清单例如分析消费模式、回答关于特定交易或商家的问题。行为准则Behavioral guidelinesAgent 应如何回应与互动例如保持专业友好的语气、回答简洁但信息充分、需要更多信息时主动澄清。约束与边界ConstraintsAgent 不应做什么或讨论什么例如不提供投资建议、不臆测用户财务状况。成功标准Success criteria怎样的回答算是好的例如分析准确、用户满意度高、数据隐私安全。这些要素共同构成一套指令集引导 Agent 理解自身使命并规范地响应用户。实践表明越清晰、越全面的 system prompt 越能带来一致且有帮助的 Agent 响应。在 Mastra 中编写首个带 system prompt 的 Agent课程在 06-understanding-system-prompts.md 讲解要素之后紧接的 07-creating-your-agent.md 给出了完整可运行的落地示例创建一个财务交易分析助手文件位于src/mastra/agents/financial-agent.ts。import { Agent } from mastra/core/agent export const financialAgent new Agent({ name: Financial Assistant Agent, instructions: ROLE DEFINITION - You are a financial assistant that helps users analyze their transaction data. - Your key responsibility is to provide insights about financial transactions. - Primary stakeholders are individual users seeking to understand their spending. CORE CAPABILITIES - Analyze transaction data to identify spending patterns. - Answer questions about specific transactions or vendors. - Provide basic summaries of spending by category or time period. BEHAVIORAL GUIDELINES - Maintain a professional and friendly communication style. - Keep responses concise but informative. - Always clarify if you need more information to answer a question. - Format currency values appropriately. - Ensure user privacy and data security. CONSTRAINTS BOUNDARIES - Do not provide financial investment advice. - Avoid discussing topics outside of the transaction data provided. - Never make assumptions about the users financial situation beyond whats in the data. SUCCESS CRITERIA - Deliver accurate and helpful analysis of transaction data. - Achieve high user satisfaction through clear and helpful responses. - Maintain user trust by ensuring data privacy and security., model: openai/gpt-5.4, tools: {}, // 后续课程会在此挂载工具 })注意这里instructions以模板字符串传入通过五个分区标题ROLE DEFINITION、CORE CAPABILITIES、BEHAVIORAL GUIDELINES、CONSTRAINTS BOUNDARIES、SUCCESS CRITERIA组织内容——这正是前面五要素的工程化体现。tools: {}表示暂时为空后续课程10-understanding-tools.md之后的章节会逐步接入交易分析工具。创建完成后可通过课程 05-running-playground.md 中的方式启动 Mastra Studio 实测npm run devStudio 默认运行在http://localhost:4111你可以向 Agent 发送消息、查看响应与思考过程、直接测试工具并调试问题。深入源码instructions 的类型系统与三种用法除了课程中的字符串写法从源码与测试中可以确认instructions还支持更多形式测试覆盖见 packages/core/src/agent/tests/instructions.test.ts1. 字符串最常用instructions: You are a helpful assistant.2. 结构化系统消息含 providerOptionsinstructions: [ { role: system, content: You are a helpful assistant. }, { role: system, content: Always be polite., providerOptions: { anthropic: { cacheControl: { type: ephemeral } } }, }, { role: system, content: Use technical language., providerOptions: { openai: { reasoning_effort: medium } }, }, ]测试用例instructions.test.ts第 262-286 行验证了携带厂商元数据的系统消息数组可被完整保留。3. 动态函数每次运行前解析Agent#getInstructions的实现位于 packages/core/src/agent/agent.ts当instructions是函数时会在生成响应前以{ requestContext, mastra }为参数调用从而实现按请求上下文动态生成 system promptinstructions: ({ requestContext }) { const role requestContext?.get(role) || assistant; return You are a helpful ${role}.; }函数可返回字符串、CoreSystemMessage、数组甚至支持async异步解析测试分别覆盖了这些分支如第 288-384 行。这是把租户、用户偏好、运行模式等动态信息注入 system prompt 的标准做法。运行期覆盖与组合instructions vs system在实际应用中你常常需要在不修改 Agent 定义的前提下临时调整指令。为此generate/stream的执行选项定义于 packages/core/src/agent/agent.types.ts提供了两个相关字段instructions覆盖Agent 默认 instructions 的自定义指令system追加到 prompt 中的额外系统消息。await agent.generate(帮我总结最近的消费, { system: { role: system, content: 请用中文回答并附上百分比变化。 }, });instructions.test.ts中的多个用例第 386-454 行、第 480-506 行、第 602-622 行专门验证了instructions 与 system 组合/覆盖的行为例如数组形式的 instructions 与数组形式的 system 可以同时传入而不报错。这一机制让你可以在不同入口API 路由、工作流步骤、子 Agent 委派复用同一个 Agent却按需调整其行为边界。将 system prompt 应用于子 Agent 与语音场景system prompt 的能力还延伸到多 Agent 场景在 packages/core/src/agent/agent.types.ts 中可以看到Agent 委派delegation时可通过params.instructions向子 Agent 传入附加指令NetworkRoutingConfig.additionalInstructions 则允许为路由 Agent 追加系统提示例如优先选择 coder 处理实现类任务。语音 Agent 同样受系统提示词约束agent.ts在构建语音时会将解析后的 instructions 通过addInstructions注入语音服务见 packages/core/src/agent/agent.ts测试用例instructions.test.ts第 508-529 行验证了结构化 system 消息会被正确转换为纯文本传入。这意味着你在 system prompt 中设定的角色、准则与约束会在文本、语音、子 Agent 等所有交互形态中保持一致。小结与建议围绕 Mastra 入门课程的指引结合源码验证编写 system prompt 的要点可以归纳为用角色、能力、行为准则、约束、成功标准五个分区组织内容既清晰又便于模型遵循优先使用字符串模板需要厂商级控制时使用结构化系统消息并携带providerOptions需要随上下文变化时把instructions写成函数支持async借助requestContext动态生成在运行期用system追加、用instructions覆盖实现同一 Agent 的多场景复用记住 system prompt 会沿用到语音与子 Agent 委派保持全链路行为一致。下一步可继续阅读同一课程中的 08-exporting-your-agent.md 与 09-testing-your-agent.md完成 Agent 的导出与测试闭环当 Agent 接入工具后system prompt 中的CORE CAPABILITIES部分将真正与可执行能力一一对应。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考