Cloud Sessions

로컬 Copilot CLI가 아닌 GitHub 호스트 환경에서 세션을 실행하는 Cloud Sessions의 사용법을 설명합니다.

​

Cloud Sessions

Cloud Sessions는 로컬 Copilot CLI 프로세스가 아니라 GitHub 측 호스트 환경에서 세션을 실행하는 기능입니다. Mission Control에서 태스크가 예약되고, 클라우드 측의 copilot-agent가 접속하여 처리를 진행합니다.

일반 Remote Sessions는 “로컬에서 실행되는 세션을 GitHub Web/모바일에서 볼 수 있도록 하는” 기능입니다. 실행 장소 자체를 GitHub 호스트 환경으로 하려면 Cloud Sessions를 사용합니다.

​

사전 조건

• 사용자가 Cloud Agent를 이용할 수 있는 Copilot 권한을 가지고 있음
• GitHub 토큰 또는 로그인된 Copilot CLI 사용자로 인증할 수 있음
• 가능하다면 GitHub 저장소 정보를 연결
• 조직 정책에서 클라우드 실행과 원격 열람이 허용되어 있음

​

기본 사용법

SessionConfig의 cloud에 CloudSessionOptions를 지정합니다. 저장소 정보는 SDK 타입상 임의이지만, Mission Control과 클라우드 에이전트에 컨텍스트를 전달하기 위해 지정하는 것을 권장합니다.

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\CloudSessionOptions;
use Revolution\Copilot\Types\CloudSessionRepository;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session): void {
    $session->sendAndWait(prompt: 'README를 요약해줘');
}, config: new SessionConfig(
    onPermissionRequest: PermissionHandler::approveSafety(),
    cloud: new CloudSessionOptions(
        repository: new CloudSessionRepository(
            owner: 'myorg',
            name: 'myrepo',
            branch: 'main',
        ),
    ),
));

배열로도 지정할 수 있습니다.

Copilot::run(
    prompt: '이 저장소의 테스트 방침을 확인해줘',
    config: [
        'cloud' => [
            'repository' => [
                'owner' => 'myorg',
                'name' => 'myrepo',
                'branch' => 'main',
            ],
        ],
    ],
);

​

최초 프롬프트를 보내는 타이밍

Cloud Session은 2단계로 초기화됩니다. session.create는 Mission Control에서 태스크가 예약된 시점에 리턴되지만, 클라우드 측 copilot-agent가 접속해 session.start를 발행하기까지 약간의 시간이 있습니다.

최초 프롬프트를 확실하게 전달하려면 먼저 이벤트를 구독하고, producer가 copilot-agent의 session.start를 확인한 후에 전송하세요.

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\CloudSessionOptions;
use Revolution\Copilot\Types\CloudSessionRepository;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    streaming: true,
    onPermissionRequest: PermissionHandler::approveSafety(),
    cloud: new CloudSessionOptions(
        repository: new CloudSessionRepository(owner: 'myorg', name: 'myrepo'),
    ),
);

Copilot::start(function (CopilotSession $session): void {
    $cloudAgentStarted = false;

    foreach ($session->stream(timeout: 30.0) as $event) {
        if (
            $event->is(SessionEventType::SESSION_START)
            && $event->data('producer') === 'copilot-agent'
        ) {
            $cloudAgentStarted = true;
            break;
        }
    }

    if (! $cloudAgentStarted) {
        throw new RuntimeException('Cloud session did not become ready.');
    }

    $session->sendAndWait(prompt: 'README를 요약해줘');
}, config: $config);

실제 앱에서는 큐나 비동기 처리 측에서 session.start 확인 후에 프롬프트를 보내는 구성으로 하면 다루기 쉽습니다.

​

Remote Sessions와의 차이

기능	실행 장소	주요 용도
Remote Sessions	로컬 또는 자체 서버	Web/모바일에서 기존 세션을 열람, 조작
Cloud Sessions	GitHub 호스트 환경	사용자 단말이나 자체 서버에서 Copilot CLI를 실행하지 않고 처리

​

주의점

• Cloud Sessions는 권한과 조직 정책의 영향을 받습니다
• streaming: true로 하면 assistant.message_delta 등의 실시간 이벤트를 받을 수 있습니다
• 권한 요청의 처리는 일반 세션과 동일합니다. Laravel 버전 Facade 경유로는 기본적으로 deny-all이므로 필요에 따라 PermissionHandler::approveSafety() 등을 지정하세요

​

참고

• Remote Sessions
• SessionConfig
• 스트리밍 이벤트

최신 정보는 GitHub 저장소를 참고하세요.