Agents en bac à sable

Un bac à sable fournit à l’agent un environnement d’exécution isolé de type Unix, avec un système de fichiers, un shell, des paquets installés, des données montées, des ports exposés, des instantanés et un accès contrôlé aux systèmes externes.

Les workflows d’agents deviennent fragiles lorsque le modèle a besoin d’un tel espace de travail, mais ne reçoit que le contexte du prompt. Pour traiter de nombreux documents, produire des artefacts, exécuter des commandes, afficher des aperçus ou reprendre une tâche interrompue, l’agent a besoin d’un environnement qu’il peut inspecter et modifier.

Les versions TypeScript et Python du SDK Agents prennent en charge les agents en bac à sable.

Ce guide porte sur les bacs à sable du SDK Agents, où votre application exécute le harnais. Pour utiliser un harnais géré par OpenAI, consultez Connecter un bac à sable à l’API Agents.

Utilisez un bac à sable lorsque l’agent doit manipuler des fichiers, exécuter des commandes, monter un espace documentaire, produire des artefacts, exposer un service ou reprendre une tâche ultérieurement en retrouvant son état.

Le harnais et l’environnement de calcul ont des responsabilités distinctes. Le harnais constitue le plan de contrôle autour du modèle. Il gère la boucle de l’agent, les appels au modèle, le routage des appels d’outils, les transferts entre agents, les approbations, le traçage, la reprise après incident et l’état de l’exécution. L’environnement de calcul constitue le plan d’exécution du bac à sable. C’est là que, sous la direction du modèle, l’agent lit et écrit des fichiers, exécute des commandes, installe des dépendances, utilise les volumes montés, expose des ports et enregistre des instantanés de l’état.

Cette séparation permet à votre application de conserver les opérations sensibles du plan de contrôle dans une infrastructure de confiance, tandis que le bac à sable prend en charge l’exécution selon les modalités du fournisseur. Le bac à sable peut exécuter du code sur des fichiers avec des identifiants aux droits limités et des montages ciblés. Le harnais peut gérer l’authentification, la facturation, les journaux d’audit, la vérification humaine et l’état nécessaire à la reprise indépendamment de chaque conteneur.

Quand utiliser un bac à sable

Utilisez un bac à sable lorsque, pour répondre, l’agent doit effectuer des opérations dans un espace de travail isolé et que le raisonnement à partir du seul contexte du prompt ne suffit pas.

Voici quelques situations courantes :

• La tâche nécessite un répertoire de documents qu’un seul prompt ne suffit pas à fournir.
• L’agent doit écrire des fichiers que votre application pourra inspecter ultérieurement.
• L’agent a besoin de commandes, de paquets ou de scripts pour accomplir la tâche.
• Le workflow produit des artefacts, par exemple des fichiers Markdown, CSV ou JSONL, des captures d’écran ou des sites web générés.
• Un service, un notebook ou un aperçu de rapport doit être accessible sur un port exposé.
• Le travail s’interrompt pour une vérification humaine, puis reprend dans le même espace de travail.

Si votre workflow ne nécessite qu’une réponse courte du modèle et n’a pas besoin d’un espace de travail persistant, appelez directement l’API Responses ou utilisez le moteur d’exécution de base du SDK Agents sans bac à sable.

Si l’agent n’utilise le shell qu’occasionnellement, commencez par l’outil de shell distant décrit dans Utilisation des outils. Utilisez des agents en bac à sable si votre produit prévoit d’isoler l’espace de travail, de choisir le fournisseur du bac à sable ou de restaurer l’état du système de fichiers pour reprendre une tâche.

Ce qu’apporte un bac à sable

Un SandboxAgent reste un Agent. Il conserve l’interface habituelle d’un agent, notamment instructions, prompt, tools, handoffs, les serveurs MCP, les paramètres du modèle, les sorties structurées, les garde-fous et les hooks. Ce qui change, c’est le périmètre d’exécution. Le moteur d’exécution prépare l’agent pour une session active de bac à sable qui gère les fichiers, les commandes, les ports et l’isolation propre au fournisseur.

