Agentes con sandbox

Un sandbox le ofrece al agente un entorno de ejecución aislado, similar a Unix, con un sistema de archivos, un shell, paquetes instalados, datos montados, puertos expuestos, instantáneas y acceso controlado a sistemas externos.

Los flujos de trabajo de los agentes se vuelven frágiles cuando el modelo necesita un espacio de trabajo de este tipo y solo recibe el contexto del prompt. Para trabajar con colecciones extensas de documentos, artefactos generados, comandos y vistas previas, o para reanudar una tarea, el agente necesita un entorno que pueda inspeccionar y modificar.

Los SDK de agentes para TypeScript y Python admiten agentes con sandbox.

Esta guía explica cómo usar sandboxes en el SDK de agentes, donde tu aplicación ejecuta el arnés de ejecución. Si necesitas un arnés de ejecución administrado por OpenAI, consulta API de agentes: conectar un sandbox.

Usa sandboxes cuando el agente necesite manipular archivos, ejecutar comandos, montar una sala de datos, producir artefactos, exponer un servicio o retomar el trabajo más adelante conservando su estado.

El arnés de ejecución y los recursos de cómputo cumplen funciones distintas. El arnés de ejecución es el plano de control que rodea al modelo. Gestiona el ciclo del agente, las llamadas al modelo, el enrutamiento de llamadas a herramientas, las transferencias entre agentes, las aprobaciones, el seguimiento, la recuperación y el estado de la ejecución. Los recursos de cómputo constituyen el plano de ejecución del sandbox. Allí, bajo la dirección del modelo, se leen y escriben archivos, se ejecutan comandos, se instalan dependencias, se usa el almacenamiento montado, se exponen puertos y se toman instantáneas del estado.

Al separar ambos planos, tu aplicación puede realizar las operaciones sensibles del plano de control en infraestructura de confianza, mientras el sandbox se encarga de la ejecución específica de cada proveedor. El sandbox puede ejecutar código sobre archivos con credenciales y montajes de alcance limitado. El arnés de ejecución puede gestionar la autenticación, la facturación, los registros de auditoría, la revisión humana y el estado de recuperación fuera de cualquier contenedor individual.

Cuándo usar un sandbox

Usa un sandbox cuando la respuesta del agente dependa del trabajo que realiza en el espacio de trabajo del sandbox y el razonamiento a partir del contexto del prompt sea insuficiente.

Estas son algunas situaciones habituales:

• La tarea requiere un directorio de documentos. Un solo prompt no basta.
• El agente debe escribir archivos que tu aplicación pueda inspeccionar más adelante.
• El agente necesita comandos, paquetes o scripts para completar el trabajo.
• El flujo de trabajo produce artefactos como archivos Markdown, CSV o JSONL, capturas de pantalla o sitios web generados.
• Un servicio, un notebook o la vista previa de un informe debe estar disponible en un puerto expuesto.
• El trabajo se pausa para que una persona lo revise y luego se reanuda en el mismo espacio de trabajo.

Si tu flujo de trabajo solo necesita una respuesta breve del modelo y puede prescindir de un espacio de trabajo persistente, llama directamente a la API de respuestas o usa el entorno de ejecución básico del SDK de agentes sin un sandbox.

Si solo necesitas acceso ocasional al shell como herramienta, empieza con la herramienta Terminal alojada en la nube que se describe en Uso de herramientas. Usa agentes con sandbox cuando el diseño del producto requiera aislar el espacio de trabajo, elegir el proveedor del sandbox o retomar el trabajo con el estado anterior del sistema de archivos.

Qué aportan los sandboxes

Un SandboxAgent sigue siendo un Agent. Conserva la interfaz habitual del agente, que incluye instructions, prompt, tools, handoffs, servidores MCP, configuración del modelo, resultados estructurados, controles de seguridad y hooks. Lo que cambia es el entorno en el que se realiza el trabajo. El ejecutor prepara al agente para trabajar con una sesión activa de sandbox que gestiona los archivos, los comandos, los puertos y el aislamiento específico del proveedor.

