自定义代理

说明如何使用 SessionConfig 的 customAgents 定义按用途划分的子代理。

​

自定义代理

定义自定义代理后，可以创建按用途划分角色的子代理结构。 Laravel 版通过 SessionConfig 的 customAgents 进行配置。

关于并行运行多个子代理的编排，请参考 Fleet Mode。

​

基本使用方式

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: '调查认证相关的设计并提出改进建议');

    dump($response->content());
}, config: new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'displayName' => 'Research Agent',
            'description' => '调查代码并整理要点',
            'tools' => ['grep', 'glob', 'view'],
            'prompt' => 'You are a research assistant. Analyze code and summarize findings.',
        ],
        [
            'name' => 'editor',
            'displayName' => 'Editor Agent',
            'description' => '进行必要最小限度的代码变更',
            'tools' => ['view', 'edit', 'bash'],
            'prompt' => 'You are a code editor. Make minimal, surgical changes only.',
        ],
    ],
));

数组形式也可以同样指定。

Copilot::run(
    prompt: '改进 README',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => '负责编写文档',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);

​

配置项

属性	类型	必需	说明
name	string	✅	代理的标识符
displayName	string		显示名称
description	string		运行时选择委派对象时使用的描述
tools	?array		可用工具。null / 省略时全部可用
prompt	string	✅	代理专用的系统 prompt
mcpServers	array		该代理专用的 MCP 服务器配置
infer	bool		是否加入自动选择对象（默认: true）
skills	array		启动时加载的技能名称列表

description 写得越具体，自动选择的精度就越高。

​

在会话启动时选择特定代理

指定 agent 后，从第一轮开始就可以启用特定的自定义代理。

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'prompt' => 'You analyze code and answer questions.',
        ],
        [
            'name' => 'editor',
            'prompt' => 'You edit code with minimal changes.',
        ],
    ],
    agent: 'researcher',
);

​

禁用自动选择（infer: false）

对于会执行高风险操作的代理，禁用自动选择并显式使用，运行起来会更安全。

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'dangerous-cleanup',
            'description' => '删除不需要的文件',
            'tools' => ['bash', 'edit', 'view'],
            'prompt' => 'Remove dead code and unused files carefully.',
            'infer' => false,
        ],
    ],
);

​

从默认代理隐藏工具

使用 defaultAgent.excludedTools 可以只对主代理隐藏特定工具。 这样便于委派给可以使用该工具的自定义代理。

$config = new SessionConfig(
    tools: [...],
    defaultAgent: [
        'excludedTools' => ['analyze-codebase'],
    ],
    customAgents: [
        [
            'name' => 'researcher',
            'tools' => ['analyze-codebase'],
            'prompt' => 'You perform deep codebase analysis.',
        ],
    ],
);

​

监听子代理事件

子代理执行期间会流出 subagent.* 事件。 可以通过 onEvent 或 $session->on() 来监听。

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session) {
    $session->on(function (SessionEvent $event): void {
        if ($event->is(SessionEventType::SUBAGENT_STARTED)) {
            info('Sub-agent started', $event->toArray());
        }

        if ($event->is(SessionEventType::SUBAGENT_COMPLETED)) {
            info('Sub-agent completed', $event->toArray());
        }

        if ($event->is(SessionEventType::SUBAGENT_FAILED)) {
            info('Sub-agent failed', $event->toArray());
        }
    });

    $session->sendAndWait(prompt: '调查这个仓库的认证实现');
});

​

最佳实践

• 将 researcher（以读取为主）和 editor（负责变更）分开
• tools 保持必要最小限度，收紧权限
• description 写得具体一些以提升自动委派精度
• 捕捉 subagent.failed 以准备重试或回退策略

​

参考

• SessionConfig
• SessionEvent
• Fleet Mode
• MCP
• Tools