De modelo a agente: equipando a Responses API com um ambiente computacional

Estamos passando de usar modelos, que se destacam em tarefas específicas, para usar agentes capazes de lidar com fluxos de trabalho complexos. Ao escrever prompts para modelos, você acessa apenas a inteligência treinada. No entanto, dar ao modelo um ambiente computacional permite uma gama muito mais ampla de casos de uso, como executar serviços, solicitar dados de APIs ou gerar artefatos mais úteis, como planilhas ou relatórios.

Alguns problemas práticos surgem quando você tenta criar agentes: onde colocar arquivos intermediários, como evitar colar tabelas grandes em um prompt, como dar ao fluxo de trabalho acesso à rede sem criar uma dor de cabeça de segurança e como lidar com timeouts e retentativas sem precisar criar um sistema de fluxo de trabalho por conta própria.

Em vez de deixar a cargo dos desenvolvedores criar seus próprios ambientes de execução, construímos os componentes necessários para equipar a Responses API⁠(abre em uma nova janela) com um ambiente computacional para executar tarefas do mundo real com confiabilidade.

A Responses API da OpenAI, junto com a ferramenta shell e um workspace de container hospedado, foi projetada para resolver esses problemas práticos. O modelo propõe etapas e comandos; a plataforma os executa em um ambiente isolado com um sistema de arquivos para entradas e saídas, armazenamento estruturado opcional (como SQLite) e acesso à rede restrito.

Neste post, vamos detalhar como construímos um ambiente computacional para agentes e compartilhar alguns aprendizados iniciais sobre como usá-lo para fluxos de trabalho de produção mais rápidos, repetíveis e seguros.

Um bom fluxo de trabalho com agente começa com um loop de execução bem fechado: o modelo propõe uma ação, como ler arquivos ou buscar dados via API, a plataforma a executa e o resultado alimenta a próxima etapa. Vamos começar pela ferramenta shell — a forma mais simples de ver esse loop em ação — e depois abordar o workspace de container, rede, skills reutilizáveis e compactação de contexto.

Para entender a ferramenta shell, primeiro é útil entender como um modelo de linguagem usa ferramentas em geral: para coisas como chamar uma função ou interagir com um computador. Durante o treinamento, um modelo recebe exemplos de como as ferramentas são usadas e quais efeitos produzem, passo a passo. Isso ajuda o modelo a aprender quando usar uma ferramenta e como usá-la. Quando dizemos "usar uma ferramenta", queremos dizer que o modelo, na verdade, apenas propõe uma chamada de ferramenta. Ele não consegue executar a chamada por conta própria.

A ferramenta shell torna o modelo muito mais poderoso: ela interage com um computador pela linha de comando para realizar uma ampla gama de tarefas, de buscar texto a enviar requisições de API no seu computador. Baseada em ferramentas familiares do Unix, nossa ferramenta shell faz tudo que você espera, com utilitários como grep, curl e awk prontos para uso.

Em comparação com nosso code interpreter atual, que executa apenas Python, a ferramenta shell permite uma gama muito mais ampla de casos de uso, como executar programas em Go ou Java ou iniciar um servidor NodeJS. Essa flexibilidade permite que o modelo realize tarefas complexas com agentes.

Por conta própria, um modelo só consegue propor comandos shell — mas como esses comandos são executados? Precisamos de um orquestrador para obter a saída do modelo, invocar ferramentas e passar a resposta da ferramenta de volta ao modelo em um loop, até a tarefa ser concluída.

A Responses API é a forma como desenvolvedores interagem com modelos da OpenAI. Quando usada com ferramentas personalizadas, a Responses API devolve o controle ao cliente, e o cliente precisa de sua própria infraestrutura para executar as ferramentas. No entanto, essa API também pode orquestrar entre o modelo e ferramentas hospedadas, prontas para uso.

Quando a Responses API recebe um prompt, ela monta o contexto do modelo: prompt do usuário, estado da conversa anterior e instruções de ferramenta. Para a execução via shell funcionar, o prompt precisa mencionar o uso da ferramenta shell e o modelo selecionado precisa ser treinado para propor comandos shell — modelos GPT‑5.2 e posteriores são treinados para isso. Com todo esse contexto, o modelo decide a próxima ação. Se ele escolher a execução via shell, retorna um ou mais comandos shell para o serviço da Responses API. O serviço de API encaminha esses comandos para o runtime do container, transmite em streaming a saída do shell e a repassa ao modelo no contexto da próxima requisição. O modelo então pode inspecionar os resultados, emitir comandos de acompanhamento ou produzir uma resposta final. A Responses API repete esse loop até o modelo retornar uma resposta sem comandos shell adicionais.

Quando a Responses API executa um comando shell, ela mantém uma conexão de streaming com o serviço de container. À medida que a saída é produzida, a API a repassa ao modelo quase em tempo real, para que ele possa decidir se espera mais saída, executa outro comando ou segue para uma resposta final.

