Agentes de sandbox

Um sandbox oferece ao agente um ambiente de execução isolado semelhante ao Unix, com sistema de arquivos, shell, pacotes instalados, dados montados, portas expostas, snapshots e acesso controlado a sistemas externos.

Os fluxos de trabalho de agentes se tornam frágeis quando o modelo precisa desse tipo de espaço de trabalho, mas recebe apenas o contexto do prompt. Para lidar com grandes conjuntos de documentos, artefatos gerados, comandos e prévias, ou para retomar o trabalho mais tarde, o agente precisa de um ambiente que possa inspecionar e modificar.

Os agentes de sandbox estão disponíveis nas versões do Agents SDK para TypeScript e Python.

Este guia aborda o uso de sandboxes no Agents SDK, em que seu aplicativo executa o harness. Para usar um harness gerenciado pela OpenAI, consulte Agents API: conectar um sandbox.

Use um sandbox quando o agente precisar manipular arquivos, executar comandos, montar uma sala de dados, produzir artefatos, expor um serviço ou retomar o trabalho mais tarde a partir do estado anterior.

O harness e o ambiente computacional têm responsabilidades distintas. O harness é o plano de controle que envolve o modelo. Ele gerencia o ciclo do agente, as chamadas ao modelo, o encaminhamento de chamadas às ferramentas, as transferências entre agentes, as aprovações, o rastreamento, a recuperação e o estado da execução. O ambiente computacional corresponde ao plano de execução do sandbox. Nele, o agente segue as orientações do modelo para ler e gravar arquivos, executar comandos, instalar dependências, usar armazenamento montado, expor portas e criar snapshots do estado.

Com essa separação, seu aplicativo pode manter as operações sensíveis do plano de controle em uma infraestrutura confiável, enquanto o sandbox cuida da execução específica do provedor. O sandbox pode executar código sobre os arquivos com credenciais e montagens de escopo limitado. O harness pode manter a autenticação, o faturamento, os logs de auditoria, a revisão humana e o estado de recuperação fora dos contêineres individuais.

Quando usar um sandbox

Use um sandbox quando a resposta do agente depender de tarefas realizadas no espaço de trabalho do sandbox e o raciocínio sobre o contexto do prompt, por si só, for insuficiente.

Algumas situações comuns incluem:

• A tarefa exige um diretório de documentos e um único prompt é insuficiente.
• O agente precisa gravar arquivos para que seu aplicativo possa inspecioná-los mais tarde.
• O agente precisa de comandos, pacotes ou scripts para concluir a tarefa.
• O fluxo de trabalho produz artefatos como arquivos Markdown, CSV ou JSONL, capturas de tela ou sites gerados.
• Um serviço, um notebook ou a prévia de um relatório precisa estar disponível em uma porta exposta.
• O trabalho é pausado para revisão humana e depois retomado no mesmo espaço de trabalho.

Se o fluxo precisar apenas de uma resposta curta do modelo e dispensar um espaço de trabalho persistente, chame a Responses API diretamente ou use o ambiente de execução básico do Agents SDK sem sandbox.

Se o agente só precisar de acesso ocasional ao shell, comece pela ferramenta Shell hospedado descrita em Como usar ferramentas. Use agentes de sandbox quando o projeto do produto exigir isolamento do espaço de trabalho, escolha do provedor de sandbox ou a possibilidade de retomar o estado do sistema de arquivos.

O que os sandboxes acrescentam

Um SandboxAgent continua sendo um Agent. Ele mantém a interface habitual do agente, incluindo instructions, prompt, tools, handoffs, servidores MCP, configurações do modelo, saída estruturada, mecanismos de proteção e hooks. O que muda é o limite de execução. O executor prepara o agente para atuar em uma sessão ativa de sandbox, que gerencia os arquivos, os comandos, as portas e o isolamento específico do provedor.

Defina as configurações padrão específicas do sandbox em SandboxAgent. Faça as escolhas de sessão que variam a cada execução na configuração de sandbox daquela execução.

Nos agentes de sandbox, um turno continua sendo uma etapa do modelo. O agente pode executar comandos de shell e outras ações inteiramente na camada de execução do sandbox. O ambiente de execução do agente só consome outro turno quando precisa de uma nova resposta do modelo após o trabalho no sandbox.

Crie o espaço de trabalho

Manifest descreve o conteúdo e a organização inicial desejados para um novo espaço de trabalho de sandbox. Use-o para definir os arquivos, repositórios, artefatos de entrada, arquivos auxiliares, montagens, diretórios de saída e configurações de ambiente que devem estar disponíveis para o agente.

