AHP Host

L’Agent Host Protocol (AHP) permet de démarrer un listener géré par le runtime Copilot et d’accepter des clients distants via WebSocket ou Mission Control de GitHub. Un hôte AHP appartient à sa connexion Client. Arrêter le listener avec Client::stop() ou avec la méthode dispose() de l’hôte ne supprime pas les sessions utilisées par l’hôte.

Démarrer un hôte

Passez au moins l’un des paramètres localServer ou githubEnvironment. Un mode d’authentification est également requis. Pour autoriser l’accès anonyme, vous devez passer explicitement 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: [] utilise une adresse de loopback et un port libre. githubEnvironment nécessite l’authentification github. Traitez le token renvoyé par l’hôte comme un secret de connexion. workspace est le répertoire de travail utilisé par l’hôte AHP. Le runtime Copilot résout ce chemin sur l’hôte où il s’exécute ; il peut donc différer du chemin au sein de votre application Laravel. Si vous l’omettez, le SDK n’inclut pas workspace dans l’appel RPC et le runtime conserve son comportement existant.

Modes d’authentification

AhpHostAuthentication::github() s’authentifie avec un compte GitHub. Vous pouvez le combiner avec githubEnvironment.
AhpHostAuthentication::none() désactive explicitement l’authentification.
AhpHostAuthentication::custom() valide les tokens d’admission avec la logique propre à votre application. Il nécessite une identité de propriétaire stable et un callback de validation.

Le callback d’authentification personnalisée reçoit une HostValidateAuthenticationRequest contenant le token d’admission déchiffré, ainsi qu’un CancellationToken signalant l’annulation. En cas de succès, renvoyez l’identité et une date expiresAt future au format RFC3339. Pour rejeter le token, renvoyez null. L’identité doit correspondre exactement à 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: [],
);

Le token d’admission est un identifiant distinct du token GitHub ou du token de fournisseur utilisé pour l’inférence. Ne le stockez ni dans les logs ni dans la configuration de session. Le signal du callback est annulé lorsque l’hôte reçoit host.authenticationCancelled ou s’arrête. Si le callback appelle des services externes, enregistrez la gestion de l’interruption avec onCancellationRequested().

Politique de création de sessions

allowCreatingNewSessions définit la politique initiale de création de nouvelles sessions par les clients distants. S’il est omis, la création de sessions à distance est refusée. Cette politique ne s’applique pas aux sessions créées par l’application propriétaire, aux sessions publiées ni aux connexions existantes. Pour modifier la politique pendant que l’hôte s’exécute, appelez la méthode setSessionCreationPolicy() de l’hôte. La nouvelle politique s’applique aux requêtes reçues après la confirmation du changement. Les requêtes de création déjà acceptées peuvent se terminer. Les clients connectés ne sont pas déconnectés.

$host->setSessionCreationPolicy(allowCreatingNewSessions: false);

Si vous utilisez directement le RPC, appelez $client->rpc()->host()->setSessionCreationPolicy() en passant une HostSetSessionCreationPolicyRequest avec le hostId et le nouveau paramètre.

Sessions gérées par l’application

Passez les callbacks createSession et resumeSession pour transmettre les requêtes de l’hôte AHP au Client de votre application. Chaque callback reçoit une HostMaterializeSessionRequest contenant la HostSessionAuthentication vérifiée par le runtime et la config fournie par l’hôte, ainsi qu’un CancellationToken pour l’annulation coopérative. Renvoyez une session créée ou reprise avec le même 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 {
        // Nettoyage côté application lorsque la participation AHP prend fin
    },
);

onSessionReleased reçoit la session dont la participation a pris fin. Le SDK ne déconnecte ni ne détruit la session. HostMaterializeSessionRequest::$authentication est une identité de confiance vérifiée par l’hôte, et non une entrée du client. Effectuez néanmoins dans le callback toute vérification d’autorisation de tenant ou d’utilisateur nécessaire.

Catalogue de sessions et arrêt

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

Annuler la publication retire la session du catalogue AHP. Cela ne supprime pas l’historique local et n’arrête pas le travail en cours. dispose() arrête le listener mais ne supprime pas les sessions associées.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Kits de démarrage

Flux et RSS

Middleware

AHP Host

AHP Host

Démarrer un hôte

Modes d’authentification

Politique de création de sessions

Sessions gérées par l’application

Catalogue de sessions et arrêt

Documentation associée

​AHP Host

​Démarrer un hôte

​Modes d’authentification

​Politique de création de sessions

​Sessions gérées par l’application

​Catalogue de sessions et arrêt

​Documentation associée

AHP Host

Démarrer un hôte

Modes d’authentification

Politique de création de sessions

Sessions gérées par l’application

Catalogue de sessions et arrêt

Documentation associée