O modelo pode propor vários comandos shell em uma única etapa, e a Responses API pode executá-los de forma concorrente usando sessões de container separadas. Cada sessão transmite a saída em streaming de forma independente, e a API multiplexa esses streams de volta em saídas estruturadas de ferramenta como contexto. Em outras palavras, o loop do agente pode paralelizar o trabalho, como procurar em arquivos, buscar dados e validar resultados intermediários.

Quando o comando envolve operações com arquivos ou processamento de dados, a saída do shell pode ficar muito grande e consumir o orçamento de contexto sem agregar sinais úteis. Para controlar isso, o modelo especifica um limite de saída por comando. A Responses API impõe esse limite e retorna um resultado limitado que preserva tanto o começo quanto o fim da saída, indicando o conteúdo omitido. Por exemplo, você pode limitar a saída a 1.000 caracteres, preservando começo e fim:

texto no início ... 1000 caracteres truncados ... texto no fim

Juntas, a execução concorrente e a saída limitada tornam o loop do agente rápido e eficiente em contexto, para que o modelo continue raciocinando sobre resultados relevantes em vez de ser sobrecarregado por logs brutos do terminal.

Um possível problema com loops de agentes é que as tarefas podem rodar por muito tempo. Tarefas de longa duração preenchem a janela de contexto, que é importante para fornecer contexto entre turnos e entre agentes. Imagine um agente chamando uma skill, recebendo uma resposta, adicionando chamadas de ferramenta e resumos de raciocínio — a janela de contexto limitada se enche rapidamente. Para evitar perder o contexto importante à medida que o agente continua rodando, precisamos de uma forma de manter os detalhes-chave e remover o que for supérfluo. Em vez de exigir que desenvolvedores projetem e mantenham sistemas personalizados de sumarização ou de carregamento de estado, adicionamos compactação nativa na Responses API, projetada para se alinhar a como o modelo se comporta e a como foi treinado.

Nossos modelos mais recentes são treinados para analisar o estado anterior da conversa e produzir um item de compactação que preserva o estado-chave anterior em uma representação criptografada e eficiente em tokens.Após a compactação, a próxima janela de contexto consiste nesse item de compactação e em trechos de alto valor da janela anterior. Isso permite que fluxos de trabalho continuem de forma coerente entre limites de janelas, mesmo em sessões longas, com várias etapas e orientadas por ferramentas. O Codex depende desse mecanismo para sustentar tarefas longas de programação e execução iterativa de ferramentas sem degradar a qualidade.

A compactação está disponível tanto incorporada no servidor quanto por meio de um endpoint `/compact` independente. A compactação do lado do servidor permite configurar um limiar, e o sistema lida automaticamente com o momento da compactação, eliminando a necessidade de lógica complexa do lado do cliente. Ela permite uma janela efetiva de contexto de entrada um pouco maior para tolerar pequenas extrapolações logo antes da compactação, para que requisições perto do limite ainda possam ser processadas e compactadas, em vez de rejeitadas. À medida que o treinamento do modelo evolui, a solução nativa de compactação evolui com ele em cada lançamento de modelo da OpenAI.

O Codex nos ajudou a construir o sistema de compactação enquanto era um de seus primeiros usuários. Quando uma instância do Codex encontrava um erro de compactação, iniciávamos uma segunda instância para investigar. O resultado foi que o Codex ganhou um sistema de compactação nativo e eficaz simplesmente por trabalhar no problema. Essa capacidade do Codex de se inspecionar e se aprimorar tornou-se uma parte especialmente interessante de trabalhar na OpenAI. A maioria das ferramentas só exige que o usuário aprenda a usá-las; o Codex aprende junto conosco.

Agora vamos falar de estado e recursos. O container não é apenas um lugar para executar comandos, mas também o contexto de trabalho do modelo. Dentro do container, o modelo pode ler arquivos, consultar bancos de dados e acessar sistemas externos sob controles de política de rede.

A primeira parte do contexto do container é o sistema de arquivos para fazer upload, organizar e gerenciar recursos. Criamos APIs de container e de arquivos⁠(abre em uma nova janela) para dar ao modelo um mapa dos dados disponíveis e ajudá-lo a escolher operações de arquivo direcionadas, em vez de realizar varreduras amplas e ruidosas.

Um antipadrão comum é colocar toda a entrada diretamente no contexto do prompt.Um antipadrão comum é colocar toda a entrada diretamente no contexto do prompt. À medida que as entradas crescem, lotar o prompt se torna caro e difícil para o modelo navegar. Um padrão melhor é preparar os recursos no sistema de arquivos do container e deixar o modelo decidir o que abrir, analisar ou transformar com comandos de shell. Assim como os humanos, os modelos trabalham melhor com informações organizadas.

