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
`hooks`	`array<string, array<array<string, mixed>>>`		Acciones de hook declarativas que solo tienen efecto dentro del agente

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

Hooks declarativos por agente

En hooks de un agente personalizado puedes indicar el nombre del evento como clave y un array de acciones declarativas como valor. Las acciones se pasan al CLI junto con la definición del agente correspondiente y solo tienen efecto en ese agente. Resulta útil, por ejemplo, cuando quieres restringir la ejecución de herramientas solo en un agente concreto.

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'restricted-agent',
            'prompt' => 'Review tool usage.',
            'hooks' => [
                'preToolUse' => [
                    ['permissionDecision' => 'deny'],
                ],
            ],
        ],
    ],
);

customAgents[*].hooks son acciones declarativas que se pasan al CLI. Indica el contenido de las acciones en el formato que acepta Copilot CLI.

hooks en el nivel superior de SessionConfig es una función distinta que registra callbacks de PHP y se aplica a toda la sesión. Para más detalles, consulta Hooks de sesión.
La carga de hooks basados en archivos de .github/hooks/ se controla por separado con enableFileHooks.

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

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds y RSS

Middleware

Agentes personalizados