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.

Basic usage

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.

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
`hooks`	`array<string, array<array<string, mixed>>>`		Declarative hook actions that apply only within this agent

Write concrete description values to improve auto-selection accuracy.

Per-agent declarative hooks

In a custom agent’s hooks, you can specify event names as keys and arrays of declarative actions as values. The actions are passed to the CLI together with that agent’s definition and apply only to that agent. Use this when, for example, you want to restrict tool execution for a specific agent only.

use Revolution\Copilot\Types\SessionConfig;

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

customAgents[*].hooks are declarative actions passed to the CLI. Specify the actions in the format accepted by Copilot CLI.

The top-level hooks in SessionConfig is a separate feature that registers PHP callbacks and applies to the whole session. See Session hooks for details.
Loading file-based hooks from .github/hooks/ is controlled separately with enableFileHooks.

Start a session with a specific agent

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

Disable auto-selection with `infer: false`

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

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

$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().

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.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Custom agents

Custom agents

Basic usage

Configuration fields

Per-agent declarative hooks

Start a session with a specific agent

Disable auto-selection with `infer: false`

Hide tools from the default agent

Observe sub-agent events

Best practices

​Custom agents

​Basic usage

​Configuration fields

​Per-agent declarative hooks

​Start a session with a specific agent

​Disable auto-selection with infer: false

​Hide tools from the default agent

​Observe sub-agent events

​Best practices

​Related docs

Custom agents

Basic usage

Configuration fields

Per-agent declarative hooks

Start a session with a specific agent

Disable auto-selection with `infer: false`

Hide tools from the default agent

Observe sub-agent events

Best practices

Related docs