跳到主要内容

子代理（Subagents）

子代理是 Codely CLI 中的专业 AI 助手，用于处理特定类型的任务。它们允许您将工作委托给配置了任务特定提示、工具和行为的 AI 代理。

什么是子代理？​

子代理是独立的 AI 助手，具有以下特点：

  • 专业化任务 - 每个子代理都配置了针对特定类型工作的专注系统提示
  • 独立上下文 - 它们维护自己的对话历史，与主对话分开
  • 受控工具访问 - 您可以配置每个子代理可以访问哪些工具
  • 自主工作 - 一旦获得任务，它们会独立工作直到完成或失败
  • 详细反馈 - 您可以实时查看它们的进度、工具使用情况和执行统计

子代理系统通过将复杂任务分解并由专业代理处理，显著提高了工作效率和输出质量。

主要优势​

  • 任务专业化 - 创建针对特定工作流程优化的代理（测试、文档、重构等）
  • 上下文隔离 - 将专业工作与主对话分开
  • 可重用性 - 在项目和会话之间保存和重用代理配置
  • 受控访问 - 限制每个代理可以使用的工具，以提高安全性和专注度
  • 进度可见性 - 通过实时进度更新监控代理执行情况

子代理的工作原理​

  1. 配置 - 创建定义行为、工具和系统提示的子代理配置
  2. 委托 - 主 AI 可以自动将任务委托给适当的子代理
  3. 执行 - 子代理独立工作，使用其配置的工具完成任务
  4. 结果 - 将结果和执行摘要返回到主对话

快速开始​

查看可用代理​

列出所有可用的子代理：

/agents list

查看代理详情​

查看特定代理的详细信息：

/agents info <代理名称>

重新加载配置​

修改代理配置后，重新加载以应用更改：

/agents reload

使用子代理​

最简单的方式是直接告诉主 AI 您需要什么，它会自动选择合适的子代理：

请为认证模块编写全面的测试

主 AI 会自动识别这是一个测试任务，并委托给测试专家子代理。

您也可以明确指定使用特定的子代理：

让 testing-expert 子代理为支付模块创建单元测试

创建自定义子代理​

存储位置​

子代理配置文件存储在以下位置：

  • 项目级：.codely-cli/agents/（优先级更高）
  • 用户级：~/.codely-cli/agents/（后备）

这允许您拥有项目特定的代理和个人代理，适用于所有项目。

⚠️ 重要注意事项​

1. task 是保留字段（且必须提供）​

task 是系统保留字段：调用子代理时用于传递"要完成的任务"。在自定义 agent 的 input_schema 里：

  • 必须包含 task = "string"（必填，不能写成可选，也不能改名）
  • 不能定义 agent_name（该字段由 delegate_to_agent 工具保留，用于选择要运行的 agent）

注意

  • 旧版实现以 query="${task}" 提供，新版可以省略，codely会自动注入

❌ 错误示例：

[validation]
input_schema = {
  task = "string?",  # 错误！task 必须是必填 string
  agent_name = "string" # 错误！agent_name 是保留字段
}

✅ 正确示例：

[validation]
input_schema = {
  task = "string",          # 必填：要完成的任务
  target = "string",
  description = "string?"
}

必须正确配置task字段，这是子代理正确运行的关键。

2. CODELY TOML 格式是推荐方式​

**推荐使用 CODELY TOML 格式（.toml）**创建新的子代理配置。

3. 其他格式仅做兼容，不推荐直接创建​

为了兼容其他工具，Codely CLI 也支持以下格式，但不推荐直接使用这些格式创建新的子代理：

  • Gemini TOML 格式（**.toml**）：兼容 Gemini 的配置格式
  • Claude YAML Frontmatter 格式（**.md**）：兼容 Claude 的配置格式

这些格式仅用于从其他工具迁移现有配置，创建新的子代理请使用推荐的 Legacy TOML 格式。

推荐配置格式：Legacy TOML​

description = "代理功能的简要描述"

[agent]
name = "planner"
system_prompt = """
详细系统提示，定义代理的行为、能力和方法。
对动态输入替换使用 `${variable_name}` 占位符（仅 TOML 格式支持；YAML frontmatter 格式不会做插值）。
"""
query = "\$\{task\}"

# 可选模型配置
[agent.model_config]
model = ""  # 空字符串使用默认模型
temp = 0.1
top_p = 0.95

[agent.run_config]
# 可选运行配置设置

[agent.tools]
allowed_tools = ["tool1", "tool2", "tool3"]

[validation]
input_schema = {
  required_param = "string",
  optional_param = "string?",
  array_param = "array?"
}

[example]
inputs = { required_param = "example_value", optional_param = "optional_value" }
description = "此示例演示内容的简要描述"

配置字段说明​

基本信息​

  • name：代理的唯一标识符（内部使用）
  • description：代理用途的简明摘要

提示配置​

  • system_prompt：详细提示，定义代理行为、专业知识和方法

