Sitzungspersistenz im Copilot SDK

Hinweis

          Copilot SDK ist zurzeit in Technische Preview. Funktionalität und Verfügbarkeit können geändert werden.

Wenn Sie eine Sitzung erstellen, verwaltet Copilot SDK den Gesprächsverlauf, den Toolstatus und den Planungskontext. Dieser Zustand befindet sich standardmäßig im Arbeitsspeicher und verschwindet, wenn die Sitzung endet. Mit aktivierter Persistenz können Sie Sitzungen über Neustarts, Containermigrationen oder sogar unterschiedliche Clientinstanzen hinweg fortsetzen. Eine visuelle Übersicht über den Lebenszyklus des Sitzungszustands finden Sie im github/copilot-sdk Repository.

State	Was ist los

          **Erstellen** | 
          `sessionId` Zugewiesen |

Schnellstart: Erstellen einer reaktivierbaren Sitzung

Der Schlüssel zum Fortsetzen von Sitzungen ist die Bereitstellung Ihres eigenen sessionId (andere SDKs könnten session_id verwenden). Ohne eine generiert das SDK eine zufällige ID, und die Sitzung kann später nicht fortgesetzt werden.

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

const client = new CopilotClient();

// Create a session with a meaningful ID
const session = await client.createSession({
  sessionId: "user-123-task-456",
  model: "gpt-5.2-codex",
});

// Do some work...
await session.sendAndWait({ prompt: "Analyze my codebase" });

// Session state is automatically persisted
// You can safely close the client

Beispiele in Python, Go und C# finden Sie im github/copilot-sdkRepository.

Fortsetzen einer Sitzung

Sie können eine Sitzung fortsetzen, von der sie beendet wurde (Minuten, Stunden oder sogar Tage später). Eine visuelle Übersicht über die wiederaufnahme von clientübergreifenden Sitzungen finden Sie im github/copilot-sdk Repository.

// Resume from a different client instance (or after restart)
const session = await client.resumeSession("user-123-task-456");

// Continue where you left off
await session.sendAndWait({ prompt: "What did we discuss earlier?" });

Beispiele in Python, Go und C# finden Sie im github/copilot-sdk Repository.

Optionen für "Fortsetzen"

Beim Fortsetzen einer Sitzung können Sie optional viele Einstellungen neu konfigurieren. Dies ist nützlich, wenn Sie das Modell ändern, Toolkonfigurationen aktualisieren oder das Verhalten ändern müssen.

Auswahl	Beschreibung
`model`	Ändern des Modells für die fortgesetzte Sitzung
`systemMessage`	Überschreiben oder Erweitern der Systemaufforderung
`availableTools`	Einschränken der verfügbaren Tools
`excludedTools`	Deaktivieren bestimmter Tools
`provider`	Erneutes Bereitstellen von BYOK-Anmeldeinformationen (erforderlich für BYOK-Sitzungen)
`reasoningEffort`	Anpassen der Aufwandsstufe für die Begründung
`streaming`	Aktivieren oder Deaktivieren von Streaming-Antworten
`workingDirectory`	Ändern des Arbeitsverzeichnisses
`configDir`	Konfigurationsverzeichnis außer Kraft setzen
`mcpServers`	MCP-Server konfigurieren
`customAgents`	Konfigurieren von benutzerdefinierten Agents
`agent`	Vorauswahl eines benutzerdefinierten Agents anhand des Namens
`skillDirectories`	Verzeichnisse, aus denen Fähigkeiten geladen werden
`disabledSkills`	Zu deaktivierende Fähigkeiten
`infiniteSessions`	Konfigurieren des unendlichen Sitzungsverhaltens

Beispiel: Modelländerung im Lebenslauf

// Resume with a different model
const session = await client.resumeSession("user-123-task-456", {
  model: "claude-sonnet-4",  // Switch to a different model
  reasoningEffort: "high",   // Increase reasoning effort
});

Verwenden von BYOK mit wieder aufgenommenen Sitzungen

Wenn Sie Ihre eigenen API-Schlüssel verwenden, müssen Sie die Anbieterkonfiguration beim Fortsetzen erneut bereitstellen. API-Schlüssel werden aus Sicherheitsgründen niemals auf dem Datenträger beibehalten.

