Espaces de travail pour agents IA

IMPORTANT : Avant de faire quoi que ce soit, vous DEVEZ lire BASE_SKILL.md dans le répertoire de cette skill. Il contient des conseils essentiels sur le débogage, la gestion des erreurs, la gestion d'état, le déploiement et la configuration du projet. Ces règles et modèles s'appliquent à tous les travaux RivetKit. Tout ce qui suit suppose que vous avez déjà lu et compris ce document.

Exemples fonctionnels

Si vous avez besoin d'une implémentation de référence, consultez le code d'exemple fonctionnant brut dans ces templates :

agent-os

Modèles pour donner à chaque agent IA son propre ordinateur avec agentOS : un Actor Rivet par agent qui possède un OS portable et léger en processus exécuté sur Wasm et V8. Utilisez-le pour les interpréteurs de code qui conservent l'état entre les exécutions, les agents qui livrent des artefacts derrière des URL d'aperçu partageables, les environnements de développement par utilisateur et les agents de maintenance programmés. agentOS est en préversion et l'API peut changer.

Cette entrée concerne la création d'un espace de travail pour un agent. Pour la mémoire de conversation, les files de messages et les modèles de chat en streaming, voir Agent IA.

Code de démarrage

La collection agent-os est du code de référence, un sous-exemple par capacité ; traitez-le comme des modèles à copier dans votre projet plutôt que comme une application clés en main. L'exemple agent-os-e2e est la procédure pas à pas complète de bout en bout.

Exemple	Code de démarrage	À utiliser quand
Hello World	GitHub	Vous voulez la boucle minimale : démarrer une VM en mode lazy au premier action, écrire un fichier, le relire.
Système de fichiers	GitHub	L'agent a besoin de la surface de fichiers complète : listage récursif, stat, déplacement, suppression et montages personnalisés.
Git	GitHub	L'agent travaille avec des vrais dépôts git à l'intérieur de l'espace de travail : init, commit, branch et clone via `exec`.
Processus	GitHub	L'agent exécute des commandes shell avec pipes et des programmes spawned longue durée.
Réseau	GitHub	L'agent sert du HTTP à l'intérieur de la VM et vous avez besoin de `vmFetch` ou d'URLs d'aperçu signées.
Cron	GitHub	L'espace de travail exécute des commandes programmées ou un travail d'agent récurrent.
Outils	GitHub	Vous voulez que vos fonctions backend soient exposées comme des commandes CLI à l'intérieur de l'espace de travail.
Session agent	GitHub	Vous pilotez une session d'agent de codage Pi à l'intérieur de l'espace de travail. Nécessite `ANTHROPIC_API_KEY`.
Montage sandbox	GitHub	L'agent a besoin de binaires natifs ou d'un vrai OS, montés dans la VM à partir d'un sandbox Docker. Nécessite Docker.
Procédure pas à pas de bout en bout	GitHub	Vous voulez un script exécutable couvrant les fichiers, les processus, les URLs d'aperçu et une session d'agent Pi en streaming.

Configuration

Tout le backend est un registre avec un seul actor agentOs() :

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: { software: [common, pi] },
});

export const registry = setup({ use: { vm } });
registry.start();

Voir le Démarrage rapide pour le côté client et la disposition du projet.

Modèle d'espace de travail

