Mandantenfähigkeit und Serverbereitstellungen

Am besten geeignet für: SaaS-Produkte, Partnerintegrationen, interne Plattformen und Back-End-Dienste, die gleichzeitige Benutzer verarbeiten.

Verwenden Sie dieses Handbuch, wenn

Verwenden Sie diesen Leitfaden, wenn Sie Folgendes erstellen:

• Ein Mehrbenutzer-SaaS-Produkt, das Copilot-gestützte Agenten einbettet
• Ein Backend für eine Partnerintegration, beispielsweise ein Muster im Stil von Copilot Studio oder Fabric
• Jeder Server, der gleichzeitige Benutzer, Arbeitsbereiche, Mandanten oder Anforderungen verarbeitet
• Eine freigegebene Laufzeit, bei der mehrere SDK-Clients eine Verbindung mit einem Copilot Laufzeitprozess herstellen

Dieser Leitfaden ist eine Schwester von Skalierung und Mehrinstanzenfähigkeit. Verwenden Sie dieses Handbuch für Topologie, Lastenausgleich und Speichermuster. Verwenden Sie dieses Handbuch für Optionen auf SDK-Ebene und Optionen für die Laufzeitisolation.

Schlüssel-SDK-Optionen

Informationen zu Rückruf-gesicherten Anmeldeinformationen finden Sie unter Authentication. Jede Sitzung hat ihre eigene Provider-Registrierung, sodass gleichzeitige Sitzungen unterschiedliche GitHub-Hosts und Konten verwenden können, ohne sich einen gemeinsamen Callback-Status zu teilen.

mode: "empty"

mode: "empty" deaktiviert standardmäßig optionales Copilot CLI-Verhalten. Im Servermodus mit mehreren Benutzern ist dies der sichere Basisplan, da Ihre Anwendung explizit entscheiden muss, auf welche Tools, MCP-Server, Fähigkeiten und Arbeitsbereichspfade eine Sitzung zugreifen kann.

Verwenden Sie für gemeinsam genutzte Server nicht die Standardeinstellung mode: "copilot-cli". Dieser Modus ist für CLI-ähnliche Codierungs-Agents vorgesehen und kann Umgebungshost-Dateisystemfunktionen verfügbar machen.

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

// baseDirectory and sessionIdleTimeoutSeconds apply when the SDK spawns the
// runtime. With RuntimeConnection.forUri(...) configure COPILOT_HOME and the
// idle timeout on the runtime process itself.
const client = new CopilotClient({
    mode: "empty",
    connection: RuntimeConnection.forUri(process.env.COPILOT_RUNTIME_URL!),
});

const session = await client.createSession({
    sessionId: `user-${user.id}-${crypto.randomUUID()}`,
    model: "gpt-5.4",
    availableTools: ["custom:lookupOrder", "custom:createTicket"],
    gitHubToken: user.githubToken,
});

from copilot import CopilotClient, RuntimeConnection
from copilot.session import PermissionHandler

client = CopilotClient(
    mode="empty",
    base_directory=f"/var/lib/my-app/copilot/{runtime_instance_id}",
    session_idle_timeout_seconds=900,
    connection=RuntimeConnection.for_uri(runtime_url),
)
await client.start()

session = await client.create_session(
    session_id=f"user-{user.id}-{request_id}",
    model="gpt-5.4",
    available_tools=["custom:lookupOrder", "custom:createTicket"],
    github_token=user.github_token,
    on_permission_request=PermissionHandler.approve_all,
)

client := copilot.NewClient(&copilot.ClientOptions{
    Mode:                      copilot.ModeEmpty,
    BaseDirectory:             fmt.Sprintf("/var/lib/my-app/copilot/%s", runtimeInstanceID),
    SessionIdleTimeoutSeconds: 900,
    Connection:                copilot.URIConnection{URL: runtimeURL},
})

session, err := client.CreateSession(ctx, &copilot.SessionConfig{
    SessionID:      fmt.Sprintf("user-%s-%s", user.ID, requestID),
    Model:          "gpt-5.4",
    AvailableTools: []string{"custom:lookupOrder", "custom:createTicket"},
    GitHubToken:    user.GitHubToken,
})

