Do modelo ao agente: equipar a Responses API com um ambiente computacional

Estamos a passar de usar modelos, que se destacam em tarefas específicas, para usar agentes capazes de gerir fluxos de trabalho complexos. Ao dar prompts a modelos, só é possível aceder à inteligência treinada. No entanto, ao dar ao modelo um ambiente computacional, é possível abranger uma gama muito mais ampla de casos de uso, como executar serviços, solicitar dados a APIs ou gerar artefactos mais úteis, como folhas de cálculo ou relatórios.

Ao tentar criar agentes, surgem alguns problemas práticos: onde colocar ficheiros intermédios, como evitar colar tabelas grandes num 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 novas tentativas sem construir um sistema de fluxo de trabalho do zero.

Em vez de exigir que os programadores criem os seus próprios ambientes de execução, construímos os componentes necessários para equipar a Responses API⁠(abre numa nova janela) com um ambiente computacional capaz de executar, de forma fiável, tarefas do mundo real.

A Responses API da OpenAI, juntamente com a ferramenta shell e uma área de trabalho de contentores alojados, foi concebida para resolver estes problemas práticos. O modelo propõe passos e comandos; a plataforma executa-os num ambiente isolado com um sistema de ficheiros para entradas e saídas, armazenamento estruturado opcional (como o SQLite) e acesso à rede restrito.

Neste artigo, explicamos como construímos um ambiente computacional para agentes e partilhamos algumas lições iniciais sobre como o usar para fluxos de trabalho de produção mais rápidos, mais repetíveis e mais seguros.

Um bom fluxo de trabalho de agente começa com um ciclo de execução curto: o modelo propõe uma ação, como ler ficheiros ou obter dados através de uma API, a plataforma executa-a e o resultado alimenta o passo seguinte. Vamos começar pela ferramenta shell — a forma mais simples de ver este ciclo em ação — e depois abordar a área de trabalho de contentores, o acesso à rede, as skills reutilizáveis e a compactação de contexto.

Para compreender a ferramenta shell, é útil primeiro entender como um modelo de linguagem usa ferramentas em geral: para fazer coisas como chamar uma função ou interagir com um computador. Durante o treino, o modelo vê exemplos de como as ferramentas são usadas e dos efeitos resultantes, passo a passo. Isto ajuda o modelo a aprender a decidir quando usar uma ferramenta e como a usar. Quando dizemos «usar uma ferramenta», queremos dizer que o modelo, na realidade, apenas propõe uma chamada à ferramenta. Não consegue executar essa chamada por si só.

A ferramenta shell torna o modelo drasticamente mais poderoso: interage com um computador através da linha de comandos para realizar uma vasta gama de tarefas, desde procurar texto até enviar pedidos a APIs a partir do computador. Assente em ferramentas Unix familiares, a nossa ferramenta shell consegue fazer tudo o que se espera, com utilitários como grep, curl e awk disponíveis logo à partida.

Em comparação com o nosso interpretador de código atual, que só executa Python, a ferramenta shell permite uma gama muito mais vasta de casos de uso, como executar programas em Go ou Java ou iniciar um servidor NodeJS. Esta flexibilidade permite ao modelo executar tarefas complexas e orientadas por agentes.

Por si só, um modelo só consegue propor comandos de shell, mas como é que esses comandos são executados? Precisamos de um orquestrador para receber a saída do modelo, invocar ferramentas e devolver ao modelo a resposta da ferramenta num ciclo, até a tarefa estar concluída.

A Responses API é a forma como os programadores interagem com os modelos da OpenAI. Quando usada com ferramentas personalizadas, a Responses API devolve o controlo ao cliente, e o cliente precisa do seu próprio mecanismo para executar as ferramentas. No entanto, esta API também pode, logo à partida, orquestrar a interação entre o modelo e ferramentas alojadas.

Quando a Responses API recebe um prompt, constrói o contexto do modelo: prompt do utilizador, estado da conversa anterior e instruções das ferramentas. Para a execução via shell funcionar, o prompt tem de referir a utilização da ferramenta shell e o modelo selecionado tem de estar treinado para propor comandos de shell — os modelos GPT‑5.2 e posteriores são treinados para isso. Com todo este contexto, o modelo decide então a próxima ação. Se escolher executar via shell, devolve um ou mais comandos de shell ao serviço da Responses API. O serviço da API encaminha esses comandos para o runtime de contentores, transmite em streaming a saída da shell e fornece-a ao modelo no contexto do pedido seguinte. O modelo pode então analisar os resultados, emitir comandos de seguimento ou produzir uma resposta final. A Responses API repete este ciclo até o modelo devolver uma conclusão sem comandos de shell adicionais.