Un actor par espace de travail, clé comme identité. client.vm.getOrCreate(["my-agent"]) donne à chaque agent son propre espace de travail ; clé par id utilisateur pour les environnements de développement par utilisateur. Chaque espace de travail a son propre système de fichiers, processus et réseau sans état partagé et sans contamination croisée (voir l'aperçu).
Les packages logiciels choisissent ce qui est installé. agentOS démarre sans aucune commande installée. L'option software installe des packages comme @rivet-dev/agent-os-common (un méta-package d'outils CLI Wasm : coreutils, sed, grep, gawk, findutils, diffutils, tar et gzip), @rivet-dev/agent-os-git (git) et @rivet-dev/agent-os-pi (l'agent de codage Pi). Voir Logiciels.
La VM démarre en mode lazy et se met en veille quand inactive. Le premier action démarre la VM (les clients voient un événement vmBooted) ; quand rien n'est actif, l'actor se met en veille et diffuse vmShutdown, puis se réveille au prochain action.

Ce qui survit à un cycle veille/réveil (voir Persistance) :

Données	À travers veille/réveil
Transcriptions de session et historique d'événements	Persistent dans SQLite actor sous forme de flux d'événements. `listPersistedSessions` et `getSessionEvents` les relisent sans démarrer la VM, et `resumeSession` reprend une session dans une VM redémarrée.
Jetons d'URL d'aperçu signés	Persistent dans SQLite actor. Les demandes sont validées par rapport au jeton stocké et la VM redémarre en mode lazy pour les servir, donc les URLs d'aperçu continuent de fonctionner après la veille.
Fichiers	Persistent quand le montage est sauvegardé par un driver persistant (base de données, S3 ou montage sandbox). Les montages en mémoire réapparaissent vides au réveil.
Processus, shells et travaux cron	Ne persistent pas. Redémarrez les processus longue durée et reprogrammez les travaux cron au réveil (extension recommandée).

L'actor se maintient éveillé tant que des sessions, des processus, des shells ou des hooks sont actifs, puis se met en veille après une période de grâce.

Visite des capacités

Zone	À utiliser pour	Actions clés	Docs	Exemple
Système de fichiers	Donner à l'agent un arbre de fichiers à lire et écrire	`readFile`, `writeFile`, `mkdir`, `readdir`, `move`	Système de fichiers	GitHub
Processus	Exécuter des commandes et des programmes longue durée	`exec`, `spawn`, `waitProcess`, `killProcess`	Processus	GitHub
Shells	Terminaux interactifs avec sortie en streaming	`openShell`, `writeShell`, `resizeShell`, `closeShell`	Processus	Aucun exemple standalone
Réseau et URLs d'aperçu	Atteindre les services à l'intérieur de la VM et les partager externement	`vmFetch`, `createSignedPreviewUrl`, `expireSignedPreviewUrl`	Réseau	GitHub
Cron	Commandes programmées et sessions d'agent récurrentes	`scheduleCron`, `listCronJobs`, `cancelCronJob`	Cron	GitHub
Sessions agent	Piloter un agent de codage à l'intérieur de l'espace de travail	`createSession`, `sendPrompt`, `resumeSession`, `closeSession`	Sessions	GitHub

Deux détails dignes d'intérêt dès le départ :

createSignedPreviewUrl retourne un chemin relatif plus le jeton et l'expiration. Construisez l'URL complète avec la méthode getGatewayUrl() du handle client ; c'est une méthode client, pas une action actor.
Programmez les travaux cron via l'actor avec uniquement les types d'action exec et session. Les actions cron de rappel sont définies dans le code serveur et ne se sérialisent pas à travers listCronJobs.

Piloter une session d'agent de codage

Seul l'agent Pi (@rivet-dev/agent-os-pi) est actuellement supporté comme agent de session ; Amp, Claude Code, Codex et OpenCode arrivent bientôt. Voir Sessions.

createSession("pi", { env: { ANTHROPIC_API_KEY } }) retourne un sessionId. La VM n'hérite pas du process.env de l'hôte, donc les clés API sont passées explicitement par session ou conservées côté serveur via la passerelle LLM.
Ouvrez une connexion temps réel et abonnez-vous à sessionEvent pour streamer la sortie de l'agent, comme les chunks de messages, pendant qu'il travaille.
sendPrompt(sessionId, ...) commence un tour ; cancelPrompt en arrête un en cours.
Quand l'agent demande à utiliser un outil, les clients reçoivent un événement permissionRequest et répondent avec respondPermission, ou le serveur approuve automatiquement avec le hook de config onPermissionRequest (voir Permissions).
Les transcriptions sont persistées automatiquement au format de transcription universel (Agent Communication Protocol, ACP). Après la veille, resumeSession poursuit une session dans la VM redémarrée, et listPersistedSessions plus getSessionEvents lisent l'historique sans démarrer la VM du tout.

Outils hôte

Exposez vos fonctions backend à l'agent comme des commandes CLI à l'intérieur de l'espace de travail. Définissez une boîte à outils avec toolKit() et hostTool() (fonctions JavaScript validées par schéma Zod sur l'hôte), passez-la via agentOs({ options: { toolKits: [...] } }), et elle s'installe comme une commande comme agentos-weather forecast --city Paris --days 3 et s'injecte dans le prompt système de l'agent. L'agent appelle votre backend sans points de terminaison HTTP ou serveurs MCP à mettre en place, et les outils en forme CLI sont compatibles avec le mode code pour d'énormes économies de tokens. Voir Outils et l'exemple d'outils.