Définissez les paramètres par défaut propres au bac à sable sur SandboxAgent. Pour chaque exécution, indiquez les choix relatifs à la session dans la configuration du bac à sable de cette exécution.

Un agent en bac à sable conserve aussi la même notion de tour. Un tour correspond à une étape du modèle. Il peut comprendre plusieurs commandes shell ou actions dans le bac à sable. Certaines opérations peuvent se dérouler entièrement dans la couche d’exécution du bac à sable. Le moteur d’exécution de l’agent ne consomme un tour supplémentaire que s’il a besoin d’une nouvelle réponse du modèle après ces opérations.

Création de l’espace de travail

Manifest décrit le contenu et l’organisation souhaités au démarrage d’un nouvel espace de travail en bac à sable. Utilisez-le pour définir les fichiers, les dépôts, les artefacts d’entrée, les fichiers auxiliaires, les montages, les répertoires de sortie et les paramètres d’environnement dont l’agent doit disposer.

Le manifeste définit le contrat d’une nouvelle session. Il ne décrit pas nécessairement l’état d’un bac à sable déjà actif. L’espace de travail réellement utilisé peut provenir d’une session active réutilisée, de l’état sérialisé d’une session de bac à sable ou d’un instantané choisi au moment de l’exécution.

Les chemins des entrées du manifeste sont relatifs à l’espace de travail. Ils ne peuvent être absolus ni sortir de cet espace au moyen de ... Le contrat de l’espace de travail reste ainsi portable entre les clients locaux, Docker et hébergés.

Pour construire votre manifeste :

• Placez les dépôts, les artefacts d’entrée et les répertoires de sortie dans le manifeste.
• Placez les spécifications détaillées des tâches et les instructions propres au dépôt dans des fichiers de l’espace de travail tels que repo/task.md ou AGENTS.md.
• Utilisez dans les instructions des chemins relatifs à l’espace de travail, par exemple repo/task.md ou output/report.md.
• Limitez les volumes montés aux données que l’agent doit lire ou écrire.
• Traitez les montages comme des entrées éphémères de l’espace de travail. Lors de la création d’un instantané ou de l’enregistrement de l’espace de travail, le contenu du stockage distant monté est exclu de la copie.

Montage de fichiers et de volumes de stockage

Les données utiles se trouvent souvent déjà ailleurs. Au lieu de coller de longs documents dans le contexte, montez-les dans le bac à sable pour que l’agent puisse travailler directement sur les fichiers.

Exemples :

• Montez un espace documentaire d’audit préalable et demandez à l’agent de rédiger une synthèse qui cite ses sources.
• Montez un export des données d’assistance et demandez à l’agent de regrouper les problèmes par catégorie dans un rapport.
• Montez les artefacts générés pour qu’un autre système puisse les examiner.

Chaque intégration fournisseur propose ses propres utilitaires de montage et gère à sa manière les identifiants et la persistance des données. Conservez le même contrat côté application : montez uniquement les entrées dont l’agent a besoin, indiquez-lui où lire et écrire, et vérifiez les artefacts générés avant de les utiliser.

Gestion des secrets et des identifiants

Fournissez les identifiants du bac à sable dans la configuration d’exécution et gardez-les hors du prompt. L’agent peut avoir besoin d’identifiants pour les gestionnaires de paquets, les volumes montés ou les API des fournisseurs. Gardez ces identifiants hors des prompts des utilisateurs, des instructions de l’agent, des fichiers de tâche, des manifestes enregistrés dans le dépôt et des artefacts générés.

Appliquez les règles suivantes :

• Pour les bacs à sable hébergés, privilégiez le système de gestion des secrets du fournisseur.
• Limitez la portée des identifiants de stockage cloud au montage ou à l’option du fournisseur qui en a besoin.
• Utilisez Manifest.environment pour les valeurs dont le processus du bac à sable a besoin au démarrage. Marquez les entrées sensibles ou générées comme éphémères si vous souhaitez les recréer au lieu de les conserver.
• Évitez d’enregistrer les secrets, les configurations de montage générées, les tokens locaux et les fichiers qui ne doivent pas subsister après l’exécution.
• Examinez les artefacts avant de les sortir du bac à sable, en particulier lorsque l’agent peut lire des documents privés ou accéder à des volumes montés.

