Claude Code 中文教程网

外观

6.2 `--agents` - 动态定义自定义子代理

约 1181 字大约 4 分钟

--agents 标志允许您通过 JSON 动态定义自定义子代理，无需修改配置文件。这为临时或特定任务提供了灵活的代理配置方式。

标志语法

claude --agents '<json>' [其他选项]

功能描述

--agents 标志接受定义一个或多个自定义子代理的 JSON 对象。每个子代理需要一个唯一的名称（作为键）和一个具有以下字段的定义对象：

使用示例

基本用法

claude --agents '{
  "reviewer": {
    "description": "Reviews code",
    "prompt": "You are a code reviewer"
  }
}'

定义一个简单的代码审查子代理。

多个子代理

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

定义多个子代理，每个有不同的职责和配置。

指定工具

claude --agents '{
  "tester": {
    "description": "Runs and analyzes tests",
    "prompt": "You are a testing expert. Run tests and analyze failures.",
    "tools": ["Bash", "Read", "Grep"]
  }
}'

定义一个只能使用特定工具的子代理。

指定模型

claude --agents '{
  "analyzer": {
    "description": "Analyzes code structure",
    "prompt": "You are a code architecture expert.",
    "model": "opus"
  }
}'

定义一个使用特定模型的子代理。

使用场景

1. 代码审查

claude --agents '{
  "reviewer": {
    "description": "Reviews code for quality and security",
    "prompt": "You are a security-focused code reviewer."
  }
}' "审查这段代码"

使用专门的代码审查子代理。

2. 调试

claude --agents '{
  "debugger": {
    "description": "Debugs errors and failures",
    "prompt": "You are an expert debugger."
  }
}' "调试这个错误"

使用专门的调试子代理。

3. 测试

claude --agents '{
  "tester": {
    "description": "Runs and analyzes tests",
    "prompt": "You are a testing expert."
  }
}' "运行测试并分析结果"

使用专门的测试子代理。

4. 文档生成

claude --agents '{
  "documenter": {
    "description": "Generates documentation",
    "prompt": "You are a technical writer."
  }
}' "为这个 API 生成文档"

使用专门的文档生成子代理。

子代理的优势

1. 专业化

每个子代理可以专注于特定领域：

  • 代码审查
  • 调试
  • 测试
  • 文档生成

2. 灵活性

可以动态定义子代理，无需修改配置文件：

  • 临时任务
  • 特定项目
  • 实验性功能

3. 工具限制

可以限制子代理使用的工具：

  • 提高安全性
  • 减少成本
  • 优化性能

4. 模型选择

可以为每个子代理选择不同的模型：

  • 使用更强大的模型处理复杂任务
  • 使用更快的模型处理简单任务
  • 优化成本和性能

注意事项

  1. JSON 格式：确保 JSON 格式正确，使用单引号或转义双引号
  2. 唯一名称：每个子代理必须有唯一的名称
  3. 描述清晰：描述应该清晰明确，帮助 Claude 决定何时调用
  4. 提示有效：系统提示应该清晰具体，指导子代理的行为
  5. 工具兼容：指定的工具必须存在且可用
  6. 模型有效：指定的模型必须受支持

最佳实践

  1. 明确描述：子代理描述应该明确说明何时应该调用
  2. 具体提示：系统提示应该具体指导子代理的行为和风格
  3. 合理工具：只包含子代理实际需要的工具
  4. 合适模型：根据任务复杂度选择合适的模型
  5. 测试验证：定义子代理后，测试其行为是否符合预期
  6. 文档记录：记录每个子代理的用途和配置

与配置文件的对比

常见问题

Q: 可以定义多少个子代理？

A: 理论上没有限制，但过多的子代理可能影响性能和决策。

Q: 子代理可以嵌套吗？

A: 不可以，子代理不能调用其他子代理。

Q: 子代理的提示可以多长？

A: 提示长度有限制，建议保持简洁明确。

Q: 如何调试子代理？

A: 使用 --verbose 标志可以查看子代理的调用和执行详情。

相关资源

  • 子代理文档：详细的子代理配置和使用指南
  • --model：设置会话模型
  • --verbose：启用详细日志记录

实际应用示例

项目特定子代理

#!/bin/bash
# 为项目定义特定的子代理
claude --agents '{
  "api-reviewer": {
    "description": "Reviews API endpoints for REST best practices",
    "prompt": "You are an API design expert. Focus on REST principles, error handling, and documentation."
  },
  "database-expert": {
    "description": "Optimizes database queries and schema",
    "prompt": "You are a database performance expert. Focus on query optimization and indexing."
  }
}' "审查这个 API 设计"

临时调试会话

#!/bin/bash
# 创建临时调试会话
claude --agents '{
"debugger": {
"description": "Debugs the current issue",
"prompt": "You are a debugging specialist. Analyze the error, identify the root cause, and provide a fix.",
"model": "opus"
}
}' --verbose "调试这个生产问题"
公众号
小红书