Quando a Responses API executa um comando de shell, mantém uma ligação em streaming ao serviço de contentores. À medida que a saída é produzida, a API retransmite-a ao modelo quase em tempo real, para que o modelo possa decidir se deve esperar por mais saída, executar outro comando ou avançar para uma resposta final.

O modelo pode propor vários comandos de shell num único passo, e a Responses API pode executá-los em simultâneo, usando sessões de contentor separadas. Cada sessão transmite a saída de forma independente, e a API combina esses streams em saídas estruturadas da ferramenta, como contexto. Por outras palavras, o ciclo do agente pode paralelizar trabalho, como pesquisar ficheiros, obter dados e validar resultados intermédios.

Quando o comando envolve operações sobre ficheiros ou processamento de dados, a saída da shell pode ficar muito grande e consumir o orçamento de contexto sem acrescentar sinais úteis. Para controlar isto, o modelo define um limite de saída por comando. A Responses API aplica esse limite e devolve um resultado limitado que preserva tanto o início como o fim da saída, assinalando o conteúdo omitido. Por exemplo, pode limitar a saída a 1 000 caracteres, preservando o início e o fim:

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

Em conjunto, a execução concorrente e a saída delimitada tornam o ciclo do agente rápido e eficiente em termos de contexto, para que o modelo possa continuar a raciocinar sobre resultados relevantes em vez de ficar sobrecarregado com logs brutos do terminal.

Um potencial problema nos ciclos de agente é que as tarefas podem demorar muito tempo. As tarefas de longa duração enchem a janela de contexto, que é importante para fornecer contexto entre turnos e entre agentes. Imagine um agente a chamar uma skill, a receber uma resposta, a acrescentar chamadas de ferramentas e resumos de raciocínio — a janela de contexto limitada enche-se rapidamente. Para evitar perder o contexto importante à medida que o agente continua a executar, precisamos de uma forma de manter os detalhes-chave e remover tudo o que for supérfluo. Em vez de exigir que os programadores concebam e mantenham sistemas personalizados de sumarização ou de transporte de estado, adicionámos compactação nativa na Responses API, concebida para se alinhar com a forma como o modelo se comporta e como foi treinado.

Os 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 anterior essencial numa representação encriptada e eficiente em termos de tokens.Após a compactação, a janela de contexto seguinte é composta por este item de compactação e por partes de alto valor da janela anterior. Isto permite que os fluxos de trabalho continuem de forma coerente entre janelas, mesmo em sessões prolongadas, com vários passos e orientadas por ferramentas. O Codex recorre a este mecanismo para sustentar tarefas de codificação de longa duração e a execução iterativa de ferramentas sem degradar a qualidade.

A compactação está disponível integrada no servidor ou através de um endpoint autónomo `/compact`. A compactação do lado do servidor permite configurar um limiar, e o sistema gere automaticamente o momento da compactação, eliminando a necessidade de lógica complexa do lado do cliente. Permite uma janela de contexto de entrada efetiva ligeiramente maior, para tolerar pequenas ultrapassagens imediatamente antes da compactação, para que pedidos perto do limite ainda possam ser processados e compactados, em vez de rejeitados. À medida que o treino dos modelos evolui, a solução de compactação nativa evolui com ele em cada lançamento de modelo da OpenAI.

O Codex ajudou-nos a construir o sistema de compactação enquanto foi um dos seus primeiros utilizadores. Quando uma instância do Codex tinha um erro de compactação, iniciávamos uma segunda instância para investigar. O resultado foi que o Codex obteve um sistema de compactação nativo e eficaz simplesmente por trabalhar no problema. Esta capacidade do Codex de se inspecionar e aperfeiçoar a si próprio tornou-se uma parte especialmente interessante do trabalho na OpenAI. A maioria das ferramentas apenas exige que o utilizador aprenda a usá-las; o Codex aprende connosco.

Agora, vamos abordar o estado e os recursos. O container não é apenas um local para executar comandos, mas também o contexto de trabalho do modelo. Dentro do container, o modelo pode ler ficheiros, consultar bases de dados e aceder a sistemas externos sob controlos de políticas de rede.

A primeira parte do contexto do container é o sistema de ficheiros para carregar, organizar e gerir recursos. Criámos APIs de container e de ficheiros⁠(abre numa nova janela) para dar ao modelo um mapa dos dados disponíveis e ajudá-lo a escolher operações de ficheiro direcionadas, em vez de executar varrimentos amplos e ruidosos.