Define los valores predeterminados específicos del sandbox en SandboxAgent. Las opciones de la sesión de sandbox que dependen de cada ejecución se definen en la configuración del sandbox para esa ejecución.

El significado de un turno tampoco cambia con los agentes con sandbox. Un turno sigue correspondiendo a un paso del modelo. Ejecutar un comando de shell o realizar una acción en el sandbox no consume por sí solo un turno. Parte del trabajo puede realizarse íntegramente en la capa de ejecución del sandbox. El entorno de ejecución del agente solo consume otro turno si necesita una nueva respuesta del modelo después del trabajo en el sandbox.

Crear el espacio de trabajo

Manifest describe el contenido y la estructura iniciales que debe tener un espacio de trabajo nuevo en el sandbox. Úsalo para definir los archivos, repositorios, artefactos de entrada, archivos auxiliares, montajes, directorios de salida y configuración del entorno que el agente debe tener a su disposición.

El archivo de manifiesto define el contrato de una sesión nueva. Por sí solo, no describe todos los sandboxes activos. El espacio de trabajo que se usa en una ejecución también puede provenir de una sesión de sandbox activa que se reutiliza, del estado serializado de una sesión de sandbox o de una instantánea elegida en el momento de la ejecución.

Las rutas de las entradas del archivo de manifiesto son relativas al espacio de trabajo. No pueden ser absolutas ni salir del espacio de trabajo mediante ... Así, el mismo contrato se puede usar con clientes locales, de Docker y alojados.

Al diseñar el archivo de manifiesto, sigue estas pautas:

• Incluye los repositorios, los artefactos de entrada y los directorios de salida en el archivo de manifiesto.
• Guarda las especificaciones extensas de las tareas y las instrucciones propias del repositorio en archivos del espacio de trabajo como repo/task.md o AGENTS.md.
• Usa rutas relativas al espacio de trabajo en las instrucciones, por ejemplo, repo/task.md u output/report.md.
• Limita el alcance del almacenamiento montado a las entradas que el agente deba leer o escribir.
• Trata los montajes como entradas efímeras del espacio de trabajo. Al tomar instantáneas o guardar el espacio de trabajo, se omite el almacenamiento remoto montado, sin copiarlo al contenido guardado.

Montar archivos y almacenamiento

A menudo, los datos que necesitas ya están en otra ubicación. En lugar de pegar documentos extensos en el contexto, móntalos en el sandbox para que el agente pueda trabajar con los archivos.

Ejemplos:

• Monta una sala de datos para una auditoría de debida diligencia y pídele al agente que prepare un resumen con citas de las fuentes.
• Monta una exportación de datos de soporte y pídele al agente que agrupe los problemas en un informe.
• Monta los artefactos generados para que otro sistema pueda revisarlos.

Cada integración con un proveedor ofrece sus propias funciones auxiliares de montaje y gestiona de manera distinta las credenciales y la persistencia. Mantén el mismo contrato en tu aplicación: monta solo las entradas que el agente deba usar, indícale dónde leer y escribir, y revisa los artefactos generados antes de usarlos.

Gestionar secretos y credenciales

Gestiona las credenciales del sandbox como parte de la configuración del entorno de ejecución. Evita incluirlas en el contenido del prompt. El agente puede necesitar credenciales para los gestores de paquetes, los montajes de almacenamiento o las API de los proveedores. Esas credenciales no deben aparecer en los prompts de los usuarios, las instrucciones del agente, los archivos de tareas, los archivos de manifiesto registrados en el repositorio ni los artefactos generados.

Sigue estas reglas:

• Si usas un proveedor de sandboxes alojados, da preferencia a su sistema nativo de gestión de secretos.
• Limita el alcance de las credenciales de almacenamiento en la nube al montaje o a la opción del proveedor que las necesite.
• Usa Manifest.environment para los valores que el proceso del sandbox necesita al iniciarse. Marca las entradas sensibles o generadas como efímeras cuando quieras volver a crearlas en lugar de conservarlas.
• Evita guardar secretos, configuraciones de montaje generadas, tokens locales o archivos que no deban conservarse después de la ejecución.
• Revisa los artefactos antes de sacarlos del sandbox, especialmente si el agente puede leer documentos privados o acceder al almacenamiento montado.

El SDK admite valores de entorno en el archivo de manifiesto y credenciales de montaje específicas de cada proveedor. La integración general con los almacenes de secretos depende del proveedor. Tu entorno de ejecución o tu proveedor de sandbox debe inyectar las credenciales en lugar de proporcionárselas al modelo como instrucciones.

Dar capacidades al agente

Las capacidades incorporan funciones nativas del sandbox a un SandboxAgent. Pueden preparar el espacio de trabajo antes de que comience una ejecución, agregar instrucciones específicas del sandbox, exponer herramientas vinculadas a la sesión activa de sandbox y ajustar el comportamiento del modelo o el procesamiento de entradas para ese agente.

De forma predeterminada, un SandboxAgent incluye las capacidades de sistema de archivos, shell y compactación. Si pasas una lista capabilities, esta reemplaza la lista predeterminada. Incluye las capacidades predeterminadas que el agente siga necesitando.

Usa las capacidades integradas cuando cubran tus necesidades. Crea una capacidad personalizada solo si necesitas ofrecer una herramienta o instrucciones específicas del sandbox que las capacidades integradas no contemplen.

Cargar habilidades

Algunas tareas requieren que, antes de que el agente comience, estén disponibles instrucciones reutilizables, scripts, referencias o recursos. Usa la capacidad Skills para que el agente pueda descubrir ese contexto de trabajo durante la ejecución.

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")),
    ],
)

Elige el origen de las habilidades según cómo quieras incorporarlas al espacio de trabajo:

• Para directorios locales de habilidades grandes, usa un directorio local con carga bajo demanda si quieres que el modelo consulte primero el índice y cargue solo lo que necesita.
• Usa un directorio local como origen si tienes un paquete local pequeño que quieres cargar desde el principio.
• Usa un repositorio Git como origen si el paquete de habilidades tiene su propio ciclo de publicación o si se usa en muchos sandboxes.

Exponer vistas previas y puertos

A veces, el artefacto consiste en un proceso en ejecución en lugar de un archivo. Usa un puerto expuesto cuando el agente cree una aplicación local, un notebook, un servidor de informes, una vista previa en el navegador u otro servicio que necesites inspeccionar desde fuera del sandbox.

La configuración del puerto depende del proveedor, pero el contrato del producto es el mismo: el agente inicia el servicio dentro del sandbox, el cliente de sandbox expone el puerto y tu aplicación comparte o inspecciona la URL de la vista previa resultante.

Ejecutar un agente con sandbox

El ciclo mínimo para trabajar con un sandbox consta de estos pasos:

1. Crea un Manifest que describa el espacio de trabajo.
2. Crea un SandboxAgent con las capacidades que necesita el modelo.
3. Elige un cliente de sandbox para el entorno donde se realizará el trabajo.
4. Ejecuta el agente con la configuración del sandbox correspondiente a esa ejecución.
5. Inspecciona o copia los artefactos que le interesen a tu aplicación, retoma el trabajo con ellos o guarda una instantánea.

Empieza con Unix-local para desarrollar localmente en macOS o Linux. Es la forma más sencilla de ejecutar el ciclo en tu equipo, ya que el ejecutor puede crear un espacio de trabajo temporal a partir del archivo de manifiesto predeterminado del agente y eliminarlo al terminar.

