Cloud-Sitzungen

Voraussetzungen

Stellen Sie vor dem Erstellen einer Cloudsitzung folgendes sicher:

Der Benutzer hat Zugriff auf Copilot mit Cloud-Agent-Berechtigung.
Die Sitzung kann sich bei GitHub authentifizieren, entweder mit einem Benutzertoken oder einer angemeldeten Copilot CLI-Identität.
Sie können die Sitzung einem GitHub Repository zuordnen. Dies ist im SDK-Typ optional, wird jedoch empfohlen, sodass der Cloud-Agent über den richtigen Repositorykontext verfügt.
Organisationsrichtlinien ermöglichen die Remotesteuerung und Anzeige von Sitzungen über Cloudoberflächen.

Erstellen einer Cloudsitzung

Legen Sie die Option create-session cloud fest, um eine Cloud-Sitzung zu erstellen. Sie können Repositorymetadaten einschließen, um die Cloudsitzung einem GitHub Repository zuzuordnen.

Typescript

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
  onPermissionRequest: async () => ({ kind: "approve-once" }),
  cloud: {
    repository: {
      owner: "github",
      name: "copilot-sdk",
      branch: "main",
    },
  },
});

Python

from copilot import (
    CloudSessionOptions,
    CloudSessionRepository,
    CopilotClient,
    PermissionHandler,
)

client = CopilotClient()
await client.start()

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    cloud=CloudSessionOptions(
        repository=CloudSessionRepository(
            owner="github",
            name="copilot-sdk",
            branch="main",
        )
    ),
)

Go

client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil {
    return err
}

session, err := client.CreateSession(ctx, &copilot.SessionConfig{
    Cloud: &copilot.CloudSessionOptions{
        Repository: &copilot.CloudSessionRepository{
            Owner:  "github",
            Name:   "copilot-sdk",
            Branch: "main",
        },
    },
    OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
        return &rpc.PermissionDecisionApproveOnce{}, nil
    },
})
_ = session

.NET

await using var client = new CopilotClient();

var session = await client.CreateSessionAsync(new SessionConfig
{
    Cloud = new CloudSessionOptions
    {
        Repository = new CloudSessionRepository
        {
            Owner = "github",
            Name = "copilot-sdk",
            Branch = "main",
        },
    },
    OnPermissionRequest = (req, inv) =>
        Task.FromResult(PermissionDecision.ApproveOnce()),
});

Java

import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setCloud(new CloudSessionOptions()
                .setRepository(new CloudSessionRepository()
                    .setOwner("github")
                    .setName("copilot-sdk")
                    .setBranch("main")))
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();
}

Rust

use std::sync::Arc;
use github_copilot_sdk::{CloudSessionOptions, CloudSessionRepository, SessionConfig};
use github_copilot_sdk::handler::ApproveAllHandler;

let session = client.create_session(
    SessionConfig::default()
        .with_cloud(CloudSessionOptions::with_repository(
            CloudSessionRepository::new("github", "copilot-sdk").with_branch("main"),
        ))
        .with_permission_handler(Arc::new(ApproveAllHandler)),
).await?;

Cloud-Sitzungen werden in zwei Phasen initialisiert: createSession ist verfügbar, sobald der Agent die Aufgabe reserviert hat, aber der Remote-Worker copilot-agent benötigt noch ein bis zwei Sekunden, um sich zu verbinden und session.start auszugeben. Wenn Sie session.send vorher aufrufen, löst das RemoteSession.send der Laufzeit "Remote session is still starting" aus, aber der Schema-Wrapper arbeitet nach dem Fire-and-Forget-Prinzip und verschluckt den Fehler stillschweigend, während er Ihrem Code dennoch ein neues messageId zurückgibt. Die Eingabeaufforderung wird auf dem Server abgelegt und erreicht nie den Worker.

Um zuverlässig zu senden, abonnieren Sie die Ereignisse vor dem Senden und warten Sie auf das erste session.start Ereignis, dessen producer``"copilot-agent" ist:

import { CopilotClient, type CopilotSession } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session: CopilotSession = await client.createSession({
  streaming: true, // required for assistant.message_delta to fire
  cloud: { repository: { owner: "github", name: "copilot-sdk" } },
  onPermissionRequest: async () => ({ kind: "approve-once" }),
});

// Subscribe BEFORE sending so you don't miss the start event.
const ready = new Promise<void>((resolve) => {
  const off = session.on("session.start", (event) => {
    if (event.data?.producer === "copilot-agent") {
      off();
      resolve();
    }
  });
});

await ready;
await session.send({ prompt: "Summarize the README" });

Einige Hinweise:

Legen Sie streaming: true in createSession fest, sodass die Laufzeit assistant.message_delta-Ereignisse ausgibt. Ohne sie ist das einzige Assistentensignal, das Sie erhalten, das abschließende assistant.message – für die Batch-Verarbeitung in Ordnung, aber der Chat wirkt eingefroren, wenn Sie eine Live-UI rendern. Siehe Ereignisse einer Streaming-Sitzung.
Nur das erstesession.send ist für dieses Rennen sensibel. Nachfolgende Sendevorgänge in derselben Sitzung funktionieren normal, weil die Laufzeit hasSessionStarted für die Dauer der Sitzung gesetzt hält.
Wenden Sie ein Timeout (z. B. 60 s) auf das ready Promise an, damit eine festgefahrene Sitzung Ihre App nicht dauerhaft blockiert.
Dasselbe Muster funktioniert in jeder SDK-Sprache — session.start abonnieren, producer === "copilot-agent" prüfen und dann send aufrufen.

Zugreifen auf die Agentsitzungs-URL

Cloud-Sitzungen sind von Natur aus remote: Sobald der Worker sich verbindet, wird die Sitzung unter https://github.com/copilot/tasks/{sessionId} veröffentlicht, und die Laufzeit löst ein session.info-Ereignis mit der URL aus. Sie müssen nichtremote.enable() aufrufen — diese API dient nur zum Synchronisieren einer lokalen Sitzung mit GitHub.

Erfassen Sie die URL, indem Sie session.info abonnieren und nach infoType: "remote" filtern:

session.on("session.info", (event) => {
  if (event.data?.infoType === "remote" && event.data.url) {
    console.log("Open from web or mobile:", event.data.url);
    // For example, surface in your UI as a shareable link or QR code.
  }
});

Das Ereignis wird kurz nach session.start ausgelöst. Wenn Ihr Renderer erst eingebunden wird, nachdem das Ereignis bereits ausgelöst wurde, speichern Sie die URL zusammen mit dem Sitzungsdatensatz im State Ihrer App und aktivieren Sie sie beim erneuten Einbinden wieder – die Runtime sendet session.info nicht von selbst erneut aus.

Informationen zur gleichen Verkabelung bei lokalen Sitzungen, die über remote: true beworben werden, finden Sie unter Remotesitzungen.

Repositoryzuordnung

Das cloud.repository-Objekt ordnet die Cloudsitzung einem GitHub Repository zu:

Feld	Required	Description
`owner`	Yes	Repositorybesitzer oder -organisation.
`name`	Yes	Repositoryname.
`branch`	No	Zu verwendender Branch für den Repository-Kontext. Lassen Sie den Wert weg, damit die Laufzeit den Standard-Branch oder den aktuellen Repository-Kontext auswählen kann.

Die Repositoryzuordnung ist im SDK-Typ optional. Fügen Sie sie jedoch ein, wenn Ihre App das Ziel-Repository kennt. Sie sorgt dafür, dass die Sitzung im Agents-Bereich mit dem richtigen Repository-Kontext angezeigt wird, und gibt dem Cloud-Agenten einen klareren Startpunkt.

Verwenden Sie branch, wenn die Arbeit von einem bestimmten Branch aus beginnen soll. Wenn Ihre App Sitzungen aus Pullanforderungen, Problem-Triage-Abläufen oder Bereitstellungsworkflows erstellt, übergeben Sie die Verzweigung, die der für den Benutzer sichtbaren Aufgabe entspricht.

Fortsetzen einer Cloudsitzung

Die cloud Option gilt nur beim Erstellen einer neuen Sitzung. Verwenden Sie die standardmäßige Wiederaufnahme-API für die SDK-Sprache, um eine vorhandene Cloudsitzung fortzusetzen:

const session = await client.resumeSession("session-id", {
  onPermissionRequest: async () => ({ kind: "approve-once" }),
});

Übergeben Sie cloud beim Fortfahren nicht erneut. Die gespeicherten Sitzungsmetadaten weisen darauf hin, dass die Sitzung cloudgestützt ist, und die Wiederaufnahme erfolgt über den normalen Pfad zur Sitzungswiederaufnahme.

Organisationsrichtlinien und -berechtigungen

Die Erstellung von Cloud-Sitzungen kann fehlschlagen, wenn der Benutzer oder die Organisation nicht zur Ausführung von Cloud-Agents berechtigt ist oder wenn Richtlinien auf Organisationsebene den Ablauf blockieren. Insbesondere können Richtlinien für Cloud-Sandbox verhindern, dass Clients die Cloudaufgabe erstellen.

In diesem Fall meldet die Laufzeit einen Fehlergrund "policy_blocked" für die Erstellung von Cloudaufgaben. Behandeln Sie dies als Autorisierungs- oder Richtlinienergebnis, nicht als vorübergehender Infrastrukturfehler.

Prüfen Sie in TypeScript den Grund, bevor Sie es erneut versuchen:

try {
  await client.createSession({ cloud: { repository } });
} catch (error) {
  if ((error as { reason?: string }).reason === "policy_blocked") {
    // Show an admin-facing message or link to org policy settings.
  }
  throw error;
}

Überprüfen Sie in Sprachen, in denen SDK-Fehler unterschiedlich dargestellt werden, den ausgegebenen Fehlergrund oder -code und behandeln Sie "policy_blocked" explizit. Es wird nicht erwartet, dass ein Erneutes Wiederholen ohne Eine Richtlinienänderung erfolgreich ist.