var client = new CopilotClient(new CopilotClientOptions
{
    Mode = CopilotClientMode.Empty,
    BaseDirectory = $"/var/lib/my-app/copilot/{runtimeInstanceId}",
    SessionIdleTimeoutSeconds = 900,
    Connection = RuntimeConnection.ForUri(runtimeUrl),
});

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    SessionId = $"user-{user.Id}-{requestId}",
    Model = "gpt-5.4",
    AvailableTools = ["custom:lookupOrder", "custom:createTicket"],
    GitHubToken = user.GitHubToken,
});

// setCopilotHome and setSessionIdleTimeoutSeconds are ignored when
// setCliUrl is used; configure those on the runtime process instead.
var client = new CopilotClient(new CopilotClientOptions()
    .setMode(CopilotClientMode.EMPTY)
    .setCliUrl(runtimeUrl)
);

var session = client.createSession(new SessionConfig()
    .setSessionId("user-" + user.id() + "-" + requestId)
    .setModel("gpt-5.4")
    .setAvailableTools(List.of("custom:lookupOrder", "custom:createTicket"))
    .setGitHubToken(user.gitHubToken())
).get();

use std::path::PathBuf;
use github_copilot_sdk::{Client, ClientOptions, Transport};
use github_copilot_sdk::mode::ClientMode;
use github_copilot_sdk::types::SessionConfig;

let client = Client::start(
    ClientOptions::new()
        .with_mode(ClientMode::Empty)
        .with_base_directory(PathBuf::from(format!(
            "/var/lib/my-app/copilot/{runtime_instance_id}"
        )))
        .with_session_idle_timeout_seconds(900)
        .with_transport(Transport::External {
            host: runtime_host.to_string(),
            port: runtime_port,
            connection_token: None,
        }),
).await?;

let session = client.create_session(
    SessionConfig::default()
        .with_session_id(format!("user-{}-{request_id}", user.id))
        .with_model("gpt-5.4")
        .with_available_tools(["custom:lookupOrder", "custom:createTicket"])
        .with_github_token(user.github_token),
).await?;

sessionIdleTimeoutSeconds

Legen Sie sessionIdleTimeoutSeconds auf Servern fest, damit inaktive Sitzungen automatisch beendet werden. Dies verhindert Zombie-Sitzungen in lang laufenden Prozessen und reduziert den Speicher- und Dateisystemdruck.

Verwenden Sie einen Wert, der der Lebensdauer einer Konversation in Ihrem Produkt entspricht. Bei Chat-Back-Ends ist in der Regel 15 bis 30 Minuten ein guter Ausgangspunkt. Verwenden Sie für Workflow-Agents ein längeres Timeout und explizites Löschen, wenn der Workflow abgeschlossen ist.

baseDirectory

baseDirectory legt COPILOT_HOME für eine Laufzeitinstanz fest. Verwenden Sie dies, um Laufzeitstatus, Anmeldeinformationen und Sitzungsdaten pro Prozess, Pod, Worker oder Mandantengrenze zu isolieren.

const client = new CopilotClient({
    mode: "empty",
    baseDirectory: `/var/lib/my-app/copilot/runtime-${process.env.HOSTNAME}`,
    sessionIdleTimeoutSeconds: 900,
});

Die Laufzeit speichert den Sitzungsstatus unter dem konfigurierten COPILOT_HOME, einschließlich session-state/{sessionId}. Wenn Ihre App mehrere Laufzeitinstanzen ausführt, weisen Sie jeder Instanz ein eigenes Verzeichnis zu, es sei denn, Sie verwenden absichtlich freigegebenen Speicher.

Wenn das SDK eine Verbindung mit einer bereits ausgeführten Laufzeit mit RuntimeConnection.forUri(url) herstellt, wird baseDirectory vom SDK-Client ignoriert. Konfigurieren Sie COPILOT_HOME stattdessen für den Laufzeitprozess.

sessionFs

sessionFs registriert einen benutzerdefinierten Sitzungsdateisystemanbieter, sodass sitzungsbezogene Datei-E/A über den Anwendungsspeicher statt über die lokale Festplatte der Laufzeitumgebung geleitet werden kann. Verwenden Sie sie, wenn der lokale Datenträger kurzlebig ist, wenn der Sitzungszustand im Objektspeicher gespeichert werden muss oder wenn eine Plattform mandantenbezogene Speicherpfade erzwingen muss.

const client = new CopilotClient({
    mode: "empty",
    sessionFs: {
        initialCwd: "/workspace",
        sessionStatePath: "/session-state",
        conventions: "posix",
    },
});