A segunda parte do contexto do container são os bancos de dados. Em muitos casos, sugerimos que os desenvolvedores armazenem dados estruturados em bancos de dados como o SQLite e façam consultas. Em vez de copiar uma planilha inteira para o prompt, por exemplo, você pode dar ao modelo uma descrição das tabelas — quais colunas existem e o que elas significam — e deixar que ele busque as linhas de que precisa.

Por exemplo, se você perguntar: "Quais produtos tiveram queda nas vendas neste trimestre?", o modelo pode consultar apenas as linhas relevantes em vez de varrer a planilha inteira. Isso é mais rápido, mais barato e mais escalável para conjuntos de dados maiores.

A terceira parte do contexto do container é o acesso à rede, uma parte essencial das cargas de trabalho com agentes. Um fluxo de trabalho de um agente pode precisar buscar dados em tempo real, chamar APIs externas ou instalar pacotes. Ao mesmo tempo, dar aos containers acesso irrestrito à internet pode ser arriscado: isso pode expor informações a sites externos, tocar inadvertidamente em sistemas internos sensíveis ou de terceiros, ou tornar mais difícil se proteger contra vazamentos de credenciais e exfiltração de dados.

Para lidar com essas preocupações sem limitar a utilidade dos agentes, criamos containers hospedados que usam um proxy sidecar de saída (egress). Todas as solicitações de rede de saída passam por uma camada centralizada de políticas que aplica listas de permissão e controles de acesso, mantendo o tráfego observável. Para credenciais, usamos injeção de segredos com escopo por domínio na saída (egress). O modelo e o container veem apenas placeholders, enquanto os valores brutos dos segredos ficam fora do contexto visível ao modelo e só são aplicados a destinos aprovados. Isso reduz o risco de vazamento e ainda permite chamadas externas autenticadas.

Comandos de shell são poderosos, mas muitas tarefas repetem os mesmos padrões de várias etapas. Os agentes precisam redescobrir o fluxo de trabalho a cada execução — replanejando, reenviando comandos e reaprendendo convenções — o que leva a resultados inconsistentes e execução desperdiçada. As skills de agentes⁠(abre em uma nova janela) empacotam esses padrões em blocos de construção reutilizáveis e componíveis. Na prática, uma skill é um bundle de pasta que inclui "SKILL.md⁠(abre em uma nova janela)" (contendo metadados e instruções) mais quaisquer recursos de suporte, como especificações de API e assets de UI.

Essa estrutura se encaixa naturalmente na arquitetura de runtime que descrevemos antes. O container fornece arquivos persistentes e contexto de execução, e a ferramenta shell fornece a interface de execução. Com ambos em funcionamento, o modelo pode descobrir arquivos de skill usando comandos de shell (`ls`, `cat`, etc.) quando precisar, interpretar instruções e executar scripts de skill — tudo no mesmo loop do agente.

Fornecemos APIs⁠(abre em uma nova janela) para gerenciar skills na plataforma da OpenAI. Desenvolvedores fazem upload e armazenam pastas de skill como bundles versionados, que depois podem ser recuperados pelo ID da skill. Antes de enviar o prompt ao modelo, a Responses API carrega a skill e a inclui no contexto do modelo. Essa sequência é determinística:

1. Recuperar metadados da skill, incluindo nome e descrição.
2. Recuperar o bundle da skill, copiá-lo para o container e descompactá-lo.
3. Atualizar o contexto do modelo com os metadados da skill e o caminho do container.

Ao decidir se uma skill é relevante, o modelo explora progressivamente suas instruções e executa seus scripts por meio de comandos de shell no container.

Para juntar todas as peças: a Responses API faz a orquestração, a ferramenta shell fornece ações executáveis, o container hospedado fornece um contexto de runtime persistente, as skills adicionam lógica de fluxo de trabalho reutilizável, e a compactação permite que um agente rode por muito tempo com o contexto de que precisa.

Com essas primitivas, um único prompt pode se expandir em um fluxo de trabalho de ponta a ponta: descobrir a skill certa, buscar dados, transformá-los em um estado estruturado local, consultá-lo com eficiência e gerar artefatos duráveis. 

O diagrama abaixo mostra como esse sistema funciona para criar uma planilha a partir de dados em tempo real.

Para um exemplo detalhado de como combinar a ferramenta shell e o ambiente computacional para fluxos de trabalho de ponta a ponta, veja nosso post no blog de desenvolvedores⁠(abre em uma nova janela) e o cookbook⁠(abre em uma nova janela), que mostram como empacotar uma skill e executá-la pela Responses API.

Estamos animados para ver o que os desenvolvedores vão construir com esse conjunto de primitivas. Modelos de linguagem foram feitos para mais do que gerar texto, imagens e áudio — vamos continuar evoluindo nossa plataforma para lidar, em escala, com tarefas complexas do mundo real.