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

# Custom agents

> Define task-specific sub-agents with SessionConfig customAgents in Laravel Copilot SDK.

## Custom agents

Custom agents let you split responsibilities by role and run sub-agents for specific tasks.
In Laravel, configure them with `SessionConfig` `customAgents`.

For orchestrating multiple sub-agents in parallel, see [Fleet Mode](/en/packages/laravel-copilot-sdk/fleet-mode).

## Basic usage

```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: 'Review the authentication design and propose improvements');

    dump($response->content());
}, config: new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'displayName' => 'Research Agent',
            'description' => 'Investigate the codebase and summarize findings',
            'tools' => ['grep', 'glob', 'view'],
            'prompt' => 'You are a research assistant. Analyze code and summarize findings.',
        ],
        [
            'name' => 'editor',
            'displayName' => 'Editor Agent',
            'description' => 'Make minimal code changes',
            'tools' => ['view', 'edit', 'bash'],
            'prompt' => 'You are a code editor. Make minimal, surgical changes only.',
        ],
    ],
));
```

You can also pass it as an array config.

```php theme={null}
Copilot::run(
    prompt: 'Improve the README',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => 'Write technical documentation',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);
```

## Configuration fields

| Property      | Type     | Required | Description                                             |
| ------------- | -------- | -------- | ------------------------------------------------------- |
| `name`        | `string` | ✅        | Agent identifier                                        |
| `displayName` | `string` |          | Display name                                            |
| `description` | `string` |          | Description used for delegation selection               |
| `tools`       | `?array` |          | Allowed tools. `null` or omitted means all tools        |
| `prompt`      | `string` | ✅        | Agent-specific system prompt                            |
| `mcpServers`  | `array`  |          | MCP server config for this agent                        |
| `infer`       | `bool`   |          | Whether the runtime can auto-select it (default `true`) |
| `skills`      | `array`  |          | Skill names to preload on startup                       |

> Write concrete `description` values to improve auto-selection accuracy.

## Start a session with a specific agent

Set `agent` to activate one custom agent from the first 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',
);
```

## Disable auto-selection with `infer: false`

For high-risk agents, disable automatic selection and require explicit use.

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

## Hide tools from the default agent

Use `defaultAgent.excludedTools` to hide specific tools from only the default agent.
This makes delegation to a custom agent easier.

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

## Observe sub-agent events

`subagent.*` events are emitted while sub-agents run.
You can observe them with `onEvent` or `$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: 'Inspect the auth implementation in this repository');
});
```

## Best practices

* Separate `researcher` (read-heavy) and `editor` (change-heavy).
* Keep `tools` minimal and least-privileged.
* Make `description` concrete to improve delegation.
* Handle `subagent.failed` with retry or fallback strategy.

## Related docs

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


## Related topics

- [Creating a Custom Agent for Boost](/en/advanced/boost-custom-agent.md)
- [Laravel Agent Detector — AI agent detection package](/en/blog/agent-detector-introduction.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/en/packages/laravel-boost-copilot-cli.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/en/packages/laravel-boost-phpstorm-copilot.md)
- [Skills](/en/packages/laravel-copilot-sdk/skills.md)