Arquitetura

A OpenAI executa o harness do agente. Seu aplicativo envia tarefas a ele e recebe resultados. Adicione um ambiente quando o agente precisar de recursos computacionais ou arquivos.

Os componentes

• Harness: A instância do Codex hospedada pela OpenAI que executa o ciclo de chamadas ao modelo e às ferramentas e mantém a sessão do agente.
• Ambiente: Onde o agente executa comandos e código e trabalha com arquivos. Um ambiente pode ser um sandbox remoto, seu notebook, um contêiner Docker ou uma função AWS Lambda.
• Servidor de aplicação: Seu código que conecta o agente ao seu produto. Ele envia tarefas, recebe eventos e processa chamadas de ferramentas de função. Quando você fornece o ambiente, seu código também gerencia o ciclo de vida dele.

Comece com os componentes necessários para sua tarefa. O harness pode funcionar sem um ambiente, e seu aplicativo pode receber atualizações de progresso por streaming ou webhooks.

Comece sem um ambiente

Um agente que responde a perguntas ou usa ferramentas para acessar serviços externos pode não precisar de recursos computacionais ou arquivos próprios. Defina environment.type como none. Este trecho mostra a configuração do ambiente. A criação de uma sessão também exige um agente e uma entrada inicial:

12345{
  "environment": {
    "type": "none"
  }
}

Seu aplicativo envia uma entrada para uma sessão. O harness chama o modelo, usa as ferramentas configuradas e retorna resultados. A OpenAI mantém a sessão para tarefas posteriores.

O harness pode chamar ferramentas MCP remotas diretamente. No caso das ferramentas de função, seu código recebe cada chamada, executa a função e retorna o resultado.

Sem um ambiente, as ferramentas integradas Bash e apply-patch, os arquivos do workspace e os MCPs do executor ficam indisponíveis.

O ambiente de execução virtual opcional mostrado aqui fornece arquivos e comandos de shell por meio das ferramentas de função do seu aplicativo.

Adicione um ambiente hospedado pela OpenAI

Quando o agente precisar executar scripts, editar arquivos ou criar artefatos, defina environment.type como openai_hosted. A OpenAI cria e gerencia um sandbox para a sessão.

Você configura os pacotes, os arquivos e o acesso à rede de que o agente precisa. O harness executa comandos diretamente no sandbox. Seu aplicativo continua enviando tarefas, recebendo eventos e processando chamadas de quaisquer ferramentas de função.

A seta tracejada se aplica apenas quando você gerencia o ambiente por conta própria, conforme descrito abaixo.

Consulte Ambientes hospedados pela OpenAI para ver as opções de configuração.

Conecte seu próprio ambiente

Use environment.type: "self_hosted" quando o agente precisar da sua infraestrutura, da sua rede privada ou de software personalizado.

Seu código inicia o ambiente e conecta um executor à sessão. O executor executa os comandos e as ferramentas solicitados pelo harness. Seu aplicativo gerencia a conexão e o ciclo de vida sem encaminhar cada comando.

Você é responsável pelo provisionamento, pela reconexão, pelo desligamento e por quaisquer arquivos que precise preservar. Seu servidor de aplicação ou um manipulador de webhooks pode gerenciar esse trabalho.

Antes de desligar os recursos computacionais, coordene as tarefas que chegam e confirme que não há nenhuma execução pendente.

Consulte Conectar um sandbox e Ciclo de vida do sandbox para ver os requisitos de configuração e desligamento.

Receba atualizações de progresso e resultados

Independentemente do ambiente escolhido, você pode usar uma ou ambas as opções a seguir:

• Streaming: Receba eventos detalhados enquanto o agente trabalha, como saídas para exibir no seu produto.
• Webhooks: Receba alterações no estado da sessão sem manter um fluxo de streaming aberto. Seu manipulador pode recuperar resultados, executar ferramentas de função ou gerenciar um ambiente hospedado em infraestrutura própria.

As ferramentas de função precisam de um manipulador que receba chamadas e retorne resultados. Se esse manipulador estiver indisponível, o agente pode ficar aguardando um resultado. Falhas nos manipuladores de eventos ou de ciclo de vida também podem interromper as atualizações de progresso ou o gerenciamento do ambiente.

Consulte Eventos de sessão e Webhooks para ver os detalhes de integração.