跳转到主要内容

自定义代理

定义自定义代理后,可以创建按用途划分角色的子代理结构。 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 以准备重试或回退策略

参考

最后修改于 2026年10月19日