模型配置（可选）​

  • model：要使用的模型名称（空字符串使用默认值，和当前一致）
  • temp：温度设置（0.0-1.0，较低值=更确定性）
  • top_p：Top-p 采样参数

工具配置​

  • tools / allowed_tools：指定代理可以使用的工具列表，默认空全部允许使用，否则只允许给定工具

输入验证​

  • input_schema：定义期望的输入参数及其类型

示例​

  • example：提供文档和测试的使用示例

可用工具​

自定义代理可以访问以下工具：

文件系统工具​

  • read_file：读取文件内容
  • write_file：将内容写入文件
  • read_many_files：一次读取多个文件
  • list_directory：列出目录内容
  • glob：查找匹配模式的文件
  • search_file_content：在文件内容中搜索

分析工具​

  • sequential_thinking：逐步推理
  • analyze_multimedia：分析图像、音频、视频

系统工具​

  • run_shell_command：执行 shell 命令

Web 工具​

  • web_fetch：获取并处理 Web 内容
  • web_search：搜索网络信息

内存工具​

  • save_memory：将信息保存到内存

任务管理​

  • todo_write：创建和管理任务列表

最佳实践​

设计原则​

单一职责原则​

每个子代理应该有清晰、专注的目的。

✅ 好的：

name = "testing-expert"
description = "编写全面的单元测试和集成测试"

❌ 避免：

name = "general-helper"
description = "帮助测试、文档、代码审查和部署"

原因：专注的代理产生更好的结果，更容易维护。

清晰的专业化​

定义特定的专业知识领域，而不是广泛的能力。

✅ 好的：

name = "react-performance-optimizer"
description = "使用分析和最佳实践优化 React 应用程序的性能"

❌ 避免：

name = "frontend-developer"
description = "处理前端开发任务"

原因：特定的专业知识导致更有针对性和有效的帮助。

可操作的描述​

编写清楚指示何时使用代理的描述。

✅ 好的：

description = "审查安全漏洞、性能问题和可维护性问题的代码"

❌ 避免：

description = "一个有用的代码审查者"

原因：清晰的描述有助于主 AI 为每个任务选择正确的代理。

配置最佳实践​

系统提示指南​

具体说明专业知识：

您是 Python 测试专家，专业知识包括：

- pytest 框架和 fixtures
- 模拟对象和依赖注入
- 测试驱动开发实践
- 使用 pytest-benchmark 进行性能测试

包括分步方法：

对于每个测试任务：

1. 分析代码结构和依赖关系
2. 识别关键功能和边缘情况
3. 创建具有清晰命名的全面测试套件
4. 包括设置/拆卸和适当的断言
5. 添加解释复杂测试场景的注释

指定输出标准：

始终遵循这些标准：

- 使用解释场景的描述性测试名称
- 包括正面和负面测试用例
- 为复杂的测试函数添加文档字符串
- 确保测试是独立的，可以按任何顺序运行

安全考虑​

  • 工具限制：子代理只能访问其配置的工具
  • 沙箱：所有工具执行遵循与直接工具使用相同的安全模型
  • 审计跟踪：所有子代理操作都被记录并实时可见
  • 访问控制：项目和用户级别的分离提供适当的边界
  • 敏感信息：避免在代理配置中包含密钥或凭据
  • 生产环境：考虑为生产和开发环境使用单独的代理

常见问题​

如何启用子代理功能？​

在 Codely CLI 中，agents（子代理）系统默认启用。如果您关闭过，可以通过以下方式启用/禁用：

  • 命令行：codely --agents=true（或移除 --no-agents）；禁用则 codely --agents=false
  • 配置文件：在 .codely-cli/settings.json（工作区）或 ~/.codely-cli/settings.json（用户）中设置：
{
  "agents": { "enabled": true }
}

另外，内置 agents 默认不加载（agents.enableBuiltin=false）。如需加载内置 agents：

{
  "agents": { "enableBuiltin": true }
}

子代理之间可以互相调用吗？​

不可以。为了防止递归调用和无限循环，子代理不能调用 delegate_to_agent 工具。

如何调试子代理？​

用调试模式运行 CLI 以查看更详细日志，例如：codely --debug（也可用 DEBUG=1 codely）。

子代理执行超时怎么办？​

您可以在代理配置中设置超时时间（以分钟为单位）：

[agent.run_config]
max_time_minutes = 30  # 30分钟后超时

如何限制子代理的最大对话轮数？​

在代理配置中设置最大轮数：

[agent.run_config]
max_turns = 10  # 最多10轮对话

高级用法​

并行执行多个子代理​

某些模型可以并行执行工具，主 AI 可以同时委托多个子代理来并行处理不同的任务，提高效率。

但必须注意，每个代理的改动不能有重叠，最好有目录隔离。

例如：

并行运行测试和文档生成，测试所有 packages 的 subpkg
提示

并行执行可以显著缩短项目开发时间，特别是对于大型项目。

使用特定模型​

您可以为特定的子代理配置不同的模型：

[agent.model_config]
model = "gpt-4"  # 使用 GPT-4 而不是默认模型