Agentes personalizados

Al definir agentes personalizados puedes crear configuraciones de subagentes que se reparten roles según el caso de uso.
En la versión Laravel se configuran mediante customAgents de SessionConfig. Para la orquestación que ejecuta varios subagentes en paralelo, consulta Fleet Mode.

Uso básico

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.',
        ],
    ],
));

También puedes indicarlo como array:

Copilot::run(
    prompt: 'READMEを改善して',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => 'ドキュメント執筆を担当する',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);

Opciones de configuración

Propiedad	Tipo	Requerida	Descripción
`name`	`string`	✅	Identificador del agente
`displayName`	`string`		Nombre a mostrar
`description`	`string`		Descripción que el runtime usa para elegir a quién delegar
`tools`	`?array`		Herramientas disponibles. Con `null` o si se omite, se pueden usar todas
`prompt`	`string`	✅	System prompt específico del agente
`mcpServers`	`array`		Configuración de servidores MCP específica de este agente
`infer`	`bool`		Si es objeto de selección automática (por defecto: `true`)
`skills`	`array`		Lista de nombres de skills que se cargan al iniciar

Cuanto más concreta escribas description, mayor será la precisión de la selección automática.

Elegir un agente concreto al iniciar la sesión

Si indicas agent, puedes habilitar un agente personalizado concreto desde el primer turn.

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',
);

Desactivar la selección automática (`infer: false`)

Para los agentes que realizan operaciones de alto riesgo es más seguro desactivar la selección automática y usarlos de forma explícita.

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'dangerous-cleanup',
            'description' => '不要ファイルを削除する',
            'tools' => ['bash', 'edit', 'view'],
            'prompt' => 'Remove dead code and unused files carefully.',
            'infer' => false,
        ],
    ],
);

Ocultar herramientas al agente por defecto

Con defaultAgent.excludedTools puedes ocultar herramientas concretas solo al agente principal.
Así resulta más fácil delegar en un agente personalizado que sí pueda usarlas.

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

Monitorizar eventos de subagentes

Mientras se ejecuta un subagente se emiten eventos subagent.*.
Puedes monitorizarlos con onEvent o con $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: 'このリポジトリの認証実装を調べて');
});

Buenas prácticas

Separa researcher (centrado en lectura) y editor (encargado de los cambios)
Deja tools en lo mínimo imprescindible y restringe permisos
Escribe description de forma concreta para mejorar la precisión de la delegación automática
Captura subagent.failed y prepara una estrategia de reintentos o fallback