// Original session with BYOK
const session = await client.createSession({
  sessionId: "user-123-task-456",
  model: "gpt-5.2-codex",
  provider: {
    type: "azure",
    endpoint: "https://my-resource.openai.azure.com",
    apiKey: process.env.AZURE_OPENAI_KEY,
    deploymentId: "my-gpt-deployment",
  },
});

// When resuming, you MUST re-provide the provider config
const resumed = await client.resumeSession("user-123-task-456", {
  provider: {
    type: "azure",
    endpoint: "https://my-resource.openai.azure.com",
    apiKey: process.env.AZURE_OPENAI_KEY,  // Required again
    deploymentId: "my-gpt-deployment",
  },
});

Was beibehalten wird

Der Sitzungsstatus wird gespeichert in ~/.copilot/session-state/{sessionId}/:

~/.copilot/session-state/
└── user-123-task-456/
    ├── checkpoints/           # Conversation history snapshots
    │   ├── 001.json          # Initial state
    │   ├── 002.json          # After first interaction
    │   └── ...               # Incremental checkpoints
    ├── plan.md               # Agent's planning state (if any)
    └── files/                # Session artifacts
        ├── analysis.md       # Files the agent created
        └── notes.txt         # Working documents

Daten	Persistiert?	Hinweise
Aufgezeichnete Unterhaltungen

          ✅ Ja | Vollständiger Nachrichtenthread |

Bewährte Methoden für Sitzungs-ID

Wählen Sie Sitzungs-IDs aus, die Besitz und Zweck codieren. Dies erleichtert die Überwachung und Bereinigung.

Schema	Beispiel	Anwendungsfall

          ❌
          `abc123`
         | Zufällige IDs | Schwer zu überwachen, keine Besitzinformationen |

| ✅ user-{userId}-{taskId} | user-alice-pr-review-42 | Apps mit mehreren Benutzern | | ✅ tenant-{tenantId}-{workflow} | tenant-acme-onboarding | Mehrinstanzenfähige SaaS | | ✅ {userId}-{taskId}-{timestamp} | alice-deploy-1706932800 | Zeitbasierte Bereinigung |

Vorteile strukturierter IDs:

Einfach zu überwachen: "Alle Sitzungen für Benutzer alice anzeigen"
Einfach zu bereinigen: "Alle Sitzungen löschen, die älter als X sind"
Natürliche Zugriffskontrolle: Parsen der Benutzer-ID aus der Sitzungs-ID

Beispiel: Generieren von Sitzungs-IDs

function createSessionId(userId: string, taskType: string): string {
  const timestamp = Date.now();
  return `${userId}-${taskType}-${timestamp}`;
}

const sessionId = createSessionId("alice", "code-review");
// → "alice-code-review-1706932800000"

Ein Beispiel in Python finden Sie im github/copilot-sdk Repository.

Verwalten des Sitzungslebenszyklus

Auflisten aktiver Sitzungen

// List all sessions
const sessions = await client.listSessions();
console.log(`Found ${sessions.length} sessions`);

for (const session of sessions) {
  console.log(`- ${session.sessionId} (created: ${session.createdAt})`);
}

// Filter sessions by repository
const repoSessions = await client.listSessions({ repository: "owner/repo" });

Bereinigen von alten Sitzungen

async function cleanupExpiredSessions(maxAgeMs: number) {
  const sessions = await client.listSessions();
  const now = Date.now();
  
  for (const session of sessions) {
    const age = now - new Date(session.createdAt).getTime();
    if (age > maxAgeMs) {
      await client.deleteSession(session.sessionId);
      console.log(`Deleted expired session: ${session.sessionId}`);
    }
  }
}

// Clean up sessions older than 24 hours
await cleanupExpiredSessions(24 * 60 * 60 * 1000);

Trennen einer Sitzung

Wenn eine Aufgabe abgeschlossen ist, trennen Sie die Verbindung mit der Sitzung explizit, anstatt auf Timeouts zu warten. Dadurch werden Speicherressourcen freigegeben, sitzungsdaten jedoch auf dem Datenträger beibehalten, sodass die Sitzung später noch fortgesetzt werden kann:

try {
  // Do work...
  await session.sendAndWait({ prompt: "Complete the task" });
  
  // Task complete — release in-memory resources (session can be resumed later)
  await session.disconnect();
} catch (error) {
  // Clean up even on error
  await session.disconnect();
  throw error;
}

Jedes SDK stellt idiomatische automatische Bereinigungsmuster bereit:

Sprache	Schema	Beispiel

          **TypeScript** | `Symbol.asyncDispose` | `await using session = await client.createSession(config);` |

Hinweis

          `destroy()` wurde ersetzt und `disconnect()` wird in einer zukünftigen Version entfernt. Bestehender Code funktioniert `destroy()` weiterhin, sollte jedoch migriert werden.

Dauerhaftes Löschen einer Sitzung

Um eine Sitzung und alle zugehörigen Daten dauerhaft vom Datenträger zu entfernen (Aufgezeichnete Unterhaltungen, Planungszustand, Artefakte), verwenden Sie deleteSession. Dies ist unumkehrbar – die Sitzung kann nach dem Löschen nicht fortgesetzt werden:

// Permanently remove session data
await client.deleteSession("user-123-task-456");

Tipp

          `disconnect()` gibt Speicherressourcen frei, behält jedoch Sitzungsdaten auf dem Datenträger für eine spätere Wiederaufnahme bei.

          `deleteSession()` Entfernt dauerhaft alles, einschließlich Dateien auf dem Datenträger.

Automatische Bereinigung: Leerlaufzeitüberschreitung

Das SDK verfügt über ein integriertes 30-Minuten-Leerlauftimeout. Sitzungen ohne Aktivität werden automatisch bereinigt. Für eine visuelle Übersicht über den Ablauf des Leerlauftimeouts sehen Sie sich das github/copilot-sdk-Repository an.

Lauschen Sie auf Leerlaufereignisse, um zu wissen, wann die Arbeit abgeschlossen ist:

session.on("session.idle", (event) => {
  console.log(`Session idle for ${event.idleDurationMs}ms`);
});

Bereitstellungsmuster

Muster 1: Ein CLI-Server pro Benutzer (empfohlen)

Am besten geeignet für: starke Isolation, Mehrinstanzenumgebungen, dynamische Azure-Sitzungen. Ein visuelles Diagramm finden Sie im github/copilot-sdk Repository.

Vorteile:

Vollständige Isolation
Einfache Sicherheit
Einfache Skalierung

Muster 2: Gemeinsam genutzter CLI-Server (ressourceneffizient)

Am besten geeignet für: interne Tools, vertrauenswürdige Umgebungen, ressourcenbeschränkte Setups. Ein visuelles Diagramm finden Sie im github/copilot-sdk Repository.

Anforderungen:

Eindeutige Sitzungs-IDs pro Benutzer
Zugriffssteuerung auf Anwendungsebene
Sitzungs-ID-Überprüfung vor Vorgängen

// Application-level access control for shared CLI
async function resumeSessionWithAuth(
  client: CopilotClient,
  sessionId: string,
  currentUserId: string
): Promise<Session> {
  // Parse user from session ID
  const [sessionUserId] = sessionId.split("-");
  
  if (sessionUserId !== currentUserId) {
    throw new Error("Access denied: session belongs to another user");
  }
  
  return client.resumeSession(sessionId);
}

Dynamische Azure-Sitzungen

Für Serverlose/Containerbereitstellungen, bei denen Container neu gestartet oder migriert werden können, muss das Sitzungsstatusverzeichnis an beständigen Speicher bereitgestellt werden:

# Azure Container Instance example
containers:
  - name: copilot-agent
    image: my-agent:latest
    volumeMounts:
      - name: session-storage
        mountPath: /home/app/.copilot/session-state

volumes:
  - name: session-storage
    azureFile:
      shareName: copilot-sessions
      storageAccountName: myaccount

Ein visuelles Diagramm zur Persistenz des Containerneustarts finden Sie im github/copilot-sdk Repository.

Fortlaufende Sitzungen für langandauernde Workflows

Aktivieren Sie für Workflows, die Kontextbeschränkungen überschreiten könnten, dauerhafte Sitzungen mit automatischer Datenkomprimierung.

