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

# Agentes personalizados

> Explica cómo definir subagentes especializados por uso con customAgents de SessionConfig.

## 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](/es/packages/laravel-copilot-sdk/fleet-mode).

## Uso básico

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

También puedes indicarlo como array:

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

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

## 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.

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

## 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.

```php theme={null}
$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()`.

```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: 'このリポジトリの認証実装を調べて');
});
```

## 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

## Referencias

* [SessionConfig](/es/packages/laravel-copilot-sdk/session-config)
* [SessionEvent](/es/packages/laravel-copilot-sdk/session-event)
* [Fleet Mode](/es/packages/laravel-copilot-sdk/fleet-mode)
* [MCP](/es/packages/laravel-copilot-sdk/mcp)
* [Tools](/es/packages/laravel-copilot-sdk/tools)


## Related topics

- [Crear un agente personalizado de Boost](/es/advanced/boost-custom-agent.md)
- [Laravel Agent Detector — Paquete de detección de agentes de IA](/es/blog/agent-detector-introduction.md)
- [Laravel Boost](/es/boost.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/es/packages/laravel-boost-copilot-cli.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/es/packages/laravel-boost-phpstorm-copilot.md)