Um antipadrão comum é colocar toda a entrada diretamente no contexto do prompt. À medida que as entradas crescem, encher demasiado o prompt torna-se dispendioso e difícil de o modelo percorrer. Um padrão melhor é preparar os recursos no sistema de ficheiros do container e deixar o modelo decidir o que abrir, analisar ou transformar com comandos de shell. Tal como os humanos, os modelos funcionam melhor com informação organizada.

A segunda parte do contexto do container são as bases de dados. Em muitos casos, sugerimos que os programadores armazenem dados estruturados em bases de dados como o SQLite e as consultem. Em vez de copiar, por exemplo, uma folha de cálculo inteira para o prompt, pode dar ao modelo uma descrição das tabelas — que colunas existem e o que significam — e deixá-lo obter as linhas de que precisa.

Por exemplo, se perguntar «Que produtos tiveram vendas em queda neste trimestre?», o modelo pode consultar apenas as linhas relevantes em vez de analisar toda a folha de cálculo. Isto é mais rápido, mais barato e mais escalável para conjuntos de dados maiores.

A terceira parte do contexto do contentor é o acesso à rede, uma componente essencial das cargas de trabalho dos agentes. O fluxo de trabalho do agente pode precisar de obter dados em tempo real, chamar APIs externas ou instalar pacotes. Ao mesmo tempo, dar aos contentores acesso irrestrito à internet pode ser arriscado: pode expor informação a websites externos, tocar inadvertidamente em sistemas internos sensíveis ou de terceiros, ou tornar mais difícil proteger contra fugas de credenciais e exfiltração de dados.

Para resolver estas preocupações sem limitar a utilidade dos agentes, criámos contentores alojados para usarem um proxy de egress em sidecar. Todos os pedidos de rede de saída passam por uma camada centralizada de políticas que aplica listas de permissões e controlos de acesso, mantendo o tráfego observável. Para credenciais, usamos injeção de segredos por domínio no egress. O modelo e o contentor só veem placeholders, enquanto os valores brutos dos segredos ficam fora do contexto visível para o modelo e só são aplicados para destinos aprovados. Isto reduz o risco de fuga de dados, mantendo a possibilidade de chamadas externas autenticadas.

Os comandos de shell são poderosos, mas muitas tarefas repetem os mesmos padrões em várias etapas. Os agentes têm de redescobrir o fluxo de trabalho a cada execução — voltando a planear, a emitir comandos e a reaprender convenções — o que leva a resultados inconsistentes e a execução desperdiçada. As skills de agentes⁠(abre numa nova janela) empacotam esses padrões em blocos reutilizáveis e combináveis. Em termos concretos, uma skill é um pacote de pastas que inclui ‘SKILL.md⁠(abre numa nova janela)’ (contendo metadados e instruções) e quaisquer recursos de apoio, como especificações de API e assets de UI.

Esta estrutura encaixa naturalmente na arquitetura de runtime que descrevemos anteriormente. O contentor fornece ficheiros persistentes e contexto de execução, e a ferramenta shell fornece a interface de execução. Com ambos no lugar, o modelo pode descobrir ficheiros de skills usando comandos de shell (`ls`, `cat`, etc.) quando necessário, interpretar instruções e executar scripts de skills — tudo no mesmo ciclo do agente.

Disponibilizamos APIs⁠(abre numa nova janela) para gerir skills na plataforma da OpenAI. Os programadores carregam e armazenam pastas de skills como bundles versionados, que podem mais tarde ser recuperados pelo ID da skill. Antes de enviar o prompt ao modelo, a Responses API carrega a skill e inclui-a no contexto do modelo. Esta sequência é determinística:

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

Ao decidir se uma skill é relevante, o modelo explora progressivamente as suas instruções e executa os seus scripts através de comandos de shell no contentor.

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

Com estes primitivos, um único prompt pode expandir-se para um fluxo de trabalho de ponta a ponta: descobrir a skill certa, obter dados, transformá-los num estado estruturado local, consultá-los de forma eficiente e gerar artefactos persistentes.

O diagrama abaixo mostra como este sistema funciona para criar uma folha de cálculo a partir de dados em tempo real.

Para um exemplo aprofundado de como combinar a ferramenta shell e o ambiente computacional em fluxos de trabalho de ponta a ponta, consulte o nosso post no blog para developers⁠(abre numa nova janela) e o cookbook⁠(abre numa nova janela), que explicam como empacotar uma skill e executá-la através da Responses API.

Estamos entusiasmados por ver o que os programadores constroem com este conjunto de primitivos. Os modelos de linguagem foram concebidos para fazer mais do que gerar texto, imagens e áudio — continuaremos a evoluir a nossa plataforma para se tornar mais capaz de lidar, à escala, com tarefas complexas do mundo real.