自定义代理
定义自定义代理后,可以创建按用途划分角色的子代理结构。 Laravel 版通过SessionConfig 的 customAgents 进行配置。
关于并行运行多个子代理的编排,请参考 Fleet Mode。
基本使用方式
配置项
description 写得越具体,自动选择的精度就越高。
按代理配置的声明式钩子
在自定义代理的hooks 中,可以以事件名为键、以声明式动作数组为值进行指定。
这些动作会随对应代理的定义一起传递给 CLI,并且仅在该代理中生效。
适用于只想限制特定代理的工具执行等场景。
customAgents[*].hooks 是传递给 CLI 的声明式动作。
请按照 Copilot CLI 接受的格式指定动作内容。
SessionConfig顶层的hooks是注册 PHP 回调的另一项功能,作用于整个会话。详情请参考 会话钩子。.github/hooks/中基于文件的钩子加载由enableFileHooks单独控制。
在会话启动时选择特定代理
指定agent 后,从第一轮开始就可以启用特定的自定义代理。
禁用自动选择(infer: false)
对于会执行高风险操作的代理,禁用自动选择并显式使用,运行起来会更安全。
从默认代理隐藏工具
使用defaultAgent.excludedTools 可以只对主代理隐藏特定工具。
这样便于委派给可以使用该工具的自定义代理。
监听子代理事件
子代理执行期间会流出subagent.* 事件。
可以通过 onEvent 或 $session->on() 来监听。
最佳实践
- 将
researcher(以读取为主)和editor(负责变更)分开 tools保持必要最小限度,收紧权限description写得具体一些以提升自动委派精度- 捕捉
subagent.failed以准备重试或回退策略