Konfigurieren Sie für Sprachen, die einen Provider-Callback bereitstellen, sessionFs auf Client-Ebene, und stellen Sie beim Erstellen oder Fortsetzen einer Sitzung einen sitzungsspezifischen Dateisystem-Handler bereit. Siehe Wiederaufnahme und Persistenz der Sitzung für Persistenzkonzepte und Speicherabschläge.

Laufzeiteigene dauerhafte Berechtigungseinstellungen verwenden auch das Sitzungsdateisystem. Unter dem sessionStatePath des Anbieters behält tool_approvals seine allowed_directories-Zuordnung auf oberster Ebene mit settings.json und locations bei; allowedUrls speichert sandbox und config.json auf oberster Ebene; und trustedFolders speichert permissions.json auf oberster Ebene.

URL-Genehmigungen werden nur aus settings.json gelesen; ältere Benutzereinstellungsfelder wie z. B. in config.json``allowedUrls werden ignoriert, was dem Hostverhalten entspricht.

Standortschlüssel sind normalisierte Anbieterverzeichnispfade ohne hinzugefügtes Präfix. Die Auflösung folgt den Pfadkonventionen des Anbieters, ohne das Hostdateisystem zu prüfen oder Host-Git-Repositorys zu ermitteln. /workspace und /workspace/sub wählen unterschiedliche Standorteinträge aus.

Die Laufzeit fügt diesen Dateien keine Sitzungs-ID-Partitionen hinzu oder ändert ihre Freigabe-Granularität. Sitzungen, die auf dieselben Dateien im selben Anbieternamespace zugreifen, teilen sich gespeicherte Berechtigungen. Ihre Anwendung muss unterschiedliche Namespaces für Mandanten oder Sitzungen verwenden, die Isolation erfordern, den Zugriff auf jeden Namespace autorisieren und wiederaufgenommene Sitzungen erneut mit ihrem ursprünglichen Namespace verbinden.

Mit einem separaten Namespace pro Sitzung überleben dauerhafte Berechtigungen die Wiederaufnahmen dieser Sitzung, anstatt mandantenweite Berechtigungen für neue Sitzungen zu werden. Die gemeinsame Nutzung von Berechtigungen zur Freigabe über Sitzungen hinweg erfordert die gemeinsame Nutzung der Einwilligungsdateien, während der übrige Sitzungszustand getrennt bleibt. Die Laufzeit serialisiert Zustimmungsupdates nur innerhalb desselben Anbieterendpunkts und -prozesses; Anwendungen, die zugrunde liegende Dateien über Endpunkte oder Prozesse hinweg gemeinsam nutzen, müssen gleichzeitige Updates koordinieren.

Die Laufzeit blockiert direkte, durch den Provider unterstützte Dateischreibvorgänge in die lexikalischen Genehmigungsmetadatenpfade im Sinne einer mehrschichtigen Absicherung, nicht als manipulationssichere Speichergrenze. Anbieter dürfen beschreibbare Aliase (z. B. symlinks oder Windows 8.3 short names) nicht über Agentdateitools für Genehmigungsmetadaten verfügbar machen. Shelltools werden nicht über SessionFS ausgeführt, und ihre Befehle werden nicht anhand seiner virtuellen Metadatenpfade überprüft. Wenn Ihre Anwendung den zugrunde liegenden Speicher des Anbieters separat für die Shellausführung oder anderen beliebigen Code verfügbar macht, muss Ihr Host diesen Speicher schützen.

Genehmigungsvorgänge für das Sitzungsdateisystem importieren niemals gespeicherte Berechtigungen aus den URL- permissions-config.json oder Sandkasteneinstellungen settings.json des Hosts und greifen auch nicht auf die Ordnervertrauensstellung von config.json zurück. Sie aktualisieren diese Hostdateien nicht, auch wenn der Anbieter keine Genehmigungen hat oder einen Fehler meldet. Ein Anbieterfehler berechtigt nicht zur Verwendung der Hosteinwilligung. URL-Ablehnungsregeln bleiben maßgeblich, und das Ordnervertrauen verwendet Anbieterpfade ohne Host-Git-Erkennung.