Le SDK prend en charge les valeurs d’environnement du manifeste et les identifiants de montage propres à chaque fournisseur. L’intégration avec un gestionnaire de secrets dépend du fournisseur. Laissez votre moteur d’exécution ou votre fournisseur de bac à sable injecter les identifiants, sans les communiquer au modèle dans ses instructions.

Attribution de capacités à l’agent

Les capacités associent les fonctionnalités natives du bac à sable à un SandboxAgent. Elles peuvent préparer l’espace de travail avant l’exécution, ajouter des instructions propres au bac à sable, exposer des outils liés à la session active et adapter le comportement du modèle ou le traitement des entrées pour cet agent.

Par défaut, un SandboxAgent dispose des capacités d’accès au système de fichiers, d’accès au shell et de compactage. Si vous fournissez une liste capabilities, elle remplace la liste par défaut. Incluez donc toutes les capacités par défaut dont l’agent a encore besoin.

Privilégiez les capacités intégrées lorsqu’elles répondent à vos besoins. Créez une capacité personnalisée uniquement s’il vous faut un outil ou des instructions propres au bac à sable que les capacités intégrées ne proposent pas.

Chargement des Skills

Certaines tâches nécessitent de préparer des instructions réutilisables, des scripts, des références ou des ressources avant le démarrage de l’agent. Utilisez la capacité Skills pour que l’agent puisse découvrir ces éléments pendant l’exécution.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import {
  Capabilities,
  SandboxAgent,
  gitRepo,
  skills,
} from "@openai/agents/sandbox";

const agent = new SandboxAgent({
  name: "Tax prep assistant",
  instructions: "Use the mounted skill before preparing the return.",
  capabilities: [
    ...Capabilities.default(),
    skills({
      from: gitRepo({
        repo: "owner/tax-prep-skills",
        ref: "main",
      }),
    }),
  ],
});

1
2
3
4
5
6
7
8
9
10
11
12from agents.sandbox import SandboxAgent
from agents.sandbox.capabilities import Capabilities, Skills
from agents.sandbox.entries import GitRepo

agent = SandboxAgent(
    name="Tax prep assistant",
    instructions="Use the mounted skill before preparing the return.",
    capabilities=Capabilities.default()
    + [
        Skills(from_=GitRepo(repo="owner/tax-prep-skills", ref="main")),
    ],
)

Choisissez la source des Skills en fonction du mode de chargement souhaité :

• Pour un répertoire local volumineux de Skills, utilisez une source locale à chargement différé si vous voulez que le modèle consulte d’abord l’index, puis charge uniquement ce dont il a besoin.
• Pour un petit ensemble de Skills à charger dès le départ, utilisez un répertoire local comme source.
• Utilisez un dépôt Git comme source si l’ensemble de Skills a son propre cycle de publication ou si de nombreux bacs à sable l’utilisent.

Exposition des aperçus et des ports

L’artefact produit peut aussi prendre la forme d’un processus en cours d’exécution. Utilisez un port exposé lorsque l’agent crée une application locale, un notebook, un serveur de rapports, un aperçu dans le navigateur ou tout autre service auquel vous devez accéder depuis l’extérieur du bac à sable.

La configuration des ports dépend du fournisseur, mais le fonctionnement reste le même pour votre produit. L’agent démarre le service dans le bac à sable, le client de bac à sable expose le port, puis votre application partage l’URL de l’aperçu ou l’utilise pour examiner le résultat.

Exécution d’un agent en bac à sable

Une boucle d’exécution minimale comporte les étapes suivantes :

1. Créez un Manifest qui décrit l’espace de travail.
2. Créez un SandboxAgent doté des capacités dont le modèle a besoin.
3. Choisissez un client de bac à sable adapté à l’environnement dans lequel le travail doit s’effectuer.
4. Exécutez l’agent avec la configuration du bac à sable prévue pour cette exécution.
5. Examinez ou copiez les artefacts utiles à votre application, reprenez le travail sur ces artefacts ou enregistrez-en un instantané.