Si usas el SDK para TypeScript, instala un intérprete de Python 3 de confianza en el host antes de crear una sesión con UnixLocalSandboxClient. El SDK usa Python para acceder de forma protegida a los archivos locales y busca el intérprete en /usr/bin/python3, /usr/local/bin/python3 y /opt/homebrew/bin/python3. Si Python está instalado en otra ubicación, asigna la ruta absoluta del ejecutable a la variable OPENAI_AGENTS_PYTHON en el entorno del host antes de iniciar Node.js. El intérprete es un requisito previo del host. Instalar Python dentro del sandbox no satisface ese requisito. Si el SDK no encuentra un intérprete de Python adecuado, la creación de la sesión falla.

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())

Para ver ejemplos locales completos, consulta la guía de inicio rápido para agentes con sandbox en TypeScript y unix_local_runner.py en Python.

Cambiar de proveedor

El proveedor se define en la configuración de cada ejecución y es independiente de la definición del agente. Mantén el mismo SandboxAgent, el archivo de manifiesto y las capacidades. Cambia el cliente de sandbox y las opciones del proveedor según el entorno que quieras usar.

Este ejemplo usa Docker para aislar la ejecución local en un contenedor. Los proveedores de alojamiento siguen el mismo patrón con sus propias clases de cliente y opciones.

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)

Para ver ejemplos que puedes ejecutar, consulta la guía de clientes de sandbox y el ejemplo básico en TypeScript. En el repositorio del SDK también encontrarás ejemplos en Python: basic.py para elegir un proveedor, docker_runner.py para usar Docker y main.py para trabajar con una sala de datos.

Patrones avanzados

Una vez que el ciclo básico funciona, puedes usar sandboxes en flujos donde el agente necesita un espacio de trabajo en lugar de más contexto en el prompt. Estos ejemplos ilustran patrones de trabajo que utilizan la misma API. El mismo arnés de ejecución puede dirigir, pausar, reanudar y rastrear el flujo de trabajo, mientras cada sandbox ejecuta las tareas junto a los archivos, las herramientas y los puertos que necesita.

Reanudar el trabajo o preparar futuras ejecuciones

El trabajo de un agente a menudo se extiende más allá de una sola solicitud. Puede que un usuario revise un artefacto, que un paso requiera aprobación o que el paso siguiente dependa de un evento posterior.

Distingue estos tres tipos de estado:

En la práctica, el ejecutor determina qué sesión de sandbox usar en este orden:

1. Si pasas una sesión de sandbox activa, el ejecutor la reutiliza directamente.
2. Si no pasas una sesión activa y la ejecución se reanuda desde RunState, el ejecutor retoma la sesión de sandbox a partir de su estado almacenado.
3. Si no se cumple ninguna de las condiciones anteriores y pasas explícitamente un estado de sandbox serializado, el ejecutor reanuda la sesión desde ese estado.
4. En los demás casos, el ejecutor crea una nueva sesión de sandbox. Para esa sesión, usa el archivo de manifiesto de la ejecución si se proporcionó uno. De lo contrario, usa el archivo de manifiesto predeterminado del agente.

El ejemplo de reanudación del sandbox serializa el estado de la sesión detenida, reanuda la sesión con el mismo cliente y luego pasa la sesión reanudada a la siguiente ejecución:

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)

Las entradas para sesiones nuevas, como manifest y snapshot, solo se aplican cuando el ejecutor crea una sesión de sandbox. Si inyectas una session activa, el procesamiento de las capacidades puede agregar entradas compatibles que no sean montajes. En un sandbox que ya está en ejecución, no puede cambiar la raíz, el entorno, los usuarios ni los grupos. Tampoco puede eliminar entradas existentes, reemplazar tipos de entradas ni agregar o modificar montajes.

Esta separación permite que el arnés de ejecución reanude el ciclo del agente mientras el proveedor de sandbox restaura o vuelve a crear el espacio de trabajo. Encontrarás código de ejemplo actualizado para estos casos en el ejemplo de reanudación a partir del estado de sesión en TypeScript y en los archivos main.py y sandbox_agent_with_remote_snapshot.py en Python.

Conservar la memoria entre ejecuciones

