Genkit Dart 中间件实战filesystem、skills 与 toolApproval 全面指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skillsGenkit Dart 是 Google Genkit 面向 Dart/Flutter 的 AI SDK通过统一的接口支持文本生成、结构化输出、工具调用、流式响应与 Agent 工作流。本篇文章以genkit_middleware插件包为核心系统讲解三大 Agent 增强中间件——文件系统访问filesystem、技能注入skills与工具审批toolApproval——的初始化方式、配置参数、底层中断interrupt机制与完整的人机协同human-in-the-loop代码示例。读完本文你将能够在自己的 Genkit Dart Agent 中安全地开放文件读写、按需加载 SKILL.md 技能说明并为敏感工具接入显式的用户审批流程。一、中间件是什么从use:数组到插件注册在 Genkit Dart 中中间件middleware是一类在每次ai.generate或 Agent 回合turn执行时叠加的横切能力子 Agent 委派agents()、文件系统访问filesystem()、技能加载skills()、工具审批toolApproval()以及自动重试retry()都可以通过一行配置接入无需手写胶水代码。这些中间件被统一挂载在两个位置Genkit(plugins: [...])注册对应的插件Plugin让use:中的中间件引用在运行时可以解析use: [...]ai.generate或ai.defineAgent的参数按顺序叠加中间件。根据本仓库的 Genkit Dart 核心文档 与 Agent 文档retry和RetryPlugin随核心包package:genkit/genkit.dart一同提供而本文讨论的filesystem、skills、toolApproval以及多 Agent 编排用的agents全部来自独立的package:genkit_middleware插件包。在初始化 Genkit 时注册插件import package:genkit/genkit.dart; import package:genkit_middleware/genkit_middleware.dart; void main() { final ai Genkit( plugins: [ FilesystemPlugin(), SkillsPlugin(), ToolApprovalPlugin(), ], ); }注意genkit_middleware是聚合导出包实际使用时也可以按模块导入例如 Agent 参考文档 中的写法import package:genkit_middleware/filesystem.dart;、import package:genkit_middleware/skills.dart;、import package:genkit_middleware/tool_approval.dart;。与 Agent 的配合use:组合示例中间件与 Agent 是天然搭配的关系。在 agents.md 中给出了一个典型的 codingAgent 组合示例把本文的三个中间件与retry()一起叠加展示了一个完整的沙箱编码 Agentimport package:genkit/genkit.dart; import package:genkit_middleware/filesystem.dart; import package:genkit_middleware/skills.dart; import package:genkit_middleware/tool_approval.dart; final codingAgent ai.defineAgent( name: codingAgent, system: You are an expert AI coding assistant working in a sandboxed workspace., tools: [runShell, askUser], // your own custom tools/interrupts use: [ // Require user approval (interrupt) before risky tools; reads/run auto-approved. // Order matters: keep toolApproval before filesystem. toolApproval( approved: [list_files, read_file, use_skill, run_shell, ask_user], ), // list_files / read_file / write_file / search_and_replace, sandboxed. filesystem(rootDirectory: workspaceDir), // Load coding conventions on demand via a use_skill tool. skills(skillPaths: [skillsDir]), // Automatic retry on transient model errors. retry(), ], store: InMemorySessionStore(), // needed for tool approval maxTurns: 30, );这里有两点关键实践值得注意顺序敏感注释明确提示 Order matters: keep toolApproval before filesystem即审批中间件应放在文件系统中间件之前确保所有工具调用先经过审批门控需要会话存储toolApproval依赖中断interrupt机制实现暂停与恢复因此 Agent 必须配置store: InMemorySessionStore()或其它SessionStore详见后文第四部分与 会话与持久化文档。二、Filesystem 中间件受限根目录内的文件读写filesystem中间件允许 Agent 在一个**受限的根目录restricted root directory**内执行列目录、读取、写入与搜索替换操作。它通过限定根目录实现沙箱隔离——Agent 只能访问该目录以内的文件从机制上避免模型越权操作工作区之外的内容。在ai.generate中按需启用final response await ai.generate( prompt: Check the logs in the current directory., use: [ filesystem(rootDirectory: /path/to/secure/workspace), ], );提供的工具Tools Provided工具名作用list_files列出指定目录下的文件read_file读取文件内容write_file写入文件search_and_replace在文件中搜索并替换内容这些工具会被注入到当前回合的工具列表中模型可以在回答中自主决定何时调用。例如把filesystem挂到编码 Agent 上之后模型可以自行查看项目结构 → 读取源码 → 修改文件完成一次代码修复任务。从实现层面看filesystem中间件与 Agent 文档 中codingAgent的filesystem(rootDirectory: workspaceDir)用法完全一致——rootDirectory参数定义了文件操作的安全边界所有工具调用都会被约束在该目录内。三、Skills 中间件从 SKILL.md 按需注入专家指令skills中间件负责从指定目录中的SKILL.md文件加载技能说明skills并将其注入到系统提示词system prompt中。这在构建按需读取领域知识的 Agent 时非常有用与其把所有指令一次性塞进提示词不如让模型在需要时主动调用技能工具拉取完整内容从而节省上下文空间、提升响应质量。final response await ai.generate( prompt: Help me debug this issue., use: [ skills(skillPaths: [/path/to/skills]), ], );提供的工具use_skill按名称获取某个技能的完整内容。skillPaths参数接收一个路径列表Genkit 会在这些目录中扫描SKILL.md文件将其注册为可供模型调用的技能。在上面的codingAgent示例中skills(skillPaths: [skillsDir])让 Agent 可以在处理编码任务时按需加载团队的编码规范Load coding conventions on demand via a use_skill tool。设计意图skills中间件非常适合海量技能库 稀疏调用的场景。技能内容不会常驻提示词只有模型判断需要时才通过use_skill拉取既降低了 token 消耗又让 Agent 的能力边界可以持续扩展。四、Tool Approval 中间件敏感工具的人机审批toolApproval中间件是三个中间件中机制最复杂的部分它负责拦截指定工具的执行并要求显式审批。当模型请求执行一个未被批准的敏感工具时中间件会中断回合interrupt返回FinishReason.interrupted把控制权交回给调用方人类或上层代码等待确认后再从暂停点恢复执行。4.1 放行规则白名单或 resumed 载荷一个工具只有满足以下任一条件才会被放行它位于approved白名单列表中它的请求request的resumed载荷中携带{ tool-approved: true }。第一条对应默认拦截、显式放行的配置方式第二条则对应暂停后由人类批准再放行的恢复路径。final response await ai.generate( prompt: Delete the database., use: [ // Require approval for all tools EXCEPT those below toolApproval(approved: [read_file, list_files]), ], );4.2 中断与恢复的完整代码流下面是文档给出的完整审批流程发送请求 → 检测中断 → 询问用户 → 批准后恢复。final response await ai.generate( prompt: Delete the database., use: [ // Require approval for all tools EXCEPT those below toolApproval(approved: [read_file, list_files]), ], ); if (response.finishReason FinishReason.interrupted) { // response.interrupts is a ListToolRequestPart. final interrupt response.interrupts.first; // Ask user for approval final isApproved await askUser(); if (isApproved) { final resumeResponse await ai.generate( messages: response.messages, // Pass history toolChoice: ToolChoice.none, // Prevent immediate re-call interruptRestart: [ // .restart(...) nests the payload under metadata.resumed. interrupt.restart({tool-approved: true}), ], ); } }关键细节逐条拆解response.interrupts类型为ListToolRequestPart包含所有被拦截并暂停的工具请求response.messages恢复时必须把完整历史传回保证模型上下文连续toolChoice: ToolChoice.none防止模型在恢复时立即重新触发被暂停的工具调用interrupt.restart({tool-approved: true}).restart(...)构建器会把载荷payload嵌套到metadata.resumed下而这正是中间件读取放行标记的位置——载荷格式{ tool-approved: true }必须与中间件的检查逻辑严格一致。4.3 机制原理中间件读取metadata.resumed从实现机制看toolApproval之所以能暂停-放行核心在于.restart(...)构建器对请求元数据的处理To approve on resume, re-issue the pausedToolRequestPartwith.restart({tool-approved: true})— the builder nests the payload undermetadata.resumed, exactly what the middleware reads.也就是说恢复resume本质上是对被暂停的ToolRequestPart的重发re-issue重发时携带的{tool-approved: true}会被中间件读取并识别为人类已批准。这一机制与 Genkit Dart 的底层中断模型一脉相承——根据 Human-in-the-Loop 参考文档中断本质上是被用作控制流的工具调用它不会在服务端执行完成而是暂停回合随后从暂停点精确恢复。4.4 Agent 侧的恢复chat.resume当你在 Agent 对话而非裸ai.generate中使用toolApproval时暂停对象是AgentInterrupt而不是ToolRequestPart。此时把相同的.restart(...)构建器直接传给chat.resume即可chat.resume(restart: [interrupt.restart({tool-approved: true})]);相关文档明确指出When resuming an agent chat rather than a rawai.generatecall, the interrupts areAgentInterrupts; pass the same.restart(...)builder directly tochat.resume.更完整的 Agent 侧暂停-恢复流程参见 agents-human-in-the-loop.md其中还介绍了AgentInterrupt暴露的构建器.respond(output)提供工具输出而不执行与.restart([payload])重发原始工具请求可携带可选载荷混合恢复chat.resume可以同时传respond:与restart:列表一次性处理多个中断流式恢复chat.resumeStream(respond: [...])配合await for逐块渲染输出自定义中断场景下可通过ctx.resumed读取.restart(...)传入的载荷自行检查resumed is Map resumed[tool-approved] true。// interrupt is the paused AgentInterrupt from res.interrupts. // Pass this restart entry back when resuming the chat: await chat.resume( restart: [interrupt.restart({tool-approved: true})], );4.5 使用注意事项必须配置SessionStoreAgent 使用toolApproval时需要服务端持久化会话如InMemorySessionStore()以便恢复时准确定位暂停点。不过中断与持久化是正交的——根据 会话文档中断无论有无 store 都能工作但toolApproval的恢复流程依赖 store 承载会话快照链恢复条目必须从响应构建服务端会校验每个respond/restart条目与对话历史的匹配性务必基于响应中的中断对象构建恢复条目不要手写伪造 Part可能再次中断恢复后新的响应仍可能再次触发中断需要循环处理直到res.interrupts为空子 Agent 的中断会降级为普通工具响应根据 多 Agent 编排文档子 Agent 触发的中断会作为普通工具响应汇报给编排者而不会传播为可恢复的中断因此委派给子 Agent 的任务应保持自包含。五、实战组合一个带审批的安全编码 Agent综合以上三节可以把全部能力组装为一个实战 Agent。以下示例综合了 Agent 文档 的codingAgent模式与 中间件文档 的三个中间件import package:genkit/genkit.dart; import package:genkit_middleware/genkit_middleware.dart; import package:genkit_google_genai/genkit_google_genai.dart; void main() { final ai Genkit( plugins: [ googleAI(), // 模型插件 FilesystemPlugin(), // filesystem 中间件依赖 SkillsPlugin(), // skills 中间件依赖 ToolApprovalPlugin(), // toolApproval 中间件依赖 RetryPlugin(), // 自动重试核心包 ], model: googleAI.gemini(gemini-flash-latest), ); final workspaceDir /path/to/secure/workspace; final skillsDir /path/to/skills; final codingAgent ai.defineAgent( name: safeCodingAgent, system: You are an expert AI coding assistant working in a sandboxed workspace. Always request user approval before destructive actions., use: [ // 先审批只放行读取类工具其余如 write_file / search_and_replace需人工批准 toolApproval(approved: [list_files, read_file, use_skill]), // 再文件系统所有读写都被限制在 workspaceDir 内 filesystem(rootDirectory: workspaceDir), // 按需加载技能模型需要时调用 use_skill skills(skillPaths: [skillsDir]), retry(), ], store: InMemorySessionStore(), // toolApproval 必需 maxTurns: 30, ); // 与服务端交互时检测中断并人工审批 // final res await chat.send(text: Fix the bug in src/main.dart); // if (res.interrupts.isNotEmpty) { // await chat.resume(restart: [ // res.interrupts.first.restart({tool-approved: true}), // ]); // } }这个组合清晰地展示了三个中间件的分工中间件承担的安全/能力职责toolApproval默认拦截所有工具仅放行approved白名单危险操作必须人工批准filesystem把文件操作约束在workspaceDir沙箱内skills按需加载skillsDir中的 SKILL.md 技能说明六、中间件的更多应用Dotprompt 与多 Agent 编排中间件机制并不局限于 Dart 代码内联使用它在 Genkit Dart 的其它能力中同样贯穿始终Dotprompt 声明式使用根据 Dotprompt 文档.prompt文件的 YAML frontmatter 支持tools、maxTurns、returnToolRequests以及use中间件字段意味着你可以在提示词模板层面声明需要挂载的中间件把用哪个模型、开哪些工具、挂哪些中间件统一收口到提示词文件中多 Agent 委派agents()中间件同样来自package:genkit_middleware会为每个子 Agent 注入一个委派工具delegate_to_name并向编排者的系统提示词追加sub-agents说明块详见 agents-multi-agent.md本地开发调试使用 Genkit CLI 的genkit start -- dart run main.dart启动应用参见 SKILL.md可捕获每一次工具调用与中间件交互的 trace在 Developer UI默认 http://localhost:4000中直观验证filesystem/skills/toolApproval是否按预期工作。总结genkit_middleware为 Genkit Dart Agent 提供了三件套式的能力增强filesystem以受限根目录实现安全的文件访问skills通过use_skill工具实现技能按需注入toolApproval借助中断机制为敏感工具构建完整的人机审批闭环。三者可以独立使用也可以像codingAgent那样按先审批、后文件、再技能的顺序组合并在Genkit(plugins: [...])中注册对应的FilesystemPlugin、SkillsPlugin与ToolApprovalPlugin。理解toolApproval背后的metadata.resumed放行协议与.restart(...)构建器是掌握 Genkit Dart 人机协同开发的关键。更多相关细节可继续阅读本仓库的 agents.md、agents-human-in-the-loop.md 与 agents-multi-agent.md。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Genkit Dart 中间件实战：filesystem、skills 与 toolApproval 全面指南
Genkit Dart 中间件实战filesystem、skills 与 toolApproval 全面指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skillsGenkit Dart 是 Google Genkit 面向 Dart/Flutter 的 AI SDK通过统一的接口支持文本生成、结构化输出、工具调用、流式响应与 Agent 工作流。本篇文章以genkit_middleware插件包为核心系统讲解三大 Agent 增强中间件——文件系统访问filesystem、技能注入skills与工具审批toolApproval——的初始化方式、配置参数、底层中断interrupt机制与完整的人机协同human-in-the-loop代码示例。读完本文你将能够在自己的 Genkit Dart Agent 中安全地开放文件读写、按需加载 SKILL.md 技能说明并为敏感工具接入显式的用户审批流程。一、中间件是什么从use:数组到插件注册在 Genkit Dart 中中间件middleware是一类在每次ai.generate或 Agent 回合turn执行时叠加的横切能力子 Agent 委派agents()、文件系统访问filesystem()、技能加载skills()、工具审批toolApproval()以及自动重试retry()都可以通过一行配置接入无需手写胶水代码。这些中间件被统一挂载在两个位置Genkit(plugins: [...])注册对应的插件Plugin让use:中的中间件引用在运行时可以解析use: [...]ai.generate或ai.defineAgent的参数按顺序叠加中间件。根据本仓库的 Genkit Dart 核心文档 与 Agent 文档retry和RetryPlugin随核心包package:genkit/genkit.dart一同提供而本文讨论的filesystem、skills、toolApproval以及多 Agent 编排用的agents全部来自独立的package:genkit_middleware插件包。在初始化 Genkit 时注册插件import package:genkit/genkit.dart; import package:genkit_middleware/genkit_middleware.dart; void main() { final ai Genkit( plugins: [ FilesystemPlugin(), SkillsPlugin(), ToolApprovalPlugin(), ], ); }注意genkit_middleware是聚合导出包实际使用时也可以按模块导入例如 Agent 参考文档 中的写法import package:genkit_middleware/filesystem.dart;、import package:genkit_middleware/skills.dart;、import package:genkit_middleware/tool_approval.dart;。与 Agent 的配合use:组合示例中间件与 Agent 是天然搭配的关系。在 agents.md 中给出了一个典型的 codingAgent 组合示例把本文的三个中间件与retry()一起叠加展示了一个完整的沙箱编码 Agentimport package:genkit/genkit.dart; import package:genkit_middleware/filesystem.dart; import package:genkit_middleware/skills.dart; import package:genkit_middleware/tool_approval.dart; final codingAgent ai.defineAgent( name: codingAgent, system: You are an expert AI coding assistant working in a sandboxed workspace., tools: [runShell, askUser], // your own custom tools/interrupts use: [ // Require user approval (interrupt) before risky tools; reads/run auto-approved. // Order matters: keep toolApproval before filesystem. toolApproval( approved: [list_files, read_file, use_skill, run_shell, ask_user], ), // list_files / read_file / write_file / search_and_replace, sandboxed. filesystem(rootDirectory: workspaceDir), // Load coding conventions on demand via a use_skill tool. skills(skillPaths: [skillsDir]), // Automatic retry on transient model errors. retry(), ], store: InMemorySessionStore(), // needed for tool approval maxTurns: 30, );这里有两点关键实践值得注意顺序敏感注释明确提示 Order matters: keep toolApproval before filesystem即审批中间件应放在文件系统中间件之前确保所有工具调用先经过审批门控需要会话存储toolApproval依赖中断interrupt机制实现暂停与恢复因此 Agent 必须配置store: InMemorySessionStore()或其它SessionStore详见后文第四部分与 会话与持久化文档。二、Filesystem 中间件受限根目录内的文件读写filesystem中间件允许 Agent 在一个**受限的根目录restricted root directory**内执行列目录、读取、写入与搜索替换操作。它通过限定根目录实现沙箱隔离——Agent 只能访问该目录以内的文件从机制上避免模型越权操作工作区之外的内容。在ai.generate中按需启用final response await ai.generate( prompt: Check the logs in the current directory., use: [ filesystem(rootDirectory: /path/to/secure/workspace), ], );提供的工具Tools Provided工具名作用list_files列出指定目录下的文件read_file读取文件内容write_file写入文件search_and_replace在文件中搜索并替换内容这些工具会被注入到当前回合的工具列表中模型可以在回答中自主决定何时调用。例如把filesystem挂到编码 Agent 上之后模型可以自行查看项目结构 → 读取源码 → 修改文件完成一次代码修复任务。从实现层面看filesystem中间件与 Agent 文档 中codingAgent的filesystem(rootDirectory: workspaceDir)用法完全一致——rootDirectory参数定义了文件操作的安全边界所有工具调用都会被约束在该目录内。三、Skills 中间件从 SKILL.md 按需注入专家指令skills中间件负责从指定目录中的SKILL.md文件加载技能说明skills并将其注入到系统提示词system prompt中。这在构建按需读取领域知识的 Agent 时非常有用与其把所有指令一次性塞进提示词不如让模型在需要时主动调用技能工具拉取完整内容从而节省上下文空间、提升响应质量。final response await ai.generate( prompt: Help me debug this issue., use: [ skills(skillPaths: [/path/to/skills]), ], );提供的工具use_skill按名称获取某个技能的完整内容。skillPaths参数接收一个路径列表Genkit 会在这些目录中扫描SKILL.md文件将其注册为可供模型调用的技能。在上面的codingAgent示例中skills(skillPaths: [skillsDir])让 Agent 可以在处理编码任务时按需加载团队的编码规范Load coding conventions on demand via a use_skill tool。设计意图skills中间件非常适合海量技能库 稀疏调用的场景。技能内容不会常驻提示词只有模型判断需要时才通过use_skill拉取既降低了 token 消耗又让 Agent 的能力边界可以持续扩展。四、Tool Approval 中间件敏感工具的人机审批toolApproval中间件是三个中间件中机制最复杂的部分它负责拦截指定工具的执行并要求显式审批。当模型请求执行一个未被批准的敏感工具时中间件会中断回合interrupt返回FinishReason.interrupted把控制权交回给调用方人类或上层代码等待确认后再从暂停点恢复执行。4.1 放行规则白名单或 resumed 载荷一个工具只有满足以下任一条件才会被放行它位于approved白名单列表中它的请求request的resumed载荷中携带{ tool-approved: true }。第一条对应默认拦截、显式放行的配置方式第二条则对应暂停后由人类批准再放行的恢复路径。final response await ai.generate( prompt: Delete the database., use: [ // Require approval for all tools EXCEPT those below toolApproval(approved: [read_file, list_files]), ], );4.2 中断与恢复的完整代码流下面是文档给出的完整审批流程发送请求 → 检测中断 → 询问用户 → 批准后恢复。final response await ai.generate( prompt: Delete the database., use: [ // Require approval for all tools EXCEPT those below toolApproval(approved: [read_file, list_files]), ], ); if (response.finishReason FinishReason.interrupted) { // response.interrupts is a ListToolRequestPart. final interrupt response.interrupts.first; // Ask user for approval final isApproved await askUser(); if (isApproved) { final resumeResponse await ai.generate( messages: response.messages, // Pass history toolChoice: ToolChoice.none, // Prevent immediate re-call interruptRestart: [ // .restart(...) nests the payload under metadata.resumed. interrupt.restart({tool-approved: true}), ], ); } }关键细节逐条拆解response.interrupts类型为ListToolRequestPart包含所有被拦截并暂停的工具请求response.messages恢复时必须把完整历史传回保证模型上下文连续toolChoice: ToolChoice.none防止模型在恢复时立即重新触发被暂停的工具调用interrupt.restart({tool-approved: true}).restart(...)构建器会把载荷payload嵌套到metadata.resumed下而这正是中间件读取放行标记的位置——载荷格式{ tool-approved: true }必须与中间件的检查逻辑严格一致。4.3 机制原理中间件读取metadata.resumed从实现机制看toolApproval之所以能暂停-放行核心在于.restart(...)构建器对请求元数据的处理To approve on resume, re-issue the pausedToolRequestPartwith.restart({tool-approved: true})— the builder nests the payload undermetadata.resumed, exactly what the middleware reads.也就是说恢复resume本质上是对被暂停的ToolRequestPart的重发re-issue重发时携带的{tool-approved: true}会被中间件读取并识别为人类已批准。这一机制与 Genkit Dart 的底层中断模型一脉相承——根据 Human-in-the-Loop 参考文档中断本质上是被用作控制流的工具调用它不会在服务端执行完成而是暂停回合随后从暂停点精确恢复。4.4 Agent 侧的恢复chat.resume当你在 Agent 对话而非裸ai.generate中使用toolApproval时暂停对象是AgentInterrupt而不是ToolRequestPart。此时把相同的.restart(...)构建器直接传给chat.resume即可chat.resume(restart: [interrupt.restart({tool-approved: true})]);相关文档明确指出When resuming an agent chat rather than a rawai.generatecall, the interrupts areAgentInterrupts; pass the same.restart(...)builder directly tochat.resume.更完整的 Agent 侧暂停-恢复流程参见 agents-human-in-the-loop.md其中还介绍了AgentInterrupt暴露的构建器.respond(output)提供工具输出而不执行与.restart([payload])重发原始工具请求可携带可选载荷混合恢复chat.resume可以同时传respond:与restart:列表一次性处理多个中断流式恢复chat.resumeStream(respond: [...])配合await for逐块渲染输出自定义中断场景下可通过ctx.resumed读取.restart(...)传入的载荷自行检查resumed is Map resumed[tool-approved] true。// interrupt is the paused AgentInterrupt from res.interrupts. // Pass this restart entry back when resuming the chat: await chat.resume( restart: [interrupt.restart({tool-approved: true})], );4.5 使用注意事项必须配置SessionStoreAgent 使用toolApproval时需要服务端持久化会话如InMemorySessionStore()以便恢复时准确定位暂停点。不过中断与持久化是正交的——根据 会话文档中断无论有无 store 都能工作但toolApproval的恢复流程依赖 store 承载会话快照链恢复条目必须从响应构建服务端会校验每个respond/restart条目与对话历史的匹配性务必基于响应中的中断对象构建恢复条目不要手写伪造 Part可能再次中断恢复后新的响应仍可能再次触发中断需要循环处理直到res.interrupts为空子 Agent 的中断会降级为普通工具响应根据 多 Agent 编排文档子 Agent 触发的中断会作为普通工具响应汇报给编排者而不会传播为可恢复的中断因此委派给子 Agent 的任务应保持自包含。五、实战组合一个带审批的安全编码 Agent综合以上三节可以把全部能力组装为一个实战 Agent。以下示例综合了 Agent 文档 的codingAgent模式与 中间件文档 的三个中间件import package:genkit/genkit.dart; import package:genkit_middleware/genkit_middleware.dart; import package:genkit_google_genai/genkit_google_genai.dart; void main() { final ai Genkit( plugins: [ googleAI(), // 模型插件 FilesystemPlugin(), // filesystem 中间件依赖 SkillsPlugin(), // skills 中间件依赖 ToolApprovalPlugin(), // toolApproval 中间件依赖 RetryPlugin(), // 自动重试核心包 ], model: googleAI.gemini(gemini-flash-latest), ); final workspaceDir /path/to/secure/workspace; final skillsDir /path/to/skills; final codingAgent ai.defineAgent( name: safeCodingAgent, system: You are an expert AI coding assistant working in a sandboxed workspace. Always request user approval before destructive actions., use: [ // 先审批只放行读取类工具其余如 write_file / search_and_replace需人工批准 toolApproval(approved: [list_files, read_file, use_skill]), // 再文件系统所有读写都被限制在 workspaceDir 内 filesystem(rootDirectory: workspaceDir), // 按需加载技能模型需要时调用 use_skill skills(skillPaths: [skillsDir]), retry(), ], store: InMemorySessionStore(), // toolApproval 必需 maxTurns: 30, ); // 与服务端交互时检测中断并人工审批 // final res await chat.send(text: Fix the bug in src/main.dart); // if (res.interrupts.isNotEmpty) { // await chat.resume(restart: [ // res.interrupts.first.restart({tool-approved: true}), // ]); // } }这个组合清晰地展示了三个中间件的分工中间件承担的安全/能力职责toolApproval默认拦截所有工具仅放行approved白名单危险操作必须人工批准filesystem把文件操作约束在workspaceDir沙箱内skills按需加载skillsDir中的 SKILL.md 技能说明六、中间件的更多应用Dotprompt 与多 Agent 编排中间件机制并不局限于 Dart 代码内联使用它在 Genkit Dart 的其它能力中同样贯穿始终Dotprompt 声明式使用根据 Dotprompt 文档.prompt文件的 YAML frontmatter 支持tools、maxTurns、returnToolRequests以及use中间件字段意味着你可以在提示词模板层面声明需要挂载的中间件把用哪个模型、开哪些工具、挂哪些中间件统一收口到提示词文件中多 Agent 委派agents()中间件同样来自package:genkit_middleware会为每个子 Agent 注入一个委派工具delegate_to_name并向编排者的系统提示词追加sub-agents说明块详见 agents-multi-agent.md本地开发调试使用 Genkit CLI 的genkit start -- dart run main.dart启动应用参见 SKILL.md可捕获每一次工具调用与中间件交互的 trace在 Developer UI默认 http://localhost:4000中直观验证filesystem/skills/toolApproval是否按预期工作。总结genkit_middleware为 Genkit Dart Agent 提供了三件套式的能力增强filesystem以受限根目录实现安全的文件访问skills通过use_skill工具实现技能按需注入toolApproval借助中断机制为敏感工具构建完整的人机审批闭环。三者可以独立使用也可以像codingAgent那样按先审批、后文件、再技能的顺序组合并在Genkit(plugins: [...])中注册对应的FilesystemPlugin、SkillsPlugin与ToolApprovalPlugin。理解toolApproval背后的metadata.resumed放行协议与.restart(...)构建器是掌握 Genkit Dart 人机协同开发的关键。更多相关细节可继续阅读本仓库的 agents.md、agents-human-in-the-loop.md 与 agents-multi-agent.md。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考