SII CLI

简体中文

English

简体中文

English

主题

agent_tool - 子代理管理 ​

概述 ​

agent_tool 工具用于创建和管理专门的子代理，实现复杂任务的委托，并提供受控的工具访问和上下文隔离。子代理是具有特定能力和专长的独立 AI 实例，可以处理特定类型的任务。

工具名称 ​

  • 内部名称: agent_tool
  • 显示名称: Agent Tool
  • 图标: 用户组 (Users)

参数 ​

必需参数 ​

参数名类型说明
agentTypestring要创建的子代理类型。可用类型见下文。
taskstring子代理要完成的具体任务。要清晰详细地说明你希望子代理完成什么。

可选参数 ​

参数名类型默认值说明
contextstring"partial"与子代理共享的上下文级别。"partial" 共享相关上下文，"full" 共享完整对话，"minimal" 仅共享任务。
maxTurnsnumber15子代理的最大对话轮数。更高的值允许更复杂的任务但使用更多资源。范围：1-50。
prioritystring"normal"资源分配的优先级。更高优先级的代理获得更多资源。可选值："high"、"normal"、"low"。
timeoutMsnumber300000子代理执行的超时时间（毫秒）。更长的超时允许更复杂的任务。范围：30000-1800000（30秒-30分钟）。

可用的代理类型 ​

1. Architect（架构师） ​

  • 类型名: "architect"
  • 用途: 当仓库较大/未知或需要在行动前绘制结构图时使用
  • 交付物: docs/architecture.md 包含仓库地图（目录、关键模块、数据流、依赖热点）
  • 典型工具: read_file、search_file_content、glob、write_file
  • 特点: 不修改代码；编写单个架构文档后停止

2. SpecFlow（规范流程） ​

  • 类型名: "specflow"
  • 用途: 端到端的功能/bug 工作，采用 计划 → 审查 → 执行 工作流
  • 交付物: 具体计划、最小安全差异和验证说明；默认避免使用 shell
  • 典型工具: read_file、search_file_content、glob、write_file

3. Refactor（重构） ​

  • 类型名: "refactor"
  • 用途: 跨多个文件的模式级更改，具有严格的一致性和小批量处理
  • 交付物: 一组精确的编辑，附带理由和回滚说明
  • 典型工具: read_file、search_file_content、glob、write_file

4. Researcher（研究员） ​

  • 类型名: "researcher"
  • 用途: 需要外部知识时（API、库、基准测试）
  • 交付物: docs/research/<topic>.md 包含来源和综合信息
  • 典型工具: web_search、web_fetch、read_file、write_file

5. Debug Analyzer（调试分析器） ​

  • 类型名: "debug-analyzer"
  • 用途: 系统性问题调查、错误分析和故障排除
  • 交付物: 包含根本原因分析和解决方案验证的综合调试报告
  • 典型工具: read_file、search_file_content、glob、write_file
  • 特点: 专注于基于证据的分析，在调查期间保持系统稳定性

编排模式 ​

大型/未知仓库 ​

  1. 调用 Architect 创建 docs/architecture.md（或更新它）
  2. 然后将具体计划交给 SpecFlow，引用该文档

模式级更改 ​

使用 Refactor，提供清晰的规范和示例；偏好批量更改，批次之间进行验证

需要外部知识 ​

首先调用 Researcher；归档发现，然后继续使用 SpecFlow/Refactor

自然停止（无硬性限制） ​

  • 当计划完全执行或连续两个无操作步骤（无新差异/发现）后停止
  • 如果任务增长，保存当前阶段文档（计划/架构/重构批次）并停止，说明下一步

使用示例 ​

创建架构文档 ​

json
{
  "agentType": "architect",
  "task": "分析这个 Node.js 项目的结构，创建架构文档，包括主要模块、依赖关系和数据流",
  "context": "partial",
  "maxTurns": 20
}

实现新功能 ​

json
{
  "agentType": "specflow",
  "task": "实现用户认证功能，包括登录、注册和密码重置。遵循项目现有的代码风格和架构模式",
  "context": "full",
  "maxTurns": 30,
  "priority": "high"
}

重构代码 ​

json
{
  "agentType": "refactor",
  "task": "将所有组件从类组件重构为函数组件，使用 React Hooks。保持功能不变，添加适当的测试",
  "context": "partial",
  "maxTurns": 25
}

研究技术方案 ​

json
{
  "agentType": "researcher",
  "task": "研究 React 状态管理方案（Redux、MobX、Zustand、Recoil），比较它们的优缺点，推荐最适合我们项目的方案",
  "context": "minimal",
  "maxTurns": 15
}