Pour le développement local sur macOS ou Linux, commencez par Unix-local. C’est le cycle local le plus simple : le moteur d’exécution peut créer un espace de travail temporaire à partir du manifeste par défaut de l’agent, puis le nettoyer à la fin de l’exécution.

Si vous utilisez le SDK TypeScript, installez un interpréteur Python 3 de confiance sur l’hôte avant de créer une session avec UnixLocalSandboxClient. Le SDK utilise Python pour sécuriser l’accès aux fichiers locaux et recherche l’interpréteur aux emplacements /usr/bin/python3, /usr/local/bin/python3 et /opt/homebrew/bin/python3. Si Python est installé ailleurs, définissez OPENAI_AGENTS_PYTHON dans l’environnement de l’hôte avant de démarrer Node.js. Donnez à cette variable le chemin absolu de l’exécutable Python. Cette installation doit se faire sur l’hôte : installer un paquet dans le bac à sable ne suffit pas. Si aucun interpréteur Python approprié n’est disponible, la création de la session échoue.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42import { run } from "@openai/agents";
import { Manifest, SandboxAgent, file, shell } from "@openai/agents/sandbox";
import { UnixLocalSandboxClient } from "@openai/agents/sandbox/local";

const manifest = new Manifest({
  entries: {
    "account_brief.md": file({
      content:
        "# Northwind Health\n\n" +
        "- Segment: Mid-market healthcare analytics provider.\n" +
        "- Renewal date: 2026-04-15.\n",
    }),
    "implementation_risks.md": file({
      content:
        "# Delivery risks\n\n" +
        "- Security questionnaire is not complete.\n" +
        "- Procurement requires final legal language by April 1.\n",
    }),
  },
});

const agent = new SandboxAgent({
  name: "Renewal Packet Analyst",
  model: "gpt-6-astra",
  instructions:
    "Review the workspace before answering. Keep the response concise, " +
    "business-focused, and cite the file names that support each conclusion.",
  defaultManifest: manifest,
  capabilities: [shell()],
});

const result = await run(
  agent,
  "Summarize the renewal blockers and recommend the next two actions.",
  {
    sandbox: {
      client: new UnixLocalSandboxClient(),
    },
  }
);

console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53import asyncio

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Shell
from agents.sandbox.entries import File
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

manifest = Manifest(
    entries={
        "account_brief.md": File(
            content=(
                b"# Northwind Health\n\n"
                b"- Segment: Mid-market healthcare analytics provider.\n"
                b"- Renewal date: 2026-04-15.\n"
            )
        ),
        "implementation_risks.md": File(
            content=(
                b"# Delivery risks\n\n"
                b"- Security questionnaire is not complete.\n"
                b"- Procurement requires final legal language by April 1.\n"
            )
        ),
    }
)

agent = SandboxAgent(
    name="Renewal Packet Analyst",
    model="gpt-6-astra",
    instructions=(
        "Review the workspace before answering. Keep the response concise, "
        "business-focused, and cite the file names that support each conclusion."
    ),
    default_manifest=manifest,
    capabilities=[Shell()],
)


async def main():
    result = await Runner.run(
        agent,
        "Summarize the renewal blockers and recommend the next two actions.",
        run_config=RunConfig(
            sandbox=SandboxRunConfig(client=UnixLocalSandboxClient()),
            workflow_name="Unix-local sandbox review",
        ),
    )
    print(result.final_output)


asyncio.run(main())

Pour des exemples locaux complets, consultez le guide de démarrage des agents en bac à sable en TypeScript et le fichier Python unix_local_runner.py.

Changement de fournisseur

Le fournisseur se choisit dans la configuration de l’exécution. Conservez le même SandboxAgent, le même manifeste et les mêmes capacités, puis remplacez le client de bac à sable et les options du fournisseur en fonction de l’environnement souhaité.

