6.2 --agents - 動態定義自定義子代理

--agents 標誌允許您透過 JSON 動態定義自定義子代理，無需修改配置檔案。這為臨時或特定任務提供了靈活的代理配置方式。

标志语法

bash


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

功能描述

--agents 標誌接受定義一個或多個自定義子代理的 JSON 物件。每個子代理需要一個唯一的名稱（作為鍵）和一個具有以下欄位的定義物件：

欄位	必需	描述

description| 是| 何時應呼叫子代理的自然語言描述 prompt| 是| 指導子代理行為的系統提示 tools| 否| 子代理可以使用的特定工具陣列。如果省略，繼承所有工具 model| 否| 要使用的模型別名：sonnet、opus 或 haiku。如果省略，使用預設子代理模型

使用示例

基本用法

bash


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

定義一個簡單的程式碼審查子代理。

多个子代理

bash


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."
  }
}'

定義多個子代理，每個有不同的職責和配置。

指定工具

bash


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

定義一個只能使用特定工具的子代理。

指定模型

bash


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

定義一個使用特定模型的子代理。

使用场景

1. 代码审查

bash


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

使用專門的程式碼審查子代理。

2. 调试

bash


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

使用專門的除錯子代理。

3. 测试

bash


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

使用專門的測試子代理。

4. 文档生成

bash


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. 文件記錄 ：記錄每個子代理的用途和配置

與配置檔案的對比

特性	--agents 標誌	配置檔案

永續性| 臨時（僅當前會話）| 持久 靈活性| 高（動態定義）| 中（需要修改檔案） 適用場景| 臨時任務、實驗| 長期使用、團隊共享 複雜度| 簡單（單次定義）| 複雜（需要編輯檔案）

## 常见问题

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

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

### Q: 子代理可以嵌套吗？

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

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

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

### Q: 如何调试子代理？

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

## 相关资源

  * 子代理文档：详细的子代理配置和使用指南，请参阅相关章节
  * `--model`：设置会话模型
  * `--verbose`：启用详细日志记录
## 实际应用示例

### 项目特定子代理

    bash


    #!/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 设计"

### 临时调试会话

    bash


    #!/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 "调试这个生产问题"