„Einmal genehmigen“, „Für Sitzung genehmigen“, „Ablehnungen“ und „Änderungen an Sitzungsrichtlinien“ behalten ihre vorhandenen Lebensdauern und das Verhalten der Ereigniswiedergabe bei. Das Speicherrouting wandelt sie nicht in neue dauerhafte Berechtigungen um. Schützen Sie Sitzungsaufzeichnungen, einschließlich dauerhafter Berechtigungsereignisse, mit derselben Mandantenisolation wie Genehmigungsmetadaten.

Diese Grenze gilt nur für Sitzungen mit einem Sitzungsdateisystemanbieter. Alle SDK-Anwendungen ohne sessionFs, sowohl im copilot-cli- als auch im empty-Modus und in normalen CLI-Sitzungen behalten vorhandene hostgestützte Persistenz für Erinnerungsorte, dauerhafte URL-Genehmigungen, Ordnervertrauensstellungen und Sandkasteneinstellungen bei.

Überprüfte öffentliche SDK-Oberflächen:

Java stellt derzeit keine überprüfte öffentliche sessionFs-Option zur Verfügung, sodass in diesem Handbuch kein Java sessionFs-Beispiel angezeigt wird.

RuntimeConnection.forUri(url)

Verwenden Sie eine externe Laufzeitverbindung, wenn mehrere SDK-Clients eine bereits ausgeführte Laufzeit gemeinsam nutzen sollten. Dies ist in Back-End-Diensten üblich, bei denen der Laufzeitprozess getrennt von Anforderungshandlern verwaltet wird.

Externe Laufzeiten verwalten ihre eigene Authentifizierung und Speicherung auf Prozessebene. Übergeben Sie Token pro Sitzung an createSession oder resumeSession wenn Sie eine benutzerspezifische Authentifizierung benötigen.

Pro Sitzung gitHubToken

Legen Sie gitHubToken in jeder Sitzung fest, um die GitHub-Authentifizierung auf den anfordernden Benutzer zu beschränken. Dies unterscheidet sich von einem Token auf Clientebene, das den Laufzeitprozess authentifiziert.

const session = await client.createSession({
    sessionId: `user-${user.id}-support`,
    model: "gpt-5.4",
    availableTools: ["custom:*"],
    gitHubToken: user.githubToken,
});

Verwenden Sie sitzungsbezogene Tokens für den Ausschluss von Inhalten, das Modellrouting, Kontingentprüfungen und den benutzerspezifischen Copilot-Zugriff. Vermeiden Sie die Freigabe eines Diensttokens für alle Benutzer, es sei denn, Ihr Produkt verwendet absichtlich die Semantik des Dienstkontos.

Integration-ID

Partner, die Branding-Agents erstellen, können eine Integrations-ID für Mission Control-Anforderungen festlegen. Die Laufzeit liest GITHUB_COPILOT_INTEGRATION_ID und stempelt sie als Copilot-Integration-Id HTTP-Header für jede Mission Control-Anforderung.

GITHUB_COPILOT_INTEGRATION_ID=my-product-agent copilot --headless --port 4321

Die Standardintegrations-ID lautet copilot-developer-cli. Verwenden Sie einen stabilen Wert wie my-product-agent für Attribution und Routing. Die Integrations-ID wird derzeit nur von der Umgebungsvariablen konfiguriert. Es handelt sich nicht um eine erstklassige SDK-Option.

Wenn das SDK die Laufzeit startet, übergeben Sie die Umgebungsvariable über die Client-Umgebungsoption. Wenn Sie eine Verbindung mit RuntimeConnection.forUri(url) herstellen, legen Sie die Umgebungsvariable direkt für den Laufzeitprozess selbst fest.

Isolationsgarantien auf Sitzungsebene

Die Isolation auf Sitzungsebene bedeutet, dass die Laufzeit benutzerspezifische Modell- und Zustandsinformationen auf eine Sitzung beschränkt und nicht in einem global gemeinsam genutzten Zustand hält.

mode: "empty" macht freigegebene Laufzeitmuster praktikabel: Es werden keine umgebenden Betriebssystemtools verfügbar gemacht, es sei denn, Ihre Anwendung registriert oder lässt sie zu. Mit mode: "copilot-cli" wird der Zugriff auf das Dateisystem des Betriebssystems über den Hostprozess gemeinsam genutzt. Verwenden Sie diesen Modus daher nicht im Mehrbenutzer-Servermodus.