Cet exemple utilise Docker pour isoler l’exécution dans un conteneur local. Les fournisseurs de bacs à sable hébergés suivent le même principe, avec leurs propres classes de clients et leurs propres options.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import { run } from "@openai/agents";
import { SandboxAgent } from "@openai/agents/sandbox";
import { DockerSandboxClient } from "@openai/agents/sandbox/local";

const agent = new SandboxAgent({
  name: "Workspace reviewer",
  model: "gpt-6-astra",
  instructions: "Inspect the sandbox workspace before answering.",
});

const result = await run(agent, "Inspect the workspace.", {
  sandbox: {
    client: new DockerSandboxClient({
      image: "node:22-bookworm-slim",
    }),
  },
});

console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29from docker import from_env as docker_from_env

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxRunConfig
from agents.sandbox.config import DEFAULT_PYTHON_SANDBOX_IMAGE
from agents.sandbox.sandboxes.docker import (
    DockerSandboxClient,
    DockerSandboxClientOptions,
)

docker_run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=DockerSandboxClient(docker_from_env()),
        options=DockerSandboxClientOptions(
            image=DEFAULT_PYTHON_SANDBOX_IMAGE,
            network_mode="none",
        ),
    ),
    workflow_name="Docker sandbox review",
)

result = await Runner.run(
    agent,
    "Summarize the renewal blockers and recommend the next two actions.",
    run_config=docker_run_config,
)

print(result.final_output)

Pour des exemples exécutables, consultez le guide des clients de bac à sable et l’exemple de base en TypeScript. Le dépôt du SDK propose aussi des exemples Python : basic.py pour le choix du fournisseur, docker_runner.py pour Docker et main.py pour un workflow utilisant un espace documentaire.

Workflows avancés

Une fois la boucle de base opérationnelle, vous pouvez utiliser les bacs à sable pour les workflows où l’agent a besoin d’un espace de travail plutôt que d’un prompt plus détaillé. Ces exemples illustrent différents workflows qui utilisent la même API. Un même harnais peut acheminer les tâches, interrompre le workflow, le reprendre et en tracer l’exécution. Chaque bac à sable exécute les tâches au plus près des fichiers, des outils et des ports nécessaires.

Reprise du travail ou préparation d’une nouvelle exécution

Le travail d’un agent se poursuit souvent au-delà d’une seule requête. Un utilisateur peut avoir besoin d’examiner un artefact, une étape peut nécessiter une approbation ou la suite du travail peut dépendre d’un événement ultérieur.

Distinguez trois types d’état :

En pratique, le moteur d’exécution détermine la session de bac à sable à utiliser dans l’ordre suivant :

1. Si vous fournissez une session de bac à sable active, le moteur d’exécution la réutilise directement.
2. Sinon, si l’exécution reprend à partir de RunState, le moteur d’exécution restaure la session de bac à sable à partir de son état enregistré.
3. Sinon, si vous fournissez explicitement un état sérialisé du bac à sable, le moteur d’exécution reprend à partir de cet état.
4. Sinon, le moteur d’exécution crée une nouvelle session de bac à sable. Il utilise le manifeste fourni pour cette exécution ou, à défaut, le manifeste par défaut de l’agent.

L’exemple de reprise sérialise l’état de la session arrêtée, restaure la session au moyen du même client, puis transmet la session restaurée à l’exécution suivante :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52import { run } from "@openai/agents";
import { Manifest, SandboxAgent } from "@openai/agents/sandbox";
import { UnixLocalSandboxClient } from "@openai/agents/sandbox/local";

const manifest = new Manifest();
const client = new UnixLocalSandboxClient({
  snapshot: { type: "local", baseDir: "/tmp/my-sandbox-snapshots" },
});
const agent = new SandboxAgent({
  name: "Workspace builder",
  model: "gpt-6-astra",
  instructions: "Inspect the sandbox workspace before answering.",
});

const session = await client.create({ manifest });
let conversation = [];
let frozenSessionState;

