AHP Host

Agent Host Protocol(AHP)을 사용하면 Copilot 런타임이 관리하는 리스너를 시작하고, WebSocket 또는 GitHub의 Mission Control을 통해 원격 클라이언트를 받아들일 수 있습니다. AHP 호스트는 해당 Client 연결이 소유합니다. Client::stop()이나 호스트의 dispose()로 리스너를 중지해도 호스트가 사용한 세션은 삭제되지 않습니다.

호스트 시작

localServer 또는 githubEnvironment 중 적어도 하나를 전달합니다. 인증 모드도 필수입니다. 익명 접근을 허용하려면 none을 명시적으로 전달해야 합니다.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\AhpHostAuthentication;

$client = Copilot::client();

$host = $client->startAhpHost(
    authentication: AhpHostAuthentication::github(),
    localServer: [],
    allowCreatingNewSessions: true,
    workspace: '/workspace/project',
);

echo $host->url;

localServer: []는 루프백 주소와 비어 있는 포트를 사용합니다. githubEnvironment에는 github 인증이 필요합니다. 호스트가 반환하는 token은 연결용 시크릿으로 취급하세요. workspace는 AHP 호스트가 사용하는 작업 디렉터리입니다. Copilot 런타임은 이 경로를 런타임이 실행되는 호스트에서 해석하므로, Laravel 애플리케이션 내부의 경로와 다를 수 있습니다. 생략하면 SDK는 RPC 호출에 workspace를 포함하지 않으며, 런타임은 기존 동작을 유지합니다.

인증 모드

AhpHostAuthentication::github()는 GitHub 계정으로 인증합니다. githubEnvironment와 함께 사용할 수 있습니다.
AhpHostAuthentication::none()은 인증을 명시적으로 비활성화합니다.
AhpHostAuthentication::custom()은 애플리케이션 자체 로직으로 입장 토큰(admission token)을 검증합니다. 고정된 소유자 ID와 검증 콜백이 필요합니다.

커스텀 인증 콜백은 복호화된 입장 토큰을 담은 HostValidateAuthenticationRequest와 취소를 알리는 CancellationToken을 받습니다. 성공 시에는 ID와 RFC3339 형식의 미래 시각 expiresAt을 반환합니다. 토큰을 거부하려면 null을 반환합니다. ID는 requireIdentity와 정확히 일치해야 합니다.

use Revolution\Copilot\Types\AhpHostAuthentication;
use Revolution\Copilot\Types\Rpc\HostAuthenticationResult;
use Revolution\Copilot\Types\Rpc\HostValidateAuthenticationRequest;
use Revolution\Copilot\Support\CancellationToken;

$authentication = AhpHostAuthentication::custom(
    requireIdentity: 'team-123',
    authenticate: function (
        HostValidateAuthenticationRequest $request,
        CancellationToken $signal,
    ): ?HostAuthenticationResult {
        if ($signal->isCancellationRequested()) {
            return null;
        }

        $identity = validateAdmissionToken($request->token);

        if ($identity !== 'team-123') {
            return null;
        }

        return new HostAuthenticationResult(
            identity: $identity,
            expiresAt: '2099-01-01T00:00:00Z',
        );
    },
);

$host = $client->startAhpHost(
    authentication: $authentication,
    localServer: [],
);

입장 토큰은 추론에 사용하는 GitHub 토큰이나 프로바이더 토큰과는 별개의 자격 증명입니다. 로그나 세션 설정에 저장하지 마세요. 호스트가 host.authenticationCancelled를 받거나 종료되면 콜백의 signal이 취소됩니다. 콜백에서 외부 서비스를 호출하는 경우 onCancellationRequested()로 중단 처리를 등록하세요.

세션 생성 정책

allowCreatingNewSessions는 원격 클라이언트가 새 세션을 생성하는 것에 대한 초기 정책을 설정합니다. 생략하면 원격 세션 생성이 거부됩니다. 이 정책은 소유 애플리케이션이 생성한 세션, 공개된 세션, 기존 연결에는 적용되지 않습니다. 호스트 실행 중에 정책을 변경하려면 호스트의 setSessionCreationPolicy()를 호출합니다. 새 정책은 변경이 확인된 이후에 도착한 요청에 적용됩니다. 이미 수락된 생성 요청은 완료될 수 있습니다. 연결된 클라이언트의 연결은 끊기지 않습니다.

$host->setSessionCreationPolicy(allowCreatingNewSessions: false);

RPC를 직접 사용하는 경우 $client->rpc()->host()->setSessionCreationPolicy()를 호출하고, hostId와 새 설정을 담은 HostSetSessionCreationPolicyRequest를 전달합니다.

애플리케이션 소유 세션

createSession과 resumeSession 콜백을 전달하면 AHP 호스트의 요청을 애플리케이션의 Client로 넘길 수 있습니다. 각 콜백은 런타임이 검증한 HostSessionAuthentication과 호스트가 제공한 config를 담은 HostMaterializeSessionRequest, 그리고 협조적 취소를 위한 CancellationToken을 받습니다. 같은 Client로 생성하거나 재개한 세션을 반환하세요.

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Support\CancellationToken;
use Revolution\Copilot\Types\Rpc\HostMaterializeSessionRequest;
use Revolution\Copilot\Support\PermissionHandler;

$host = $client->startAhpHost(
    authentication: $authentication,
    localServer: [],
    createSession: function (
        HostMaterializeSessionRequest $request,
        CancellationToken $signal,
    ) use ($client): CopilotSession {
        return $client->createSession([
            ...($request->config ?? []),
            'onPermissionRequest' => PermissionHandler::approveAll(),
        ]);
    },
    resumeSession: function (
        HostMaterializeSessionRequest $request,
        CancellationToken $signal,
    ) use ($client): CopilotSession {
        $sessionId = $request->config['sessionId'];

        return $client->resumeSession($sessionId, [
            'onPermissionRequest' => PermissionHandler::approveAll(),
        ]);
    },
    onSessionReleased: function (CopilotSession $session): void {
        // AHP 참여가 끝났을 때 애플리케이션 측 정리 처리
    },
);

onSessionReleased는 참여가 끝난 세션을 받습니다. SDK는 세션의 연결을 끊거나 파기하지 않습니다. HostMaterializeSessionRequest::$authentication은 클라이언트 입력이 아니라 호스트가 검증한 신뢰할 수 있는 ID입니다. 그래도 필요한 테넌트 또는 사용자 인가는 콜백 내에서 수행하세요.

세션 카탈로그와 종료

$host->publishSession('session-id');
$sessions = $host->listSessions();
$host->unpublishSession('session-id');
$host->dispose();

공개를 해제하면 세션이 AHP 카탈로그에서 제거됩니다. 로컬 이력을 삭제하거나 실행 중인 작업을 중지하지는 않습니다. dispose()는 리스너를 중지하지만 관련 세션은 삭제하지 않습니다.

GitHub Copilot

SDK

AI SDK

VOICEVOX

스타터 킷

피드·RSS

미들웨어

AHP Host

AHP Host

호스트 시작

인증 모드

세션 생성 정책

애플리케이션 소유 세션

세션 카탈로그와 종료

관련 문서

​AHP Host

​호스트 시작

​인증 모드

​세션 생성 정책

​애플리케이션 소유 세션

​세션 카탈로그와 종료

​관련 문서

AHP Host

호스트 시작

인증 모드

세션 생성 정책

애플리케이션 소유 세션

세션 카탈로그와 종료

관련 문서