La memoria del sandbox permite que un agente con sandbox aprenda de ejecuciones anteriores. Es independiente de la memoria conversacional de Session que gestiona el SDK. Las sesiones conservan el historial de mensajes, mientras que la memoria del sandbox recoge lo aprendido en ejecuciones anteriores del espacio de trabajo y lo guarda en archivos que el agente puede leer más adelante.

Usa la memoria cuando el agente deba conservar preferencias del usuario, correcciones, lecciones específicas del proyecto o resúmenes de tareas sin volver a procesar todos los turnos anteriores. La reanudación y las instantáneas conservan el estado del espacio de trabajo. La memoria conserva orientaciones reutilizables sobre el trabajo realizado allí.

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()],
)

De forma predeterminada, la memoria permite tanto leer como generar memorias. Para leer la memoria, el agente necesita acceso al shell, con el que puede buscar y abrir archivos de memoria. De forma predeterminada, las actualizaciones de memoria durante la ejecución también requieren acceso al sistema de archivos para que el agente pueda corregir información desactualizada o actualizar la memoria cuando el usuario se lo pida.

El agente consulta la memoria de forma progresiva. El SDK inyecta memory_summary.md al inicio de la ejecución. Si el trabajo anterior parece relevante, el agente busca en MEMORY.md y solo abre los resúmenes de ejecución cuando necesita más detalles.

De forma predeterminada, los artefactos de memoria se guardan en el espacio de trabajo del sandbox:

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/

El entorno de ejecución agrega segmentos de cada ejecución durante la sesión de sandbox. Cuando la sesión se cierra, el proceso de generación de memoria primero extrae resúmenes de las conversaciones y memorias sin procesar. Luego consolida esas memorias en MEMORY.md y memory_summary.md. Para reutilizar la memoria en una ejecución posterior, conserva los directorios de memoria configurados. Puedes mantener activa la misma sesión de sandbox, reanudarla a partir de su estado, comenzar desde una instantánea o montar almacenamiento persistente como S3.

En los chats de varios turnos con sandbox, usa una sesión estable del SDK junto con la misma sesión activa de sandbox. Para agrupar las ejecuciones, la memoria usa, en orden de prioridad, el ID explícito de la conversación, el ID de la sesión del SDK, el ID del grupo de ejecuciones y, por último, un ID generado para cada ejecución. El ID de la sesión de sandbox identifica el espacio de trabajo activo y es distinto del ID de conversación que usa la memoria.

Para ver ejemplos que puedes ejecutar, consulta la guía de memoria en TypeScript. En Python, consulta memory.py para un flujo con instantáneas locales, memory_s3.py para almacenar la memoria en S3 y memory_multi_agent_multiturn.py para usar estructuras de memoria independientes por agente.

Combinar agentes con sandbox

Los agentes con sandbox se pueden combinar con el resto del SDK.

Usa una transferencia cuando un agente que recibe solicitudes sin usar un sandbox deba delegar a un agente con sandbox solo la parte del flujo que requiere un uso intensivo del espacio de trabajo. La ejecución principal continúa, pero el agente con sandbox pasa a ser el agente activo en el turno siguiente.

Usa agentes como herramientas cuando un orquestador de nivel superior deba llamar a uno o más agentes con sandbox como herramientas anidadas. Cada agente con sandbox que actúe como herramienta puede tener su propia configuración de ejecución del sandbox, su cliente de sandbox, su archivo de manifiesto y sus opciones de proveedor.

Para ver ejemplos, consulta handoffs.py y sandbox_agents_as_tools.py.

Proveedores de sandbox

Empieza con Unix-local para iterar rápidamente en tu equipo o con Docker si quieres aislamiento local en contenedores. Cambia a un proveedor de alojamiento cuando la tarea requiera ejecución administrada, aislamiento específico del proveedor, escalado, vistas previas, montajes de almacenamiento, instantáneas o credenciales que deban mantenerse fuera del servidor de tu aplicación.

Consulta la documentación de cada proveedor para conocer los detalles de configuración, credenciales, aislamiento, almacenamiento, vistas previas y persistencia.