try {
  const firstResult = await run(agent, "Build the first version of the app.", {
    maxTurns: 20,
    sandbox: { session },
  });

  conversation = firstResult.history;
  frozenSessionState = await client.serializeSessionState?.(session.state);
} finally {
  await session.close?.();
}

if (!frozenSessionState || !client.deserializeSessionState || !client.resume) {
  throw new Error("Sandbox client does not support session resume.");
}

const resumedSession = await client.resume(
  await client.deserializeSessionState(frozenSessionState)
);

try {
  conversation.push({
    role: "user",
    content: "Continue from the existing workspace and add tests.",
  });

  const secondResult = await run(agent, conversation, {
    maxTurns: 20,
    sandbox: { session: resumedSession },
  });
  console.log(secondResult.finalOutput);
} finally {
  await resumedSession.close?.();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44async with session:
    first_result = await Runner.run(
        agent,
        "Create app.py with an add(a, b) function that returns their sum. "
        "Run it once to check that add(2, 3) equals 5.",
        max_turns=20,
        run_config=RunConfig(
            sandbox=SandboxRunConfig(session=session),
            workflow_name="Sandbox resume example",
        ),
    )

conversation = first_result.to_input_list()
frozen_session_state = client.deserialize_session_state(
    client.serialize_session_state(session.state)
)

conversation.append(
    {
        "role": "user",
        "content": (
            "Read the existing app.py without replacing it. Add test_app.py with "
            "two unittest tests: one for positive inputs and one for negative "
            "inputs. Run both tests."
        ),
    }
)

resumed_session = await client.resume(frozen_session_state)
try:
    async with resumed_session:
        second_result = await Runner.run(
            agent,
            conversation,
            max_turns=20,
            run_config=RunConfig(
                sandbox=SandboxRunConfig(session=resumed_session),
                workflow_name="Sandbox resume example",
            ),
        )
finally:
    await client.delete(resumed_session)

print(second_result.final_output)

Les entrées d’initialisation telles que manifest et snapshot ne s’appliquent que lorsque le moteur d’exécution crée une session de bac à sable. Si vous injectez une session active, le traitement des capacités peut ajouter des entrées compatibles autres que des montages. Il ne peut toutefois ni modifier la racine, l’environnement, les utilisateurs ou les groupes, ni supprimer des entrées existantes, ni remplacer un type d’entrée par un autre, ni ajouter ou modifier des montages dans le bac à sable déjà en cours d’exécution.

Cette séparation permet au harnais de reprendre la boucle de l’agent pendant que le fournisseur du bac à sable restaure ou recrée l’espace de travail. Vous trouverez des exemples à jour en TypeScript dans l’exemple de reprise à partir de l’état de session et en Python dans main.py et sandbox_agent_with_remote_snapshot.py.

Conservation de la mémoire d’une exécution à l’autre

La mémoire du bac à sable permet aux agents de tirer parti des exécutions précédentes. Elle est distincte de la mémoire conversationnelle des objets Session gérés par le SDK. Les sessions conservent l’historique des messages. La mémoire du bac à sable synthétise les enseignements des exécutions précédentes dans des fichiers que l’agent pourra consulter ultérieurement.

Utilisez la mémoire lorsque l’agent doit tenir compte des préférences de l’utilisateur, de corrections, d’enseignements propres au projet ou de résumés de tâches sans rejouer tous les tours précédents. La reprise de session et les instantanés préservent l’état de l’espace de travail. La mémoire conserve les enseignements tirés du travail effectué dans cet espace afin que l’agent puisse les réutiliser.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import {
  Manifest,
  SandboxAgent,
  filesystem,
  memory,
  shell,
} from "@openai/agents/sandbox";

const manifest = new Manifest();

const agent = new SandboxAgent({
  name: "Memory-enabled reviewer",
  instructions:
    "Inspect the workspace and retain useful lessons for follow-up runs.",
  defaultManifest: manifest,
  capabilities: [memory(), filesystem(), shell()],
});

1
2
3
4
5
6
7
8from agents.sandbox.capabilities import Filesystem, Memory, Shell

agent = SandboxAgent(
    name="Memory-enabled reviewer",
    instructions="Inspect the workspace and retain useful lessons for follow-up runs.",
    default_manifest=manifest,
    capabilities=[Memory(), Filesystem(), Shell()],
)

Par défaut, la mémoire autorise à la fois la lecture et la génération. La lecture nécessite un accès au shell pour que l’agent puisse rechercher et ouvrir les fichiers de mémoire. Par défaut, la mise à jour de la mémoire en cours d’exécution nécessite également un accès au système de fichiers. L’agent peut ainsi corriger des informations obsolètes ou mettre à jour la mémoire à la demande de l’utilisateur.

La lecture de la mémoire se fait progressivement. Le SDK injecte memory_summary.md au début de l’exécution. Si des travaux antérieurs semblent pertinents, l’agent effectue une recherche dans MEMORY.md. Il n’ouvre les résumés d’exécution que s’il a besoin de plus de détails.

Par défaut, les artefacts de mémoire se trouvent dans l’espace de travail du bac à sable :

workspace/
  sessions/
    <rollout-id>.jsonl
  memories/
    memory_summary.md
    MEMORY.md
    raw_memories.md
    phase_two_selection.json
    raw_memories/
      <rollout-id>.md
    rollout_summaries/
      <rollout-id>_<slug>.md
    skills/

Le moteur d’exécution ajoute les segments d’exécution au fil de la session de bac à sable. À la fermeture de la session, le processus de génération de la mémoire extrait d’abord les résumés des conversations et les éléments de mémoire bruts, puis consolide ces éléments dans MEMORY.md et memory_summary.md. Pour réutiliser la mémoire lors d’une exécution ultérieure, conservez les répertoires de mémoire configurés. Vous pouvez garder la même session active, la reprendre à partir de son état enregistré, démarrer à partir d’un instantané ou monter un volume de stockage persistant tel que S3.

Pour les discussions en plusieurs tours dans un bac à sable, utilisez une session SDK stable et conservez la même session de bac à sable active. Pour regrouper les exécutions, la mémoire utilise en priorité l’identifiant de conversation fourni explicitement, puis, à défaut, l’identifiant de session du SDK, celui du groupe d’exécutions et, en dernier recours, un identifiant généré pour chaque exécution. L’identifiant de session du bac à sable identifie l’espace de travail actif. Il est distinct de l’identifiant de conversation utilisé par la mémoire.

Pour des exemples exécutables, consultez le guide de la mémoire en TypeScript. En Python, memory.py illustre un workflow avec un instantané local, memory_s3.py le stockage de la mémoire dans S3 et memory_multi_agent_multiturn.py l’utilisation de répertoires de mémoire distincts pour chaque agent.

Combinaison d’agents en bac à sable

Vous pouvez combiner les agents en bac à sable avec les autres composants du SDK.

Utilisez un transfert lorsqu’un agent qui reçoit les demandes hors du bac à sable doit déléguer à un agent en bac à sable uniquement la partie du workflow qui sollicite le plus l’espace de travail. L’exécution principale se poursuit, mais l’agent en bac à sable devient l’agent actif au tour suivant.

Utilisez les agents comme outils lorsqu’un orchestrateur de niveau supérieur doit appeler un ou plusieurs agents en bac à sable comme outils imbriqués. Chaque agent ainsi appelé peut avoir sa propre configuration d’exécution en bac à sable, son propre client, son propre manifeste et ses propres options de fournisseur.

Pour des exemples, consultez handoffs.py et sandbox_agents_as_tools.py.

Fournisseurs de bacs à sable

Commencez par Unix-local pour itérer rapidement en local, ou par Docker si vous souhaitez isoler l’exécution dans un conteneur local. Passez à un fournisseur de bacs à sable hébergés si la tâche nécessite une exécution gérée, une isolation propre au fournisseur, une mise à l’échelle, des aperçus, des volumes de stockage montés, des instantanés ou des identifiants à conserver hors du serveur de votre application.

Consultez la documentation de chaque fournisseur pour connaître les modalités de configuration, de gestion des identifiants, d’isolation, de stockage, d’accès aux aperçus et de persistance des données.