AHP Host

Agent Host Protocol（AHP）可讓您啟動由 Copilot 執行環境管理的監聽器，並透過 WebSocket 或 GitHub 的 Mission Control 接受遠端用戶端連線。AHP 主機由其 Client 連線所擁有。透過 Client::stop() 或主機的 dispose() 停止監聽器時，並不會刪除主機所使用的 Session。

啟動主機

請至少傳入 localServer 或 githubEnvironment 其中之一。此外也必須指定驗證模式。若要允許匿名存取，必須明確傳入 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: [] 會使用回送位址與可用的連接埠。githubEnvironment 需要 github 驗證。請將主機回傳的 token 視為連線用的機密資訊。 workspace 是 AHP 主機使用的工作目錄。Copilot 執行環境會在執行環境所在的主機上解析此路徑，因此可能與 Laravel 應用程式內的路徑不同。省略時，SDK 不會在 RPC 呼叫中包含 workspace，執行環境會維持既有的行為。

驗證模式

AhpHostAuthentication::github() 使用 GitHub 帳號進行驗證。可與 githubEnvironment 搭配使用。
AhpHostAuthentication::none() 明確停用驗證。
AhpHostAuthentication::custom() 使用您應用程式自己的邏輯驗證准入 Token。需要穩定的擁有者身分與驗證回呼。

自訂驗證回呼會收到包含已解密准入 Token 的 HostValidateAuthenticationRequest，以及用來通知取消的 CancellationToken。驗證成功時，請回傳身分與 RFC3339 格式的未來 expiresAt。若要拒絕 Token，請回傳 null。身分必須與 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: [],
);

准入 Token 是與用於推論的 GitHub Token 或供應商 Token 不同的憑證。請勿將其儲存在日誌或 Session 設定中。當主機收到 host.authenticationCancelled 或關閉時，回呼的 signal 會被取消。若回呼會呼叫外部服務，請透過 onCancellationRequested() 註冊中止處理。

Session 建立政策

allowCreatingNewSessions 用來設定遠端用戶端建立新 Session 的初始政策。省略時，會拒絕遠端建立 Session。此政策不適用於擁有者應用程式建立的 Session、已發佈的 Session 或既有的連線。若要在主機執行期間變更政策，請呼叫主機的 setSessionCreationPolicy()。新政策會套用至變更被確認後才抵達的請求。已被接受的建立請求仍可完成。已連線的用戶端不會被中斷連線。

$host->setSessionCreationPolicy(allowCreatingNewSessions: false);

直接使用 RPC 時，請呼叫 $client->rpc()->host()->setSessionCreationPolicy()，並傳入包含 hostId 與新設定的 HostSetSessionCreationPolicyRequest。

由應用程式擁有的 Session

傳入 createSession 與 resumeSession 回呼，即可將來自 AHP 主機的請求交給您應用程式的 Client 處理。每個回呼都會收到包含經執行環境驗證的 HostSessionAuthentication 與主機提供的 config 的 HostMaterializeSessionRequest，以及用於協作式取消的 CancellationToken。請回傳使用同一個 Client 建立或恢復的 Session。

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 {
        // AHP 參與結束時的應用程式端清理處理
    },
);

onSessionReleased 會收到參與已結束的 Session。SDK 不會中斷連線或銷毀該 Session。HostMaterializeSessionRequest::$authentication 是經主機驗證的可信任身分，而非用戶端輸入。儘管如此，仍請在回呼內執行所需的租戶或使用者授權檢查。

Session 目錄與關閉

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

取消發佈會將 Session 從 AHP 目錄中移除。不會刪除本機歷程記錄，也不會停止執行中的工作。dispose() 會停止監聽器，但不會刪除相關的 Session。

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

AHP Host

AHP Host

啟動主機

驗證模式

Session 建立政策

由應用程式擁有的 Session

Session 目錄與關閉

相關文件

​AHP Host

​啟動主機

​驗證模式

​Session 建立政策

​由應用程式擁有的 Session

​Session 目錄與關閉

​相關文件

AHP Host

啟動主機

驗證模式

Session 建立政策

由應用程式擁有的 Session

Session 目錄與關閉

相關文件