O manifesto define o contrato para uma nova sessão. O espaço de trabalho efetivamente usado em uma execução também pode vir de uma sessão ativa reutilizada, de um estado de sessão de sandbox serializado ou de um snapshot escolhido no momento da execução.

Os caminhos das entradas do manifesto são relativos ao espaço de trabalho. Eles não podem ser absolutos nem usar .. para sair do espaço de trabalho. Isso permite usar o mesmo contrato com clientes locais, Docker ou hospedados.

Ao criar um manifesto, siga estas práticas:

• Inclua os repositórios, os artefatos de entrada e os diretórios de saída no manifesto.
• Coloque especificações de tarefas mais longas e instruções específicas do repositório em arquivos do espaço de trabalho, como repo/task.md ou AGENTS.md.
• Nas instruções, use caminhos relativos ao espaço de trabalho, como repo/task.md ou output/report.md.
• Limite o escopo do armazenamento montado às entradas que o agente deve ler ou gravar.
• Trate as montagens como entradas temporárias do espaço de trabalho. Os processos de criação de snapshots e de persistência ignoram o armazenamento remoto montado. Seu conteúdo fica fora da cópia salva do espaço de trabalho.

Monte arquivos e armazenamento

Muitas vezes, os dados necessários já estão armazenados em outro lugar. Em vez de colar documentos grandes no contexto, monte-os no sandbox para que o agente trabalhe diretamente com os arquivos.

Exemplos:

• Monte uma sala de dados de due diligence e peça ao agente um resumo com referências às fontes.
• Monte uma exportação de dados de suporte e peça ao agente que agrupe os problemas em um relatório.
• Monte os artefatos gerados para que outro sistema possa revisá-los.

Cada integração com um provedor oferece seus próprios recursos de montagem, formas de lidar com credenciais e mecanismos de persistência. Mantenha o mesmo contrato no aplicativo: monte apenas as entradas que o agente deve usar, indique onde ele deve ler e gravar e verifique os artefatos gerados antes de usá-los.

Gerencie segredos e credenciais

Forneça as credenciais do sandbox pela configuração de execução e mantenha-as fora dos prompts. O agente pode precisar de credenciais para acessar gerenciadores de pacotes, montagens de armazenamento ou APIs de provedores. Essas credenciais não devem aparecer nos prompts dos usuários, nas instruções do agente, nos arquivos de tarefas, nos manifestos incluídos em commits ou nos artefatos gerados.

Siga estas regras:

• Para sandboxes hospedados, prefira os sistemas de gerenciamento de segredos nativos do provedor.
• Limite o escopo das credenciais de armazenamento em nuvem à montagem ou à opção do provedor que precisa delas.
• Use Manifest.environment para os valores de que o processo do sandbox precisa na inicialização. Marque entradas sensíveis ou geradas como temporárias quando quiser recriá-las em vez de persistir seus valores.
• Evite salvar segredos, configurações de montagem geradas, tokens locais ou arquivos que não devam ser mantidos após a execução.
• Revise os artefatos antes de transferi-los para fora do sandbox, especialmente quando o agente puder ler documentos privados ou dados em armazenamento montado.

O SDK aceita valores de ambiente definidos no manifesto e credenciais de montagem específicas de cada provedor. A integração com um repositório de segredos depende do provedor. Cabe ao ambiente de execução ou ao provedor de sandbox injetar as credenciais, sem fornecê-las ao modelo como instruções.

Adicione capacidades ao agente

As capacidades associam comportamentos nativos do sandbox a um SandboxAgent. Elas podem preparar o espaço de trabalho antes do início da execução, acrescentar instruções específicas do sandbox, disponibilizar ferramentas vinculadas à sessão ativa e ajustar o comportamento do modelo ou o processamento das entradas para aquele agente.

Por padrão, um SandboxAgent inclui capacidades de sistema de arquivos, shell e compactação. Se você fornecer uma lista de capabilities, ela substituirá a lista padrão. Inclua nela todas as capacidades padrão de que o agente ainda precisar.

Prefira as capacidades integradas quando elas atenderem às suas necessidades. Crie uma capacidade personalizada apenas quando precisar de uma ferramenta ou de uma interface de instruções específica do sandbox que as capacidades integradas não ofereçam.

Carregue habilidades

Algumas tarefas exigem que instruções reutilizáveis, scripts, referências ou recursos estejam disponíveis antes de o agente começar. Use a capacidade Skills para que o agente possa descobrir esse contexto de trabalho durante a execução.

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

Escolha a origem das habilidades de acordo com a forma como elas devem ser disponibilizadas no sandbox:

• Para diretórios locais de habilidades maiores, use um diretório local com carregamento sob demanda se quiser que o modelo consulte primeiro o índice e carregue apenas o necessário.
• Use um diretório local para disponibilizar um pequeno conjunto local de habilidades logo no início.
• Use um repositório Git quando o conjunto de habilidades tiver seu próprio ciclo de lançamentos ou for usado por vários sandboxes.

Exponha prévias e portas

Às vezes, o artefato é um processo em execução. Use uma porta exposta quando o agente criar um aplicativo local, um notebook, um servidor de relatórios, uma prévia no navegador ou outro serviço que você precise inspecionar de fora do sandbox.

A configuração das portas varia conforme o provedor, mas o contrato do produto é o mesmo. O agente inicia o serviço dentro do sandbox, o cliente de sandbox expõe a porta e seu aplicativo compartilha a URL da prévia ou a acessa para inspecionar o resultado.

Execute um agente de sandbox

O ciclo básico para trabalhar com um sandbox consiste nas seguintes etapas:

1. Crie um Manifest que descreva o espaço de trabalho.
2. Crie um SandboxAgent com as capacidades de que o modelo precisa.
3. Escolha um cliente de sandbox para o ambiente em que o trabalho será realizado.
4. Execute o agente com a configuração de sandbox específica dessa execução.
5. Inspecione ou copie os artefatos relevantes para seu aplicativo, retome o trabalho com eles ou salve-os em um snapshot.

Para desenvolvimento local no macOS ou no Linux, comece com Unix-local. Ele simplifica o ciclo de desenvolvimento porque o executor pode criar um espaço de trabalho temporário a partir do manifesto padrão do agente e removê-lo após a execução.

Se você usa o SDK para TypeScript, instale um interpretador confiável do Python 3 no host antes de criar uma sessão com UnixLocalSandboxClient. O SDK usa o Python para acessar arquivos locais de forma protegida e procura o interpretador nos caminhos /usr/bin/python3, /usr/local/bin/python3 e /opt/homebrew/bin/python3. Se o Python estiver instalado em outro local, defina a variável OPENAI_AGENTS_PYTHON no ambiente do host com o caminho absoluto do executável antes de iniciar o Node.js. A instalação do interpretador é um pré-requisito do host. Instalar o pacote dentro do sandbox não atende a esse requisito. Se nenhum interpretador Python adequado estiver disponível, a criação da sessão falhará.

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 exemplos locais completos, consulte o guia de início rápido de agentes de sandbox em TypeScript e o arquivo unix_local_runner.py em Python.

Troque de provedor

Escolha o provedor na configuração da execução. A definição do agente independe dessa escolha. Mantenha o SandboxAgent, o manifesto e as capacidades e troque o cliente de sandbox e as opções do provedor de acordo com o ambiente desejado.

Este exemplo usa o Docker para obter isolamento local em um contêiner. Os provedores hospedados seguem o mesmo padrão, cada um com suas próprias classes de cliente e opções.

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 exemplos que você pode executar, consulte o guia de clientes de sandbox e o exemplo básico em TypeScript. No repositório do SDK, os exemplos em Python incluem basic.py para selecionar o provedor, docker_runner.py para usar o Docker e main.py para trabalhar com uma sala de dados.

Padrões avançados

Depois que o ciclo básico estiver funcionando, você pode usar sandboxes em fluxos nos quais o agente precisa de um espaço de trabalho e ampliar o contexto do prompt seria insuficiente. Os exemplos a seguir ilustram padrões de fluxo de trabalho que usam a mesma API. O mesmo harness pode encaminhar etapas, pausar, retomar e rastrear o fluxo, enquanto cada sandbox executa as tarefas junto aos arquivos, às ferramentas e às portas necessários.

Retome o trabalho ou prepare uma execução futura

O trabalho de um agente muitas vezes se estende por mais de uma solicitação. Um usuário pode precisar revisar um artefato, uma etapa pode exigir aprovação ou a próxima etapa pode depender de um evento futuro.

Diferencie estas três formas de preservar o estado:

Na prática, o executor determina qual sessão de sandbox usar na seguinte ordem:

1. Se você fornecer uma sessão de sandbox ativa, o executor a reutilizará diretamente.
2. Caso contrário, se a execução estiver sendo retomada a partir de RunState, o executor usará o estado armazenado da sessão de sandbox para retomá-la.
3. Caso contrário, se você fornecer explicitamente um estado de sandbox serializado, o executor retomará a sessão a partir desse estado.
4. Nos demais casos, o executor criará uma nova sessão de sandbox. Para essa sessão, ele usará o manifesto fornecido para a execução ou, se nenhum for fornecido, o manifesto padrão do agente.

O exemplo de retomada do sandbox serializa o estado da sessão interrompida, retoma a sessão pelo mesmo cliente e passa a sessão retomada para a execução seguinte:

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)

