AHP Host

Mit dem Agent Host Protocol (AHP) können Sie einen von der Copilot-Runtime verwalteten Listener starten und Remote-Clients über WebSocket oder GitHub Mission Control annehmen. Ein AHP Host gehört zu seiner Client-Verbindung. Wenn Sie den Listener mit Client::stop() oder dispose() des Hosts beenden, werden die vom Host verwendeten Sessions nicht gelöscht.

Host starten

Übergeben Sie mindestens localServer oder githubEnvironment. Außerdem ist ein Authentifizierungsmodus erforderlich. Um anonymen Zugriff zu erlauben, müssen Sie explizit none übergeben.

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: [] verwendet eine Loopback-Adresse und einen freien Port. githubEnvironment erfordert die github-Authentifizierung. Behandeln Sie das vom Host zurückgegebene token als Verbindungsgeheimnis. workspace ist das vom AHP Host verwendete Arbeitsverzeichnis. Die Copilot-Runtime löst diesen Pfad auf dem Host auf, auf dem die Runtime läuft. Er kann daher vom Pfad innerhalb Ihrer Laravel-Anwendung abweichen. Wenn Sie ihn weglassen, nimmt das SDK workspace nicht in den RPC-Aufruf auf, und die Runtime behält ihr bisheriges Verhalten bei.

Authentifizierungsmodi

AhpHostAuthentication::github() authentifiziert über ein GitHub-Konto. Lässt sich mit githubEnvironment kombinieren.
AhpHostAuthentication::none() deaktiviert die Authentifizierung explizit.
AhpHostAuthentication::custom() validiert Admission-Tokens mit Ihrer eigenen Anwendungslogik. Erforderlich sind eine stabile Owner-Identität und ein Validierungs-Callback.

Der Callback für die benutzerdefinierte Authentifizierung erhält einen HostValidateAuthenticationRequest mit dem entschlüsselten Admission-Token sowie einen CancellationToken, der einen Abbruch signalisiert. Geben Sie bei Erfolg die Identität und ein in der Zukunft liegendes expiresAt im RFC3339-Format zurück. Um das Token abzulehnen, geben Sie null zurück. Die Identität muss exakt mit requireIdentity übereinstimmen.

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: [],
);

Das Admission-Token ist ein eigenständiges Credential, getrennt vom GitHub-Token oder Provider-Token für die Inferenz. Speichern Sie es nicht in Logs oder in der Session-Konfiguration. Das Signal des Callbacks wird abgebrochen, wenn der Host host.authenticationCancelled empfängt oder heruntergefahren wird. Wenn der Callback externe Dienste aufruft, registrieren Sie die Abbruchbehandlung mit onCancellationRequested().

Richtlinie zur Session-Erstellung

allowCreatingNewSessions legt die anfängliche Richtlinie fest, ob Remote-Clients neue Sessions erstellen dürfen. Wird die Option weggelassen, ist die Erstellung von Sessions durch Remote-Clients nicht erlaubt. Die Richtlinie gilt nicht für Sessions, die von der besitzenden Anwendung erstellt wurden, für veröffentlichte Sessions oder für bestehende Verbindungen. Um die Richtlinie während der Laufzeit des Hosts zu ändern, rufen Sie setSessionCreationPolicy() des Hosts auf. Die neue Richtlinie gilt für Anfragen, die nach der Bestätigung der Änderung eintreffen. Bereits angenommene Erstellungsanfragen können abgeschlossen werden. Verbundene Clients werden nicht getrennt.

$host->setSessionCreationPolicy(allowCreatingNewSessions: false);

Wenn Sie RPC direkt verwenden, rufen Sie $client->rpc()->host()->setSessionCreationPolicy() auf und übergeben einen HostSetSessionCreationPolicyRequest mit der hostId und der neuen Einstellung.

Anwendungseigene Sessions

Übergeben Sie die Callbacks createSession und resumeSession, um Anfragen des AHP Hosts an den Client Ihrer Anwendung weiterzuleiten. Jeder Callback erhält einen HostMaterializeSessionRequest mit der von der Runtime verifizierten HostSessionAuthentication und der vom Host bereitgestellten config sowie einen CancellationToken für kooperativen Abbruch. Geben Sie eine Session zurück, die mit demselben Client erstellt oder fortgesetzt wurde.

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 {
        // Anwendungsseitiges Aufräumen, wenn die AHP-Teilnahme endet
    },
);

onSessionReleased erhält die Session, deren Teilnahme beendet wurde. Das SDK trennt oder zerstört die Session nicht. HostMaterializeSessionRequest::$authentication ist eine vom Host verifizierte, vertrauenswürdige Identität und keine Client-Eingabe. Führen Sie dennoch die erforderliche Mandanten- oder Benutzerautorisierung innerhalb des Callbacks durch.

Session-Katalog und Beenden

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

Das Zurückziehen der Veröffentlichung entfernt die Session aus dem AHP-Katalog. Der lokale Verlauf wird dabei nicht gelöscht, und laufende Arbeiten werden nicht gestoppt. dispose() beendet den Listener, löscht aber keine zugehörigen Sessions.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds und RSS

Middleware

AHP Host

AHP Host

Host starten

Authentifizierungsmodi

Richtlinie zur Session-Erstellung

Anwendungseigene Sessions

Session-Katalog und Beenden

Verwandte Dokumentation

​AHP Host

​Host starten

​Authentifizierungsmodi

​Richtlinie zur Session-Erstellung

​Anwendungseigene Sessions

​Session-Katalog und Beenden

​Verwandte Dokumentation

AHP Host

Host starten

Authentifizierungsmodi

Richtlinie zur Session-Erstellung

Anwendungseigene Sessions

Session-Katalog und Beenden

Verwandte Dokumentation