AHP Host

Agent Host Protocol (AHP) te permite iniciar un listener gestionado por el runtime de Copilot y aceptar clientes remotos mediante WebSocket o Mission Control de GitHub. Un host AHP pertenece a su conexión Client. Detener el listener con Client::stop() o con el dispose() del host no elimina las sesiones que ha utilizado el host.

Iniciar un host

Pasa al menos uno de localServer o githubEnvironment. También es obligatorio un modo de autenticación. Para permitir el acceso anónimo, debes pasar none de forma explícita.

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: [] usa una dirección de loopback y un puerto libre. githubEnvironment requiere autenticación github. Trata el token devuelto por el host como un secreto de conexión. workspace es el directorio de trabajo que utiliza el host AHP. El runtime de Copilot resuelve esta ruta en el host donde se ejecuta el runtime, por lo que puede diferir de la ruta dentro de tu aplicación Laravel. Si lo omites, el SDK no incluye workspace en la llamada RPC y el runtime mantiene su comportamiento existente.

Modos de autenticación

AhpHostAuthentication::github() autentica con una cuenta de GitHub. Puedes combinarlo con githubEnvironment.
AhpHostAuthentication::none() deshabilita la autenticación de forma explícita.
AhpHostAuthentication::custom() valida los tokens de admisión con la lógica propia de tu aplicación. Requiere una identidad de propietario estable y un callback de validación.

El callback de autenticación personalizada recibe un HostValidateAuthenticationRequest que contiene el token de admisión descifrado y un CancellationToken que indica la cancelación. Si la validación es correcta, devuelve la identidad y un expiresAt futuro en formato RFC3339. Para rechazar el token, devuelve null. La identidad debe coincidir exactamente con 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: [],
);

El token de admisión es una credencial distinta del token de GitHub o del token del proveedor que se usa para la inferencia. No lo guardes en logs ni en la configuración de la sesión. La señal del callback se cancela cuando el host recibe host.authenticationCancelled o se apaga. Si el callback llama a servicios externos, registra el manejo de la cancelación con onCancellationRequested().

Política de creación de sesiones

allowCreatingNewSessions establece la política inicial para que los clientes remotos creen nuevas sesiones. Si se omite, se deniega la creación de sesiones remotas. La política no se aplica a las sesiones creadas por la aplicación propietaria, a las sesiones publicadas ni a las conexiones existentes. Para cambiar la política mientras el host está en ejecución, llama a setSessionCreationPolicy() del host. La nueva política se aplica a las solicitudes que llegan después de que se confirme el cambio. Las solicitudes de creación ya aceptadas pueden completarse. Los clientes conectados no se desconectan.

$host->setSessionCreationPolicy(allowCreatingNewSessions: false);

Si usas RPC directamente, llama a $client->rpc()->host()->setSessionCreationPolicy() y pasa un HostSetSessionCreationPolicyRequest con el hostId y la nueva configuración.

Sesiones gestionadas por la aplicación

Pasa los callbacks createSession y resumeSession para delegar las solicitudes del host AHP al Client de tu aplicación. Cada callback recibe un HostMaterializeSessionRequest que contiene el HostSessionAuthentication verificado por el runtime y la config proporcionada por el host, además de un CancellationToken para la cancelación cooperativa. Devuelve una sesión creada o reanudada con el mismo 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 {
        // Limpieza en la aplicación cuando termina la participación en AHP
    },
);

onSessionReleased recibe la sesión cuya participación ha terminado. El SDK no desconecta ni destruye la sesión. HostMaterializeSessionRequest::$authentication es una identidad de confianza verificada por el host, no una entrada del cliente. Aun así, realiza dentro del callback cualquier autorización de tenant o de usuario que necesites.

Catálogo de sesiones y apagado

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

Despublicar una sesión la elimina del catálogo de AHP. No elimina el historial local ni detiene el trabajo en curso. dispose() detiene el listener, pero no elimina las sesiones relacionadas.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds y RSS

Middleware

AHP Host

AHP Host

Iniciar un host

Modos de autenticación

Política de creación de sesiones

Sesiones gestionadas por la aplicación

Catálogo de sesiones y apagado

Documentación relacionada

​AHP Host

​Iniciar un host

​Modos de autenticación

​Política de creación de sesiones

​Sesiones gestionadas por la aplicación

​Catálogo de sesiones y apagado

​Documentación relacionada

AHP Host

Iniciar un host

Modos de autenticación

Política de creación de sesiones

Sesiones gestionadas por la aplicación

Catálogo de sesiones y apagado

Documentación relacionada