const session = await client.createSession({
  sessionId: "long-workflow-123",
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start compaction at 80% context
    bufferExhaustionThreshold: 0.95,      // Block at 95% if needed
  },
});

Hinweis

Schwellenwerte sind Kontextauslastungsverhältnisse (0,0–1,0), keine absolute Tokenanzahl.

Einschränkungen und Überlegungen

Einschränkung	Beschreibung	Milderung

          **BYOK-Erneute Authentifizierung** | API-Schlüssel werden nicht beibehalten | Schlüssel in Ihrem geheimen Manager speichern; "On Resume" bereitstellen |

| Schreibbarer Speicher | ~/.copilot/session-state/ muss schreibbar sein | Bereitstellen persistenter Volumes in Containern | | Keine Sitzungssperre | Gleichzeitiger Zugriff auf dieselbe Sitzung ist nicht definiert | Implementieren der Sperrung oder Warteschlange auf Anwendungsebene | | Der Toolstatus wurde nicht beibehalten. | Der Status des In-Memory-Tools geht verloren. | Entwerfen Sie Werkzeuge, die zustandslos sind oder ihren eigenen Zustand speichern |

Verwaltung gleichzeitigen Zugriffs

Das SDK bietet keine integrierte Sitzungssperre. Wenn mehrere Clients auf dieselbe Sitzung zugreifen können, sollten Sie sicherstellen, dass jede Sitzung gesperrt ist, um Entführer zu verhindern:

// Option 1: Application-level locking with Redis
import Redis from "ioredis";

const redis = new Redis();

async function withSessionLock<T>(
  sessionId: string,
  fn: () => Promise<T>
): Promise<T> {
  const lockKey = `session-lock:${sessionId}`;
  const acquired = await redis.set(lockKey, "locked", "NX", "EX", 300);
  
  if (!acquired) {
    throw new Error("Session is in use by another client");
  }
  
  try {
    return await fn();
  } finally {
    await redis.del(lockKey);
  }
}

// Usage
await withSessionLock("user-123-task-456", async () => {
  const session = await client.resumeSession("user-123-task-456");
  await session.sendAndWait({ prompt: "Continue the task" });
});

Zusammenfassung

Funktion	So verwenden Sie

          **Reaktivierbare Sitzung erstellen** | Stellen Sie Ihre eigene `sessionId` |

| Sitzung fortsetzen | client.resumeSession(sessionId) | | BYOK fortsetzen | Konfiguration erneut bereitstellen provider | | Sitzungen auflisten | client.listSessions(filter?) | | Verbindung mit der aktiven Sitzung trennen | session.disconnect()— gibt Speicherressourcen frei; Sitzungsdaten auf dem Datenträger werden für die Wiederaufnahme beibehalten. | | Sitzung dauerhaft löschen | client.deleteSession(sessionId)— entfernt dauerhaft alle Sitzungsdaten vom Datenträger; Kann nicht fortgesetzt werden | | Containerisierte Bereitstellung | Zum persistenten Speicher einbinden ~/.copilot/session-state/ |

Wer kann dieses Feature verwenden?

In diesem Artikel

Schnellstart: Erstellen einer reaktivierbaren Sitzung

Fortsetzen einer Sitzung

Optionen für "Fortsetzen"

Beispiel: Modelländerung im Lebenslauf

Verwenden von BYOK mit wieder aufgenommenen Sitzungen

Was beibehalten wird

Bewährte Methoden für Sitzungs-ID

Beispiel: Generieren von Sitzungs-IDs

Verwalten des Sitzungslebenszyklus

Auflisten aktiver Sitzungen

Bereinigen von alten Sitzungen

Trennen einer Sitzung

Dauerhaftes Löschen einer Sitzung

Automatische Bereinigung: Leerlaufzeitüberschreitung

Bereitstellungsmuster

Muster 1: Ein CLI-Server pro Benutzer (empfohlen)

Muster 2: Gemeinsam genutzter CLI-Server (ressourceneffizient)

Dynamische Azure-Sitzungen

Fortlaufende Sitzungen für langandauernde Workflows

Einschränkungen und Überlegungen

Verwaltung gleichzeitigen Zugriffs

Zusammenfassung