커스텀 에이전트

SessionConfig의 customAgents로 용도별 서브에이전트를 정의하는 방법을 설명합니다.

​

커스텀 에이전트

커스텀 에이전트를 정의하면 용도별로 역할을 나눈 서브에이전트 구성을 만들 수 있습니다. Laravel 버전에서는 SessionConfig의 customAgents를 사용해 설정합니다.

여러 서브에이전트를 병렬로 실행하는 오케스트레이션에 대해서는 Fleet Mode를 참고하세요.

​

기본 사용법

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

배열 형식으로도 동일하게 지정할 수 있습니다.

Copilot::run(
    prompt: 'README를 개선해줘',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => '문서 작성을 담당한다',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);

​

설정 항목

프로퍼티	타입	필수	설명
name	string	✅	에이전트의 식별자
displayName	string		표시명
description	string		런타임이 위임처를 선택할 때의 설명
tools	?array		사용 가능한 도구. null / 생략 시 모두 사용 가능
prompt	string	✅	에이전트 전용 시스템 프롬프트
mcpServers	array		이 에이전트 전용 MCP 서버 설정
infer	bool		자동 선택 대상으로 할지(기본값: true)
skills	array		시작 시에 로드할 스킬 이름 리스트

description은 구체적으로 쓸수록 자동 선택의 정확도가 올라갑니다.

​

세션 시작 시 특정 에이전트 선택

agent를 지정하면 최초 턴부터 특정 커스텀 에이전트를 활성화할 수 있습니다.

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

​

자동 선택 비활성화(infer: false)

위험도가 높은 조작을 수행하는 에이전트는, 자동 선택을 비활성화하고 명시적으로 사용하는 운영이 안전합니다.

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'dangerous-cleanup',
            'description' => '불필요한 파일을 삭제한다',
            'tools' => ['bash', 'edit', 'view'],
            'prompt' => 'Remove dead code and unused files carefully.',
            'infer' => false,
        ],
    ],
);

​

기본 에이전트에서 도구 숨기기

defaultAgent.excludedTools를 사용하면 메인 에이전트에서만 특정 도구를 숨길 수 있습니다. 해당 도구를 사용할 수 있는 커스텀 에이전트로 위임하기 쉬워집니다.

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

​

서브에이전트 이벤트 모니터링

서브에이전트 실행 중에는 subagent.* 이벤트가 흐릅니다. onEvent 또는 $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: '이 저장소의 인증 구현을 조사해줘');
});

​

베스트 프랙티스

• researcher(읽기 중심)와 editor(변경 담당)를 분리한다
• tools는 필요 최소한으로 하여 권한을 좁힌다
• description을 구체적으로 작성해 자동 위임 정확도를 높인다
• subagent.failed를 잡아 재시도나 폴백 전략을 준비한다

​

참고

• SessionConfig
• SessionEvent
• Fleet Mode
• MCP
• Tools