> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# AHP Host

> Beschreibt, wie Sie mit dem Laravel Copilot SDK einen Agent Host Protocol (AHP) Host starten und Authentifizierung, Richtlinie zur Session-Erstellung sowie anwendungseigene Sessions konfigurieren.

## 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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
$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.

```php theme={null}
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

```php theme={null}
$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.

## Verwandte Dokumentation

* [RPC](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc.md)
* [Remote Sessions](https://kawax.biz/de/packages/laravel-copilot-sdk/remote-sessions.md)


## Related topics

- [RPC (Remote Procedure Call)](https://kawax.biz/de/packages/laravel-copilot-sdk/rpc.md)
- [Passwort zurücksetzen](https://kawax.biz/de/passwords.md)
- [Laravel Reverb](https://kawax.biz/de/reverb.md)
- [Laravel Sail](https://kawax.biz/de/sail.md)
- [Cache](https://kawax.biz/de/cache.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.