Integrations-ID und Routing

Cloud-Sitzungen werden mit einem Copilot-Integration-Id-Header versehen, der von der Umgebungsvariable GITHUB_COPILOT_INTEGRATION_ID abgeleitet wird. Diese Integrations-ID wird für Routing, Attribution und integrationsspezifisches Verhalten verwendet.

Ausführliche Informationen zu Mehrbenutzerservern und vollständigen Integrations-ID-Details finden Sie unter Mandantenfähigkeit und Serverbereitstellungen.

Vom SDK erstellte Cloud-Sitzungen werden an den copilot-developer-sandbox Agent-Slug weitergeleitet. Der Name ist eine interne Routing-Slug für den Cloud-Agent und bedeutet nicht, dass die Sitzung die lokale Windows Sandbox verwendet.

Erweitert: `COPILOT_MC_BASE_URL`

Standardmäßig leitet die Laufzeit die Agentsitzungsbasis-URL von der konfigurierten Copilot API-URL ab. Legen Sie COPILOT_MC_BASE_URL nur fest, wenn Sie diesen Sitzungsendpunkt außer Kraft setzen müssen.

Dies kann für GitHub Enterprise Server-Bereitstellungen erforderlich sein. Bestätigen Sie den richtigen Wert und den Supportstatus mit Ihrem GitHub Vertreter, bevor Sie sich auf ihn in der Produktion verlassen.

COPILOT_MC_BASE_URL="https://example.com/agents"

Cloudsitzungen im Vergleich zu Remotesitzungen

Fähigkeit	Remotesitzungen	Cloud-Sitzungen
Ausführungsstandort	Lokaler Computer oder Ihr Server	GitHub-gehostete Rechenleistung
Sitzungsfunktion	Teilt eine lokale Sitzung für GitHub Web/Mobile	Erstellt die gehostete Sitzung und leitet sie weiter.
SDK-Option
`remote: true` auf Clientseite oder in der Sitzung
`cloud: { ... }` beim Erstellen einer Sitzung
Fortsetzungspfad	Standard-Lebenslauf	Standard-Lebenslauf
Windows-Sandbox-Beziehung	Nicht verwandt	Nicht verwandt

Verwenden Sie Remotesitzungen, wenn die Sitzung dort ausgeführt werden soll, wo die SDK-Laufzeitumgebung bereits läuft, aber auch über das Agenten-Panel auf GitHub zugänglich sein soll. Verwenden Sie Cloudsitzungen, wenn die Sitzung auf GitHub gehosteten Compute ausgeführt werden soll.

Troubleshooting

Symptom	Wahrscheinliche Ursache	Was soll überprüft werden?
Die Erstellung von Cloudsitzungen gibt `"policy_blocked"` zurück	Die Organisationsrichtlinie verhindert die Remotesteuerung oder die Remoteansicht durch Cloud-Flows	Überprüfen von Organisations-Copilot Richtlinien und Benutzerberechtigungen
Sitzung wird ohne Repositorykontext erstellt
`cloud.repository` wurde nicht angegeben.	Übergeben Sie `owner`, `name` und optional `branch`
„Fortsetzen“ ignoriert eine neue `cloud`Option
`cloud` gilt nur für neue Sitzungen	Bestehende Sitzung normal fortsetzen
Verwirrung mit Sandkasteneinstellungen	Windows Sandbox und Cloud-Sitzungen sind getrennt	Nicht für die Cloudausführung verwenden `SANDBOX=true`
`session.send` wird mit einem `messageId`-Ereignis aufgelöst, aber es werden keine `assistant.*`-Ereignisse ausgelöst, und im Sitzungsprotokoll erscheint keine Eingabeaufforderung.	Das session.send kam dem `session.start` vom Remote-Worker zuvor; die Laufzeitumgebung verschluckte den Prompt.	Warten Sie vor dem Senden, bis das erste session.start``producer === "copilot-agent"-Ereignis eintritt. Siehe Senden der ersten Eingabeaufforderung
Live-UI wird nie aktualisiert, obwohl der Cloud-Worker verarbeitet.
`streaming` wurde auf `createSession` nicht festgelegt, sodass nur das endgültige `assistant.message` ausgegeben wird.	Aktivieren Sie `streaming: true` in `createSession` und starten Sie es erneut
Die Cloudsitzung funktioniert, aber in Ihrer Benutzeroberfläche wird keine freigabefähige URL angezeigt.	Die App hat `session.info` für die URL nie abonniert.
`session.info` abonnieren und `infoType === "remote"` filtern. Siehe Zugriff auf die Agentsitzungs-URL

Siehe auch

Remotesitzungen: Lokal gehostete Sitzungen für den Agentsbereich freigeben GitHub
Ereignisse einer Streaming-Sitzung: Abonnieren von assistant.* Deltas für das Live-UI-Rendering
Mandantenfähigkeit und Serverbereitstellungen: Integrations-IDs und Serverbereitstellungsmuster
Authentication: Konfigurieren GitHub Authentifizierung für SDK-Sitzungen

In diesem Artikel