# Reprise de session et persistance Ce guide vous guide tout au long des fonctionnalités de persistance de session du Kit de développement logiciel (SDK) : comment suspendre le travail, le reprendre ultérieurement et gérer les sessions dans les environnements de production. ## Fonctionnement des sessions Lorsque vous créez une session, l’interface cli Copilot gère l’historique des conversations, l’état de l’outil et le contexte de planification. Par défaut, cet état vit en mémoire et disparaît lorsque la session se termine. Une fois la persistance activée, vous pouvez reprendre des sessions entre les redémarrages, les migrations de conteneurs ou même différentes instances clientes. ![Diagramme : Organigramme montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-session-persistence-diagram-0.png) | State | Que se passe-t-il ? | | --------------------- | ------------------------------------------------------ | | **Créer** | | | `session_id` Attribué | | | **Active** | Envoyer des invites, des appels d’outils, des réponses | | **suspendu** | État enregistré sur le disque | | **Resume** | État chargé à partir du disque | ## Démarrage rapide : création d’une session pouvant être reprise La clé pour permettre la reprise des sessions consiste à fournir votre propre `session_id`. Sans un, le SDK génère un ID aléatoire et la session ne peut pas être reprise ultérieurement. ### TypeScript ```typescript 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 ``` ### Python ```python from copilot import CopilotClient from copilot.session import PermissionHandler client = CopilotClient() await client.start() # Create a session with a meaningful ID session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", session_id="user-123-task-456") # Do some work... await session.send_and_wait("Analyze my codebase") # Session state is automatically persisted ``` ### Allez ```golang ctx := context.Background() client := copilot.NewClient(nil) // Create a session with a meaningful ID session, _ := client.CreateSession(ctx, &copilot.SessionConfig{ SessionID: "user-123-task-456", Model: "gpt-5.2-codex", }) // Do some work... session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Analyze my codebase"}) // Session state is automatically persisted ``` ### C# (.NET) ```csharp using GitHub.Copilot; var client = new CopilotClient(); // Create a session with a meaningful ID var session = await client.CreateSessionAsync(new SessionConfig { SessionId = "user-123-task-456", Model = "gpt-5.2-codex", }); // Do some work... await session.SendAndWaitAsync(new MessageOptions { Prompt = "Analyze my codebase" }); // Session state is automatically persisted ``` ## Reprise d’une session Plus tard, minutes, heures ou même jours, vous pouvez reprendre la session à partir de l’endroit où vous vous êtes arrêté. ![Diagramme : Organigramme montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-session-persistence-diagram-1.png) ### TypeScript ```typescript // 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?" }); ``` ### Python ```python # Resume from a different client instance (or after restart) session = await client.resume_session("user-123-task-456", on_permission_request=PermissionHandler.approve_all) # Continue where you left off await session.send_and_wait("What did we discuss earlier?") ``` ### Allez ```golang ctx := context.Background() // Resume from a different client instance (or after restart) session, _ := client.ResumeSession(ctx, "user-123-task-456", nil) // Continue where you left off session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What did we discuss earlier?"}) ``` ### C# (.NET) ```csharp // Resume from a different client instance (or after restart) var session = await client.ResumeSessionAsync("user-123-task-456"); // Continue where you left off await session.SendAndWaitAsync(new MessageOptions { Prompt = "What did we discuss earlier?" }); ``` ## Options de reprise Lors de la reprise d’une session, vous pouvez éventuellement reconfigurer de nombreux paramètres. Cela est utile lorsque vous devez modifier le modèle, mettre à jour les configurations de l’outil ou modifier le comportement. | Option | Description | | ------------------ | ------------------------------------------------------------------------------------------ | | `model` | Modifier le modèle de la session reprise | | `systemMessage` | Remplacer ou étendre l’invite système | | `availableTools` | Restreindre les outils disponibles | | `excludedTools` | Désactiver des outils spécifiques | | `provider` | Fournir à nouveau des informations d’identification BYOK (requises pour les sessions BYOK) | | `reasoningEffort` | Ajuster le niveau d’effort de raisonnement | | `streaming` | Activer/désactiver les réponses de diffusion en continu | | `workingDirectory` | Modifier le répertoire de travail | | `configDir` | Remplacer le répertoire de configuration | | `mcpServers` | Configurer les serveurs MCP | | `customAgents` | Configurer des agents personnalisés | | `agent` | Pré-sélection d’un agent personnalisé par nom | | `skillDirectories` | Répertoires à partir duquel charger des compétences | | `disabledSkills` | Compétences à désactiver | | `infiniteSessions` | Configurer le comportement de session infinie | ### Exemple : changement de modèle à la reprise ```typescript // 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 }); ``` ## Utilisation de BYOK (apportez votre propre clé) avec des sessions reprises Lorsque vous utilisez vos propres clés API, vous devez fournir à nouveau la configuration du fournisseur lors de la reprise. Les clés API ne sont jamais conservées sur le disque pour des raisons de sécurité. ```typescript // 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", }, }); ``` ## Qu’est-ce qui est conservé ? L’état de session est enregistré dans `~/.copilot/session-state/{sessionId}/`: ```text ~/.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 ``` | Data | Persisté? | Remarques | | -------------------------------- | --------------------------------- | --------- | | Historique des conversations | | | | ✅ Oui | Fil de message complet | | | Résultats des appels d’outil | | | | ✅ Oui | Mis en cache pour le contexte | | | État de planification de l’agent | | | | ✅ Oui | Fichier `plan.md` | | | Artefacts de session | | | | ✅ Oui | Dans `files/` le répertoire | | | Clés fournisseur/API | | | | ❌ Non | Sécurité : doit re-fournir | | | État de l’outil en mémoire | | | | ❌ Non | Les outils doivent être sans état | | ## Bonnes pratiques relatives à l’ID de session Choisissez les ID de session qui encodent la propriété et l’objectif. Cela facilite beaucoup l’audit et le nettoyage. | Pattern | Example | Cas d’usage | | ------------------------------- | -------------------------------------------------------- | ----------- | | ❌ | | | | `abc123` | | | | ID aléatoires | Difficile à auditer, aucune information sur la propriété | | | ✅ | | | | `user-{userId}-{taskId}` | | | | `user-alice-pr-review-42` | Applications multi-utilisateurs | | | ✅ | | | | `tenant-{tenantId}-{workflow}` | | | | `tenant-acme-onboarding` | SaaS multilocataire | | | ✅ | | | | `{userId}-{taskId}-{timestamp}` | | | | `alice-deploy-1706932800` | Nettoyage basé sur le temps | | **Avantages des ID structurés :** * Simple à auditer : « Afficher toutes les sessions pour l’utilisateur alice » * Nettoyer facilement : « Supprimer toutes les sessions antérieures à X » * Contrôle d’accès naturel : Analyser l’ID utilisateur à partir de l’ID de session ### Exemple : génération d’ID de session ```typescript 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" ``` ```python import time def create_session_id(user_id: str, task_type: str) -> str: timestamp = int(time.time()) return f"{user_id}-{task_type}-{timestamp}" session_id = create_session_id("alice", "code-review") # → "alice-code-review-1706932800" ``` ## Gestion du cycle de vie des sessions ### Liste des sessions actives ```typescript // 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" }); ``` ### Nettoyage des anciennes sessions ```typescript 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); ``` ### Déconnexion d’une session (`disconnect`) Lorsqu’une tâche est terminée, déconnectez-vous de la session explicitement plutôt que d’attendre des délais d’expiration. Cette opération libère des ressources en mémoire, mais **conserve les données de session sur le disque**, de sorte que la session peut toujours être reprise ultérieurement : ```typescript 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; } ``` Chaque KIT SDK fournit également des modèles de nettoyage automatique idiomatiques : | Language | Pattern | Example | | ------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | **TypeScript** | `Symbol.asyncDispose` | `await using session = await client.createSession(config);` | | **Python** | | | | `async with` gestionnaire de contexte | `async with await client.create_session(on_permission_request=handler) as session:` | | | **C#** | `IAsyncDisposable` | `await using var session = await client.CreateSessionAsync(config);` | | **Go** | `defer` | `defer session.Disconnect()` | > \[!NOTE] > `destroy()` est déconseillé au profit de `disconnect()`. Le code existant utilise `destroy()` continuera de fonctionner, mais doit être migré. ### Suppression définitive d’une session (`deleteSession`) Pour supprimer définitivement une session et toutes ses données du disque (historique des conversations, état de planification, artefacts), utilisez `deleteSession`. Cela est irréversible : la session **ne peut pas** être reprise après la suppression : ```typescript // Permanently remove session data await client.deleteSession("user-123-task-456"); ``` > **`disconnect()` vs `deleteSession()`:**`disconnect()` libère des ressources en mémoire, mais conserve les données de session sur le disque pour une reprise ultérieure. `deleteSession()` supprime définitivement tout, y compris les fichiers sur le disque. ## Nettoyage automatique : temporisation d'inactivité Par défaut, les sessions **n’ont pas de délai d’inactivité** et vivent indéfiniment jusqu’à ce qu’elles aient été explicitement déconnectées ou supprimées. Vous pouvez éventuellement configurer un délai d’inactivité à l’échelle du serveur via `CopilotClientOptions.sessionIdleTimeoutSeconds`: ```typescript const client = new CopilotClient({ sessionIdleTimeoutSeconds: 30 * 60, // 30 minutes }); ``` Lorsqu’un délai d’expiration est configuré, les sessions sans activité pendant cette durée sont automatiquement nettoyées. Définissez sur `0` ou omettez pour désactiver. > \[!NOTE] > Cette option s’applique uniquement lorsque le Kit de développement logiciel (SDK) génère le processus d’exécution. Lors de la connexion à un serveur existant via `cliUrl`, la configuration du délai d’expiration du serveur s’applique. ![Diagramme : Organigramme montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-session-persistence-diagram-2.png) Les sessions avec travail actif (commandes en cours d’exécution, assistants en arrière-plan) sont toujours protégées contre le nettoyage inactif, quel que soit le paramètre de délai d’expiration. Surveillez les événements d’inactivité pour réagir à l’inactivité de la session : ```typescript session.on("session.idle", (event) => { console.log(`Session idle for ${event.idleDurationMs}ms`); }); ``` ## Modèles de déploiement ### Modèle 1 : un serveur CLI par utilisateur (recommandé) Idéal pour : isolation forte, environnements multilocataires, Azure sessions dynamiques. ![Diagramme : Organigramme montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-session-persistence-diagram-3.png) \*\*Avantages:\*\*✅ Isolation complète | ✅ Sécurité simple | ✅ Mise à l’échelle simple ### Modèle 2 : serveur CLI partagé (ressource efficace) Idéal pour : outils internes, environnements approuvés, configurations contraintes de ressources. ![Diagramme : Organigramme montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-session-persistence-diagram-4.png) **Exigences:** * ⚠️ ID de session uniques par utilisateur * ⚠️ Contrôle d’accès au niveau de l’application * ⚠️ Validation de l’ID de session avant les opérations ```typescript // Application-level access control for shared CLI async function resumeSessionWithAuth( client: CopilotClient, sessionId: string, currentUserId: string ): Promise { // 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); } ``` ## sessions dynamiques Azure Pour les déploiements serverless/conteneur où les conteneurs peuvent redémarrer ou migrer : ### Monter un stockage persistant Le répertoire d’état de session doit être monté sur un stockage persistant : ```yaml # 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 ``` ![Diagramme : Organigramme montrant le processus décrit.](/assets/images/help/copilot/copilot-sdk/features-session-persistence-diagram-5.png) **La session survit aux redémarrages du conteneur !** ## Sessions infinies pour les workflows de longue durée Pour les flux de travail qui peuvent dépasser les limites de contexte, activez des sessions infinies avec compactage automatique : ```typescript 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 }, }); ``` > \[!NOTE] > Les seuils sont des ratios d’utilisation du contexte (0,0-1,0), et non des nombres de jetons absolus. Pour plus d’informations, consultez [autoTITLE](/fr/copilot/how-tos/copilot-sdk/troubleshooting/compatibility) . ## Limitations et considérations | Limitation | Description | Atténuation | | ------------------------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Ré-authentification BYOK** | Les clés API ne sont pas persistantes | Stockez les clés dans votre gestionnaire de secrets ; fournissez-les lors de la reprise | | **Stockage accessible en écriture** | | | | `~/.copilot/session-state/` doit être accessible en écriture | Monter un volume persistant dans des conteneurs | | | **Aucun verrouillage de session** | L’accès simultané à la même session n’est pas défini | Implémenter le verrouillage ou la file d’attente au niveau de l’application | | **État de l’outil non persistant** | L’état de l’outil en mémoire est perdu | Conception d’outils qui soient sans état ou conservent leur propre état | ### Gestion de l’accès simultané Le Kit de développement logiciel (SDK) ne fournit pas de verrouillage de session intégré. Si plusieurs clients peuvent accéder à la même session : ```typescript // Option 1: Application-level locking with Redis import Redis from "ioredis"; const redis = new Redis(); async function withSessionLock( sessionId: string, fn: () => Promise ): Promise { 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" }); }); ``` ## Résumé | Fonctionnalité | Utilisation | | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | **Créer une session pouvant être reprise** | Fournissez vos propres `sessionId` | | **Reprendre la session** | `client.resumeSession(sessionId)` | | **Reprise BYOK** | Re-fournir la `provider` configuration | | **Répertorier les sessions** | `client.listSessions(filter?)` | | **Se déconnecter de la session active** | | | `session.disconnect()`— libère des ressources en mémoire ; les données de session sur le disque sont conservées pour la reprise | | | **Supprimer une session définitivement** | | | `client.deleteSession(sessionId)`: supprime définitivement toutes les données de session du disque ; ne peut pas être repris | | | **Déploiement en conteneur** | Monter `~/.copilot/session-state/` dans un stockage persistant | ## Étapes suivantes * [Hooks de session](/fr/copilot/how-tos/copilot-sdk/hooks/hooks-overview) - Personnaliser le comportement de session avec des hooks * [Compatibilité du Kit de développement logiciel (SDK) et de l’interface](/fr/copilot/how-tos/copilot-sdk/troubleshooting/compatibility) - Comparaison des fonctionnalités sdk et CLI * [Guide de débogage](/fr/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - Résoudre les problèmes de session