人工智能AI Agent代码智能体AI 应用CLI开发工具【免费下载链接】forgecodeAI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300 models项目地址https://gitcode.com/gh_mirrors/forge39/forgecode点击查看免费下载导读Forge 的task工具是面向复杂多步任务设计的代理型工具agentic tool它不再执行一段固定的函数逻辑而是启动一个或多个具备独立工具集与系统提示词的专业化 Agent如实现型 Agentforge、规划型 Agentmuse、研究型 Agentsage让它们自主完成任务。本篇文章以 crates/forge_domain/src/tools/descriptions/task.md 为骨架结合 Forge 源码深入讲解task工具的参数结构、使用规范、并行委派、会话恢复与底层执行链路帮助读者掌握在真实开发会话中正确、高效地委派子代理的方法。一、什么是 Task 工具task工具的核心定位是启动一个新 Agent 来自主处理复杂、多步骤的任务。它区别于read、fs_search、write等功能性工具——后者由固定代码直接执行而task的内部是一个由 LLM 驱动的完整子会话subprocess/subagent。在 crates/forge_domain/src/tools/catalog.rs 中Task被注册为系统工具目录ToolCatalog的一个变体带Task别名其输入结构TaskInput通过#[tool_description_file]宏直接引用本篇文章对应的描述文件#[serde(alias Task)] Task(TaskInput),子代理的执行结果对用户并不可见只返回给主 Agent 一条消息主 Agent 需要用自己的话向用户转述摘要。这是理解task工具工作模式的关键前提。二、Task 工具的参数结构从 TaskInput 结构定义 可以看到调用task工具时必须提供三个参数参数类型必填说明tasksVecString是一组清晰、详细的任务描述Agent 会并行执行这些任务每条任务需包含足够的上下文和具体要求agent_idString是要委派给的专业 Agent 的 ID例如forge、muse、sage决定子代理拥有的能力与工具集session_idOptionString否续接已有 Agent 会话的 ID不提供时创建新的无状态会话提供时可跨多次调用保持上下文其中session_id在序列化时使用skip_serializing_if Option::is_none即未提供时不会出现在调用参数中保持请求体精简。关于agent_id描述文件原文写作 you must specify a agent_id parameter即每次调用都必须显式指定选择哪个 Agent 类型——主 Agent 不能省略该参数、也不能靠猜测推断。三、可用的 Agent 类型与能力边界task工具描述中的Available agent types and the tools they have access to部分由 Handlebars 模板动态渲染{{#each agents}}系统在生成工具描述时会把当前注册的所有 Agent及其可用工具列表逐一列出。Forge 仓库自带三个内置 Agent 定义均存放在 crates/forge_repo/src/agents/1. forge —— 实现型 Agent定义在 forge.md定位为执行技术开发任务的实操 Agent擅长通过直接改代码、文件操作和系统命令完成功能开发、修 Bug、重构、跑测试。可用工具包括task、sem_search、fs_search、read、write、undo、remove、patch、multi_patch、shell、fetch、skill、todo_write、todo_read以及所有mcp_*工具。2. muse —— 规划型 Agent定义在 muse.md定位为生成详细实施计划的战略规划 Agent。它只分析、不修改检查项目结构、识别风险、在plans/目录生成带目标、实施步骤与验证标准的 Markdown 计划文档。可用工具为sem_search、sage、search、read、fetch、plan与mcp_*。3. sage —— 深度研究型 Agent定义在 sage.md定位为纯只读研究 Agent用于需要跨多文件系统调研的架构分析、调用链追踪、模式识别等深度任务。可用工具为sem_search、search、read、fetch严格只读、无副作用。除了内置 Agent用户还可以通过自定义 Agent 文件扩展这一列表注册后的 Agent 会同样出现在task工具描述的 agents 列表中由主 Agent 按agent_id委派。从 ForgeAgentRegistryService 的源码可以看到Agent 列表由AgentRepository惰性加载进内存DashMap并提供get_agents、get_agent、reload_agents等方法确保运行时能够动态反映 Agent 定义的变化。四、什么时候不该用 Task 工具描述文件明确列出了三类杀鸡用牛刀的反例遇到这些场景应改用更轻量的工具只想读某个具体文件用read或fs_search直接命中更快搜索某个类定义如class Foo用fs_search做正则检索避免启动完整子代理的开销在 23 个具体文件里找代码用read逐个读取即可与上述 Agent 描述无关的其他任务不应盲目套用task工具。这条约束与 fs_search.md 描述 中开放式的多轮搜索才使用 Task 工具的原则互相呼应简单查找走专用工具开放式调研才委派子代理。五、使用规范写出可自主执行的任务描述文件给出了一套明确的使用规范Usage notes是主 Agent 正确使用task工具的操作守则必须附上 35 个词的简短描述概括 Agent 将要做什么尽可能并行启动多个 Agent在同一消息中携带多个 tool use最大化吞吐结果需要转述子代理完成后返回单条消息其内容用户看不到主 Agent 必须再发一条文本消息向用户给出简明摘要明确说明期望子代理不知道用户的真实意图必须清楚告诉它写代码还是只做研究搜索、读文件、抓取网页等任务提示词要详细提供清晰、完整的上下文让 Agent 能自主工作并精确返回所需信息信任输出子代理的输出通常应被信任主动使用若 Agent 描述中注明应主动使用则无需等用户开口主 Agent 应自行判断并提前委派。5.1 并行执行的强制要求描述文件特别强调只要用户要求并行运行 Agent就必须在单条消息中发送多个tasktool use 内容块。例如需要同时启动 build-validator 和 test-runner 两个 Agent 时必须在同一条消息里携带两次工具调用而不是顺序调用。这一约束在 forge.md 的 Tool Selection 一节也有对应强调If the user specifies that they want you to run tools in parallel, you MUST send a single message with multiple tool use content blocks。5.2 支持访问当前上下文的 Agent部分 Agent 具有访问当前上下文的能力——它们能看到本次工具调用之前完整的对话历史。对于这类 Agent主 Agent 可以写精简提示词例如调查上面讨论的那个错误直接引用此前上下文而不必重复信息因为子代理会收到全部历史消息。反之对于无此能力的 Agent每次调用都是全新会话必须把必要上下文全部写进任务描述。六、会话恢复session_id 机制描述文件对session_id的语义作了精确说明恢复模式传入上次调用返回的 agent ID 作为session_id子代理将完整保留此前的上下文继续工作全新模式不传session_id时每次调用都是全新会话此时必须提供包含全部必要上下文的任务描述。对应到实现层面TaskInput.session_id在 tool_registry.rs 中被解析为forge_domain::ConversationId解析失败则静默降级为None随后传递给AgentExecutor.execute。在 agent_executor.rs 中可以看到完整的会话复用逻辑let conversation if let Some(conversation_id) conversation_id { // 恢复模式查找既有会话未找到则报 ConversationNotFound 错误 self.services.conversation_service().find_conversation(conversation_id).await? .ok_or(Error::ConversationNotFound { id: conversation_id })? } else { // 全新模式创建新会话initiator 标记为 agent对 GitHub Copilot 计费优化至关重要 let context forge_domain::Context::default().initiator(agent.to_string()); let conversation Conversation::generate().title(task.clone()).context(context.clone()); self.services.conversation_service().upsert_conversation(conversation.clone()).await?; conversation };子代理完成后AgentExecutor.execute会返回ToolOutput::ai(conversation.id, ...)即把会话 ID 作为返回值的一部分带回给主 Agent主 Agent 可以保存这个 ID在后续需要跟进工作时用它续接会话。七、源码级执行链路从工具调用到子代理完成理解task工具背后完整链路有助于把握其能力边界与错误处理方式。7.1 分派入口在 tool_registry.rs 的 call_inner 中Task工具被特殊处理绕过普通工具的超时包装与权限检查流程if let ToolCatalog::Task(task_input) tool_input { let executor self.agent_executor.clone(); let session_id task_input.session_id.clone(); let agent_id task_input.agent_id.clone(); // NOTE: Agents should not timeout let outputs join_all(task_input.tasks.into_iter().map(|task| { let agent_id agent_id.clone(); let executor executor.clone(); async move { executor.execute(AgentId::new(agent_id), task, context, conversation_id).await } })).await.into_iter().collect::anyhow::ResultVec_()?; return Ok(ToolOutput::from(outputs.into_iter())); }两个关键设计值得注意join_all并发执行tasks数组中的多个任务被并发地分发给同一个agent_id对应的 Agent这正是单消息多 tool use 并行委派在实现层的落地方式子代理不设超时源码注释明确写着 Agents should not timeout即 LLM 驱动的子代理执行不受普通工具超时限制对比之下fs_search、shell等普通工具都经由call_with_timeout包裹。7.2 子会话执行AgentExecutor.executeagent_executor.rs随后完成以下步骤通过ctx.send_tool_input向用户界面发送[AGENT]调试标题与任务副标题展示委派过程按上文逻辑复用或新建会话构造ChatRequest::new(Event::new(task), conversation.id)调用ForgeApp::chat启动子代理的完整对话循环流式收集子代理输出Markdown内容分 partial 与非 partial 两种累加策略被汇总子代理内部的工具调用事件ToolCallStart/ToolCallEnd会转发给父级上下文展示推理内容TaskReasoning被忽略若子代理返回Interrupt则向上抛出带说明的错误——明确指出这是一个由 LLM 驱动的代理型工具失败通常源于模型限制、提示词问题或达到安全上限输出为空时返回EmptyToolResponse错误非空时封装为task_completed元素返回。7.3 描述渲染的稳定性task工具的描述文本是在运行时由 Handlebars 模板引擎渲染的见 get_system_tools系统先对所有 Agent 按 ID 排序再渲染{{#each agents}}列表。排序保证了无论 Agent 注册顺序如何渲染出的描述都稳定一致——这由测试 test_task_tool_description_is_stable_across_agent_order 直接验证它把同一组 Agent 正序与倒序分别渲染task描述并断言两者完全相等。八、相关配置项research_subagent 与 subagentstask工具的可用 Agent 集合受 crates/forge_config/src/config.rs 两个配置项影响research_subagent: bool默认false设为true时深度研究 Agentsage会被加入 Agent 列表并启用:sage命令。在 tool_registry.rs 中当该配置关闭时sage与agent会被从task工具描述中过滤掉主 Agent 便不会在描述里看到并误用它们subagents: bool默认false为true时forgeAgent 获得task工具用于委派子代理同时sage只读研究工具被移除为false时task工具禁用、sage取而代之。因此实际使用中主 Agent 能否看到并调用task工具、能看到哪些子代理取决于上述配置与已注册 Agent 的叠加结果。九、完整示例9.1 委派测试执行以下示例演示写完代码后委派 test-runner的完整流程user: Please write a function that checks if a number is primeassistant: 先使用write工具写入isPrime函数function isPrime(n) { if (n 1) return false for (let i 2; i * i n; i) { if (n % i 0) return false } return true }由于已写出重要代码且任务完成现在使用 test-runner Agent 运行测试assistant: Now let me use thetasktool to launch the test-runner agent这里体现了规范中的两条要点任务描述必须让 Agent 知道要做什么运行测试验证素数函数并且写完代码、任务收尾这一时机判断由主 Agent 完成。9.2 响应问候的子代理user: Hello由于用户在问候使用 greeting-responder Agent 回复一个友好玩笑assistant: Im going to use thetasktool to launch the greeting-responder agent该示例说明当 Agent 描述中注明应主动使用如 greeting-responder 被定义为收到问候时以玩笑回应主 Agent 应当在用户没有明确要求时就主动调用task工具。9.3 并行委派示例若用户要求并行执行必须构造单条消息、多个 tool use例如同时发出{name: task, arguments: {agent_id: forge, tasks: [运行 cargo build 并修复编译错误]}} {name: task, arguments: {agent_id: sage, tasks: [调研本项目认证模块的架构输出研究报告]}}两个调用在同一条 assistant 消息中发出join_all会并发执行互不阻塞。结语task工具是 Forge 多 Agent 协作架构的核心枢纽它以代理型工具的形式把复杂多步任务委托给具备专门工具集与提示词的子代理并通过agent_id、tasks、session_id三个参数分别控制委派给谁并行做什么是否续接上下文。理解其描述文件中的使用规范、并行约束与反例清单再结合 tool_registry.rs 的分派逻辑与 agent_executor.rs 的会话执行链路就能在真实开发中把子代理用对、用准、用快。赞分享人工智能AI Agent代码智能体AI 应用CLI开发工具【免费下载链接】forgecodeAI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300 models项目地址https://gitcode.com/gh_mirrors/forge39/forgecode点击查看免费下载相关推荐MoviePilot Agent 复杂任务执行与恢复机制深度解析MoviePilot Agent 复杂任务执行与恢复机制深度解析 MoviePilot 的 Agent 通过模型、Skills、工具与会话状态协作完成 NAS后端AI AgentMCP 服务AI 技能vim-airline会话恢复钩子恢复后执行操作vim airline会话恢复钩子恢复后执行操作 会话恢复钩子基础 在使用Vim进行开发时会话Session功能可以帮助我们保存当前的工作状态包括打开开发工具UI组件graphify 在 Trae 上的并行语义抽取Step B2 的 Task 工具子代理派发机制全解析graphify 在 Trae 上的并行语义抽取Step B2 的 Task 工具子代理派发机制全解析 本文聚焦 graphify 语义抽取管线中的「Step人工智能知识图谱RAGAI 技能开发工具MCP 服务上一篇探索未来交互Gaze-detection - 眼动追踪新纪元下一篇推荐开源项目Lottie-Windows — 动画设计的革命性工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考