调试问题 ​

json
{
  "agentType": "debug-analyzer",
  "task": "调查为什么应用在生产环境中偶尔出现内存泄漏。分析日志、代码和配置，找出根本原因并提供解决方案",
  "context": "full",
  "maxTurns": 20,
  "priority": "high"
}

返回结果 ​

工具返回一个包含以下字段的对象：

  • llmContent: 子代理的执行结果
  • returnDisplay: 用户友好的显示信息
  • summary: 操作摘要
  • artifacts: 生成的文档或文件（如果有）

上下文级别说明 ​

Minimal（最小） ​

  • 仅共享任务描述
  • 适用于独立任务
  • 最快的执行速度
  • 最少的资源使用

Partial（部分） ​

  • 共享相关的上下文信息
  • 平衡性能和上下文理解
  • 推荐用于大多数任务

Full（完整） ​

  • 共享完整的对话历史
  • 最佳的上下文理解
  • 适用于复杂任务
  • 使用更多资源

最佳实践 ​

  1. 选择合适的代理类型：

    • 根据任务性质选择最合适的代理
    • 不要用 SpecFlow 做架构分析
    • 不要用 Architect 做代码实现

  2. 清晰的任务描述：

    • 详细说明期望的结果
    • 提供必要的上下文
    • 指定约束条件

  3. 合理设置参数：

    • 简单任务使用较少的 maxTurns
    • 复杂任务增加 maxTurns 和 timeout
    • 紧急任务使用 high priority

  4. 上下文管理：

    • 独立任务使用 minimal
    • 需要理解项目的任务使用 partial
    • 需要完整背景的任务使用 full

  5. 监控和调整：

    • 检查子代理的输出
    • 根据需要调整参数
    • 必要时重新运行

工作流示例 ​

场景 1：新项目开发 ​

1. Architect: 分析现有代码库，创建架构文档
2. Researcher: 研究需要的技术栈和最佳实践
3. SpecFlow: 实现核心功能
4. Refactor: 优化和重构代码
5. Debug Analyzer: 调查和修复问题

场景 2：大规模重构 ​

1. Architect: 更新架构文档，标记需要重构的部分
2. Refactor: 分批次重构代码
3. SpecFlow: 更新测试和文档
4. Debug Analyzer: 验证重构后的稳定性

场景 3：问题排查 ​

1. Debug Analyzer: 分析问题，生成调试报告
2. Researcher: 研究相关解决方案
3. SpecFlow: 实现修复
4. Debug Analyzer: 验证修复效果

性能考虑 ​

  1. 资源使用：

    • 每个子代理消耗独立的资源
    • 高优先级代理获得更多资源
    • 注意并发代理数量

  2. 执行时间：

    • 简单任务：5-10 分钟
    • 中等任务：10-20 分钟
    • 复杂任务：20-30 分钟

  3. 成本优化：

    • 使用最小必要的上下文
    • 设置合理的 maxTurns
    • 避免不必要的高优先级

错误处理 ​

可能的错误情况：

  1. 参数错误：

    • 无效的 agentType
    • 空的 task
    • 超出范围的 maxTurns 或 timeout

  2. 执行错误：

    • 超时
    • 资源不足
    • 子代理失败

  3. 上下文错误：

    • 上下文过大
    • 上下文格式错误

限制和注意事项 ​

  1. 不是万能的：

    • 子代理有其专长领域
    • 不要期望单个代理完成所有事情

  2. 需要监督：

    • 检查子代理的输出
    • 验证生成的代码和文档
    • 必要时进行调整

  3. 资源限制：

    • 注意并发代理数量
    • 监控资源使用
    • 避免创建过多代理

  4. 上下文限制：

    • 上下文大小有限制
    • 过大的上下文可能导致性能问题

相关工具 ​

  • read_file: 子代理常用的文件读取工具
  • write_file: 子代理常用的文件写入工具
  • search_file_content: 子代理常用的搜索工具
  • run_shell_command: 某些代理可能使用的命令执行工具

总结 ​

agent_tool 是一个强大的工具，允许你将复杂任务委托给专门的子代理。通过选择合适的代理类型、提供清晰的任务描述和合理的参数设置，你可以高效地完成各种复杂的开发任务。

记住：子代理是你的助手，不是替代品。始终监督它们的工作，验证输出，并根据需要进行调整。

Released under the MIT License.

Copyright © 2024-present GAIR-NLP