跳转到主要内容

自定义代理

定义自定义代理后,可以创建按用途划分角色的子代理结构。 Laravel 版通过 SessionConfigcustomAgents 进行配置。 关于并行运行多个子代理的编排,请参考 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.',
            ],
        ],
    ],
);

配置项

属性类型必需说明
namestring代理的标识符
displayNamestring显示名称
descriptionstring运行时选择委派对象时使用的描述
tools?array可用工具。null / 省略时全部可用
promptstring代理专用的系统 prompt
mcpServersarray该代理专用的 MCP 服务器配置
inferbool是否加入自动选择对象(默认: true
skillsarray启动时加载的技能名称列表
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 以准备重试或回退策略

参考

最后修改于 2026年7月13日