Quand monter un sandbox complet

agentOS n'est pas un remplacement pour les sandboxes ; il est conçu pour fonctionner à côté d'eux. Quand un espace de travail a besoin de binaires natifs, de navigateurs, de compilation ou d'automatisation de bureau, utilisez le montage sandbox : démarrez un sandbox Docker avec SandboxAgent.start({ sandbox: docker() }), projetez son système de fichiers dans la VM comme un répertoire natif (par exemple /sandbox) avec createSandboxFs, et exposez le contrôle des processus sandbox comme outils hôte avec createSandboxToolkit. Les actions du système de fichiers comme writeFile et readFile se projettent transparemment à travers le montage tandis que les charges de travail lourdes s'exécutent dans le conteneur.

Voir Montage sandbox pour le modèle hybride et agentOS vs Sandboxes pour quand chaque côté l'emporte : la VM légère a un démarrage à froid quasi nul (~6 ms) et s'installe avec npm install, tandis que les sandboxes sont des environnements Linux complets facturés par seconde de disponibilité.

Architecture

Sujet	Résumé
Topologie	Un actor `vm[workspaceId]` par agent ou par utilisateur ; la clé de l'actor est l'identité de l'espace de travail.
Entrée	Actions actor pour les fichiers, processus, réseau, cron et sessions ; une connexion temps réel pour les événements en streaming.
Streaming	`sessionEvent` par événement agent, `processOutput` et `processExit` pour les processus spawned, `shellData` pour les shells interactifs.
Persistance	Transcriptions de session, historique d'événements et jetons d'aperçu dans SQLite actor ; les fichiers persistent à travers les montages persistants.

Actors

Clé : vm[workspaceId], par exemple client.vm.getOrCreate(["my-agent"])
Responsabilité : Possède un espace de travail. Démarre la VM en mode lazy au premier action, sert toutes les actions de capacité, proxy les demandes d'URL d'aperçu signées dans le réseau virtuel de la VM et persist les sessions et jetons dans SQLite actor.
Actions (groupées ; les plus essentielles de chaque zone)
- Système de fichiers : readFile, writeFile, mkdir, readdir, readdirRecursive, stat, exists, move, deleteFile
- Processus : exec, spawn, writeProcessStdin, waitProcess, listProcesses, killProcess
- Shells : openShell, writeShell, resizeShell, closeShell
- Réseau : vmFetch, createSignedPreviewUrl, expireSignedPreviewUrl
- Cron : scheduleCron, listCronJobs, cancelCronJob
- Sessions : createSession, sendPrompt, cancelPrompt, respondPermission, resumeSession, closeSession, destroySession, listPersistedSessions, getSessionEvents
Files d'attente
- Aucune
Événements
- vmBooted
- vmShutdown
- sessionEvent
- permissionRequest
- processOutput
- processExit
- shellData
- cronEvent
État
- SQLite
- agent_os_sessions et agent_os_session_events (métadonnées de session plus événements de transcript ordonnés par seq)
- agent_os_preview_tokens (jetons d'URL d'aperçu signés avec expiration)
- agent_os_fs_entries (contenu de fichier pour les montages basés sur base de données)