Unter mode: "empty" schließt das SDK standardmäßig jeden integrierten, mit der Runtime gebündelten Skill aus (dabei sendet es im Patch für die Post-Create-/Post-Resume-Optionen neben der leeren installedPlugins-Liste auch eine leere includedBuiltinSkills-Liste). Legen Sie includedBuiltinSkills (oder die sprachspezifische Groß-/Kleinschreibung) so fest, um ausgewählte integrierte Elemente ausdrücklich zuzulassen, genauso wie availableTools ausgewählte mit der Laufzeitumgebung gebündelte Tools zulässt. Ein Anrufer kann sich auch für seine eigenen benutzerdefinierten Fähigkeiten entscheiden , z. B. durch die Aktivierung von Fähigkeiten und Zeigen auf seine eigenen Qualifikationsverzeichnisse – und diese bleiben nutzbar.

Der Sitzungszustand wird unter COPILOT_HOME/session-state/{sessionId} gespeichert, es sei denn, Sie leiten ihn über sessionFs um. Verwenden Sie eindeutige Sitzungs-IDs, die Ihre eigene Mandanten- oder Benutzergrenze enthalten, und erzwingen Sie die Zugriffssteuerung, bevor Sie Sitzungen fortsetzen oder löschen.

Mustervergleich

Muster 2: gemeinsame CLI mit mode: "empty"

In diesem Muster verbinden sich alle Benutzer über Ihr Back-End mit einem Laufzeitpool. Die Anwendung führt die Benutzerauthentifizierung aus, wählt eine Sitzungs-ID aus, übergibt das GitHub-Token des Benutzers in der Sitzung und stellt eine explizite Tool-Zulassungsliste bereit.

Verwenden Sie die folgenden Regeln:

• Starten Sie den Client oder die Runtime immer in mode: "empty".
• Verwenden Sie eindeutige Sitzungs-IDs, und speichern Sie Besitzermetadaten in Ihrer Anwendungsdatenbank.
• Überprüfen Sie die Inhaberschaft vor resumeSession, deleteSession oder jeder UI-Aktion, die auf eine Sitzungs-ID verweist.
• Übergeben Sie gitHubToken pro Sitzung, wenn Anforderungen als der Benutzer ausgeführt werden sollen.
• Registrieren Sie nur die Tools, die die Sitzung benötigt, und bevorzugen Sie quellqualifizierte Zulassungslisten wie custom:* oder mcp:search_docs.
• Legen Sie sessionIdleTimeoutSeconds fest und löschen Sie abgeschlossene Workflow-Sitzungen explizit.

Häufige Fallstricke

• Vergessen von mode: "empty". Der Standardmodus copilot-cli macht das CLI-Stilverhalten verfügbar und kann das Hostdateisystem über Umgebungstools verfügbar machen.
• Keine Festlegung von sessionIdleTimeoutSeconds. Server mit langen Laufzeiten können inaktive Sitzungen ansammeln, wenn diese nicht bereinigt werden.
• Freigeben eines gitHubToken für mehrere Benutzer anstelle der Übergabe eines Tokens pro Sitzung.
• Blindes Vertrauen in vom Client übermittelte Sitzungs-IDs, ohne im Backend ihre Zugehörigkeit zu prüfen.
• Festlegen von baseDirectory auf einem Client, der eine Verbindung mit einer vorhandenen Laufzeit herstellt, und Erwarten, dass der Laufzeitspeicher verschoben wird. Konfigurieren Sie stattdessen den Laufzeitprozess.
• Das Zulassen weit gefasster Toolmuster wie builtin:*, ohne zu prüfen, ob jedes Tool für Ihre Benutzer geeignet ist.

Siehe auch

• Skalierung und Mehrinstanzenfähigkeit: Bereitstellungstopologien, Speichermuster und Isolationsvergleiche
• Einrichtung von Back-End-Diensten: Ausführen der Runtime im Headless-Servermodus
• Bring Your Own Key (BYOK): Verwendung der Anmeldedaten Ihres eigenen Modellanbieters
• Cloud-Sitzungen: Weiterleiten ausgewählter Arbeit an Cloud-Sitzungen
• Wiederaufnahme und Persistenz der Sitzung: Verwalten des fortsetzungsfähigen Sitzungszustands
• Funktionen: Tools, Ereignisse, Hooks und erweiterte SDK-Features