AHP Host

L’Agent Host Protocol (AHP) ti permette di avviare un listener gestito dal runtime di Copilot e di accettare client remoti tramite WebSocket o Mission Control di GitHub. Un host AHP appartiene alla sua connessione Client. Fermare il listener con Client::stop() o con il dispose() dell’host non elimina le sessioni utilizzate dall’host.

Avvio di un host

Passa almeno uno tra localServer e githubEnvironment. È inoltre richiesta una modalità di autenticazione. Per consentire l’accesso anonimo, devi passare esplicitamente 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: [] utilizza un indirizzo di loopback e una porta libera. githubEnvironment richiede l’autenticazione github. Tratta il token restituito dall’host come un segreto di connessione. workspace è la directory di lavoro utilizzata dall’host AHP. Il runtime di Copilot risolve questo percorso sull’host in cui è in esecuzione il runtime, quindi può differire dal percorso all’interno della tua applicazione Laravel. Se lo ometti, l’SDK non include workspace nella chiamata RPC e il runtime mantiene il suo comportamento esistente.

Modalità di autenticazione

AhpHostAuthentication::github() esegue l’autenticazione con un account GitHub. Puoi combinarla con githubEnvironment.
AhpHostAuthentication::none() disabilita esplicitamente l’autenticazione.
AhpHostAuthentication::custom() convalida i token di ammissione con la logica della tua applicazione. Richiede un’identità del proprietario stabile e una callback di convalida.

La callback di autenticazione personalizzata riceve una HostValidateAuthenticationRequest contenente il token di ammissione decifrato e un CancellationToken che segnala l’annullamento. In caso di successo, restituisci l’identità e un expiresAt futuro in formato RFC3339. Per rifiutare il token, restituisci null. L’identità deve corrispondere esattamente a 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: [],
);

Il token di ammissione è una credenziale distinta dal token GitHub o dal token del provider utilizzato per l’inferenza. Non salvarlo nei log o nella configurazione della sessione. Il signal della callback viene annullato quando l’host riceve host.authenticationCancelled o viene arrestato. Se la callback chiama servizi esterni, registra la gestione dell’interruzione con onCancellationRequested().

Policy di creazione delle sessioni

allowCreatingNewSessions imposta la policy iniziale per la creazione di nuove sessioni da parte dei client remoti. Se omesso, la creazione di sessioni remote viene negata. La policy non si applica alle sessioni create dall’applicazione proprietaria, alle sessioni pubblicate o alle connessioni esistenti. Per modificare la policy mentre l’host è in esecuzione, chiama setSessionCreationPolicy() dell’host. La nuova policy si applica alle richieste che arrivano dopo la conferma della modifica. Le richieste di creazione già accettate possono essere completate. I client connessi non vengono disconnessi.

$host->setSessionCreationPolicy(allowCreatingNewSessions: false);

Se usi direttamente l’RPC, chiama $client->rpc()->host()->setSessionCreationPolicy() e passa una HostSetSessionCreationPolicyRequest con l’hostId e la nuova impostazione.

Sessioni gestite dall’applicazione

Passa le callback createSession e resumeSession per inoltrare le richieste dall’host AHP al Client della tua applicazione. Ogni callback riceve una HostMaterializeSessionRequest contenente la HostSessionAuthentication verificata dal runtime e la config fornita dall’host, oltre a un CancellationToken per l’annullamento cooperativo. Restituisci una sessione creata o ripresa con lo stesso 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 {
        // Pulizia lato applicazione al termine della partecipazione AHP
    },
);

onSessionReleased riceve la sessione la cui partecipazione è terminata. L’SDK non disconnette né distrugge la sessione. HostMaterializeSessionRequest::$authentication è un’identità attendibile verificata dall’host, non un input del client. Esegui comunque all’interno della callback qualsiasi autorizzazione per tenant o utente di cui hai bisogno.

Catalogo delle sessioni e arresto

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

Annullare la pubblicazione rimuove la sessione dal catalogo AHP. Non elimina la cronologia locale né interrompe il lavoro in corso. dispose() ferma il listener ma non elimina le sessioni correlate.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kit

Feed e RSS

Middleware

AHP Host

AHP Host

Avvio di un host

Modalità di autenticazione

Policy di creazione delle sessioni

Sessioni gestite dall’applicazione

Catalogo delle sessioni e arresto

Riferimenti

​AHP Host

​Avvio di un host

​Modalità di autenticazione

​Policy di creazione delle sessioni

​Sessioni gestite dall’applicazione

​Catalogo delle sessioni e arresto

​Riferimenti

AHP Host

Avvio di un host

Modalità di autenticazione

Policy di creazione delle sessioni

Sessioni gestite dall’applicazione

Catalogo delle sessioni e arresto

Riferimenti