Cycle de vie

sequenceDiagram
    participant C as Client
    participant A as vm actor
    participant V as agentOS VM
    participant P as Pi session

    C->>A: getOrCreate(["my-agent"])
    C->>A: writeFile("/tmp/hello.txt", ...)
    Note over A,V: le premier action démarre la VM
    A-->>C: vmBooted
    C->>A: exec("echo hello | tr a-z A-Z")
    A->>V: exécuter la commande
    V-->>A: {exitCode: 0, stdout}
    C->>A: spawn("node", ["/tmp/server.mjs"])
    C->>A: createSignedPreviewUrl(8080, 60)
    A-->>C: {path, token, expiresAt}
    C->>A: fetch(gatewayUrl + path)
    Note over A: jeton vérifié dans SQLite, demande proxyée dans le réseau VM
    C->>A: createSession("pi", {env})
    A->>P: démarrer la session
    C->>A: sendPrompt(sessionId, ...)
    loop sortie agent en streaming
        P-->>A: événement agent
        A-->>C: sessionEvent
    end
    Note over A: inactif, se met en veille après période de grâce (vmShutdown)
    C->>A: resumeSession(sessionId)
    Note over A,V: le réveil redémarre la VM, restaurant transcriptions, jetons d'aperçu et montages persistants

Liste de contrôle de sécurité

Authentifiez les connexions : Ajoutez le hook onBeforeConnect dans la config agentOs() pour que seuls les appelants autorisés accèdent à un espace de travail. Les demandes d'URL d'aperçu signées l'ignorent délibérément car le jeton est le credential ; les navigateurs accédant à une URL d'aperçu ne peuvent pas fournir les params de connexion actor.
Limitez l'utilisation d'outils d'agent avec des permissions : Les demandes de permission de session se diffusent comme événements permissionRequest pour approbation avec intervention humaine via respondPermission, ou exécutent une politique onPermissionRequest côté serveur pour les pipelines automatisés. Voir Permissions.
Traitez les URLs d'aperçu comme des credentials bearer : Les jetons sont des valeurs aléatoires de 32 caractères avec une expiration par défaut d'1 heure et un maximum de 24 ; révoquez tôt avec expireSignedPreviewUrl. Les réponses d'aperçu portent des en-têtes CORS permissifs, donc ne servez pas de données privées sur un port d'aperçu sans auth au niveau de l'app.
Gardez les credentials LLM hors du navigateur : Créez les sessions depuis du code serveur de confiance avec la clé dans l'env createSession, ou gardez les clés entièrement côté serveur avec la passerelle LLM. Les clés de session sont injectées dans l'environnement de session à l'intérieur de la VM et ne sont jamais stockées dans la config actor ou SQLite.
Traitez les sandboxes montés comme leur propre limite de confiance : Un sandbox monté est un environnement Linux complet en dehors de l'isolat Wasm et V8 de l'espace de travail. Limitez ce que son réseau et son système de fichiers peuvent atteindre avant de le projeter dans la VM d'un agent.
Définissez les limites de ressources et de coûts : Limitez la mémoire et CPU par espace de travail (maxMemoryMb, maxCpuPercent, voir Sécurité). Les sessions, processus et shells actifs maintiennent l'actor éveillé, donc ajoutez des plafonds de session par espace de travail et des budgets de token comme extension recommandée.

ai-agent-workspace

Espaces de travail pour agents IA

Exemples fonctionnels

Code de démarrage

Configuration

Modèle d'espace de travail

Visite des capacités

Piloter une session d'agent de codage

Outils hôte

Quand monter un sandbox complet

Architecture

Liste de contrôle de sécurité

Carte de référence

Actors

Agent Os

Clients

Connect

Cookbook

Général

Auto-hébergement

Skills similaires