> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义代理

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

## 自定义代理

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

关于并行运行多个子代理的编排，请参考 [Fleet Mode](/zh/packages/laravel-copilot-sdk/fleet-mode)。

## 基本使用方式

```php theme={null}
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.',
        ],
    ],
));
```

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

```php theme={null}
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` 后，从第一轮开始就可以启用特定的自定义代理。

```php theme={null}
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`）

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

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

## 从默认代理隐藏工具

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

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

## 监听子代理事件

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

```php theme={null}
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](/zh/packages/laravel-copilot-sdk/session-config)
* [SessionEvent](/zh/packages/laravel-copilot-sdk/session-event)
* [Fleet Mode](/zh/packages/laravel-copilot-sdk/fleet-mode)
* [MCP](/zh/packages/laravel-copilot-sdk/mcp)
* [Tools](/zh/packages/laravel-copilot-sdk/tools)


## Related topics

- [Laravel Boost](/zh/boost.md)
- [Fleet Mode](/zh/packages/laravel-copilot-sdk/fleet-mode.md)
- [Plugin Directories](/zh/packages/laravel-copilot-sdk/plugin-directories.md)
- [实现自定义认证 Guard](/zh/advanced/custom-auth-guard.md)
- [Laravel AI SDK](/zh/ai-sdk.md)