Entradas para novas sessões, como manifest e snapshot, só se aplicam quando o executor cria uma sessão de sandbox. Se você injetar uma session ativa, o processamento das capacidades poderá adicionar entradas compatíveis que não sejam montagens. No sandbox já em execução, esse processamento não poderá alterar a raiz, o ambiente, os usuários ou os grupos, remover entradas existentes, substituir tipos de entrada nem adicionar ou alterar montagens.

Com essa divisão, o harness pode retomar o ciclo do agente enquanto o provedor de sandbox restaura ou recria o espaço de trabalho. Para ver exemplos atuais dessas opções, consulte o exemplo de retomada do estado da sessão em TypeScript e os arquivos main.py e sandbox_agent_with_remote_snapshot.py em Python.

Preserve a memória entre execuções

A memória do sandbox permite que o agente aprenda com execuções anteriores. Ela é distinta da memória de conversa de Session gerenciada pelo SDK. As sessões preservam o histórico de mensagens. Já a memória do sandbox reúne as lições úteis de execuções anteriores no espaço de trabalho em arquivos que o agente pode ler mais tarde.

Use a memória quando o agente precisar aproveitar preferências do usuário, correções, lições específicas do projeto ou resumos de tarefas sem reproduzir todos os turnos anteriores. A retomada e os snapshots preservam o estado do espaço de trabalho. A memória preserva orientações reutilizáveis extraídas do trabalho realizado nesse espaço.

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

Por padrão, a memória permite tanto a leitura quanto a geração de novas memórias. A leitura requer acesso ao shell para que o agente possa buscar e abrir arquivos de memória. Por padrão, as atualizações durante a execução também requerem acesso ao sistema de arquivos para que o agente possa corrigir informações desatualizadas ou atualizar a memória a pedido do usuário.

Na leitura, o agente acessa a memória em níveis crescentes de detalhe. O SDK injeta memory_summary.md no início da execução. Quando um trabalho anterior parece relevante, o agente pesquisa em MEMORY.md e abre os resumos das execuções apenas se precisar de mais detalhes.

Por padrão, os artefatos de memória ficam no espaço de trabalho do 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/

Durante a sessão de sandbox, o ambiente de execução acrescenta segmentos de cada execução. Quando a sessão termina, o processo de geração de memória primeiro extrai resumos das conversas e memórias brutas. Em seguida, consolida essas memórias em MEMORY.md e memory_summary.md. Para reutilizar a memória em outra execução, preserve os diretórios de memória configurados. Você pode manter a mesma sessão de sandbox ativa, retomá-la a partir do estado da sessão, iniciar uma sessão a partir de um snapshot ou montar armazenamento persistente, como o S3.

Para chats com vários turnos no sandbox, use uma sessão estável do SDK junto com a mesma sessão de sandbox ativa. Para agrupar execuções, a memória usa o primeiro identificador disponível nesta ordem: o ID explícito da conversa, o ID da sessão do SDK, o ID do grupo de execuções e, por fim, um ID gerado para cada execução. O ID da sessão de sandbox identifica o espaço de trabalho ativo. A memória usa um ID distinto para identificar a conversa.

Para ver exemplos que você pode executar, consulte o guia de memória em TypeScript. Em Python, consulte memory.py para um fluxo com snapshots locais, memory_s3.py para armazenar memórias no S3 e memory_multi_agent_multiturn.py para manter estruturas de memória separadas por agente.

Combine agentes de sandbox

Você pode combinar agentes de sandbox com os demais recursos do SDK.

Use uma transferência entre agentes quando um agente de triagem que opera fora do sandbox precisar delegar a um agente de sandbox apenas a parte do fluxo que faz uso intensivo do espaço de trabalho. A execução principal continua, mas o agente de sandbox passa a ser o agente ativo no turno seguinte.

Use agentes como ferramentas quando um orquestrador externo precisar chamar um ou mais agentes de sandbox como ferramentas aninhadas. Cada agente usado como ferramenta pode ter sua própria configuração de execução do sandbox, seu cliente de sandbox, seu manifesto e suas opções de provedor.

Para ver exemplos, consulte handoffs.py e sandbox_agents_as_tools.py.

Provedores de sandbox

Comece com Unix-local para testar alterações rapidamente no ambiente local ou com Docker quando precisar de isolamento local em contêineres. Passe para um provedor hospedado quando a tarefa exigir execução gerenciada, isolamento específico do provedor, escalabilidade, prévias, montagens de armazenamento, snapshots ou credenciais que devam ficar fora do servidor do seu aplicativo.

Consulte a documentação de cada provedor para saber como ele lida com configuração, credenciais, isolamento, armazenamento, prévias e persistência.