Arquitetura

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

Componentes da arquitetura

• Harness: 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: Local onde o agente executa comandos e código e trabalha com arquivos. O ambiente pode ser um sandbox remoto, seu notebook, um contêiner Docker ou uma função do AWS Lambda.
• Servidor do aplicativo: Código que você usa para conectar o agente ao seu produto. Ele envia tarefas, recebe eventos e trata chamadas a ferramentas de função. Quando você fornece o ambiente, seu código também gerencia o ciclo de vida desse ambiente.

Comece com os componentes necessários para a tarefa. O harness pode funcionar sem um ambiente, e seu aplicativo pode acompanhar o progresso por streaming ou webhooks.

Comece sem um ambiente

Um agente que responde a perguntas ou usa ferramentas para acessar serviços externos pode dispensar recursos computacionais ou arquivos próprios. Defina environment.type como none. O trecho a seguir mostra a configuração do ambiente. Para criar a sessão, também é preciso informar um agente e uma entrada inicial.

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

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

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 espaço de trabalho e os servidores MCP do executor ficam indisponíveis.

O ambiente de execução virtual opcional mostrado na figura disponibiliza 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 tratando chamadas a ferramentas de função.

A seta tracejada se aplica apenas quando você gerencia o próprio ambiente, conforme descrito a seguir.

Consulte Ambientes hospedados pela OpenAI para conhecer 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 roda os comandos e as ferramentas que o harness solicita. Seu aplicativo gerencia a conexão e o ciclo de vida do ambiente sem precisar encaminhar cada comando.

Você é responsável por provisionar o ambiente, restabelecer a conexão, encerrar o ambiente e preservar os arquivos necessários. O servidor do aplicativo ou um manipulador de webhooks pode cuidar dessas tarefas.

Antes de desligar os recursos computacionais, coordene a chegada de novas tarefas e confirme que não há execuções pendentes.

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

Receba atualizações de progresso e resultados

Qualquer que seja a configuração do ambiente, você pode usar uma das opções a seguir ou combinar as duas.

• Streaming: Receba eventos detalhados enquanto o agente trabalha, como a saída que você pode exibir no seu produto.
• Webhooks: Receba notificações de mudanças no estado da sessão sem manter um fluxo de eventos aberto. Seu manipulador pode recuperar resultados, executar ferramentas de função ou gerenciar um ambiente com hospedagem própria.

As ferramentas de função precisam de um manipulador que receba as chamadas e retorne os resultados. Se o 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 da sessão e Webhooks para saber mais sobre a integração.