Shell + habilidades + compactação: dicas para agentes que executam tarefas reais de longa duração

Estamos passando de assistentes que respondem em uma única interação para agentes que trabalham por períodos mais longos em tarefas que exigem conhecimento, como ler grandes conjuntos de dados, atualizar arquivos e desenvolver aplicativos.

Com base no feedback de desenvolvedores e na nossa experiência ao desenvolver o Codex e agentes internos, estamos lançando novos recursos que tornam mais viável o trabalho de longa duração com agentes de IA:

• Habilidades (alinhadas ao padrão aberto Agent Skills): instruções reutilizáveis e versionadas que você pode montar em contêineres para que os agentes executem tarefas com mais confiabilidade.
• Ferramenta de shell aprimorada: um contêiner hospedado pela OpenAI com acesso controlado à internet, no qual o agente pode instalar dependências, executar scripts e gravar resultados, como relatórios e outros artefatos.
• Compactação no servidor: uma forma simples de compactar automaticamente o contexto de execuções longas com agentes de IA para que você nunca atinja os limites de contexto.

A documentação e a referência da API abordam cada recurso separadamente. Neste artigo, reunimos dicas e padrões menos óbvios que, até agora, deram os melhores resultados tanto no nosso trabalho na OpenAI quanto em produção na Glean, uma das primeiras empresas a usar habilidades.

Como esses recursos funcionam

Habilidades: “procedimentos” que o modelo pode carregar sob demanda

Uma habilidade reúne um conjunto de arquivos e um manifesto SKILL.md com metadados no cabeçalho e instruções. Pense nela como um guia de procedimentos versionado que o modelo pode consultar na hora de executar uma tarefa.

Quando há habilidades disponíveis, a plataforma apresenta ao modelo os campos name, description e path de cada uma. O modelo usa esses metadados para decidir se deve acionar uma habilidade. Se decidir usá-la, lê o SKILL.md para conhecer o fluxo de trabalho completo.

Ferramenta de shell: um ambiente de “execução” para agentes

Com a ferramenta de shell, os modelos podem trabalhar em um ambiente de terminal real de duas maneiras:

• Em contêineres hospedados e gerenciados pela OpenAI.
• Em um ambiente de shell local que você mesmo executa. A ferramenta funciona da mesma forma, e você controla a máquina.

O Shell hospedado funciona por meio da API Responses. Assim, suas solicitações podem manter o estado do trabalho, chamar ferramentas, dar continuidade à execução ao longo de várias interações e gerar artefatos.

Compactação: como dar continuidade a execuções longas

À medida que os fluxos de trabalho se estendem, eles atingem os limites da janela de contexto. A compactação no servidor permite que a execução continue ao gerenciar a janela de contexto e comprimir automaticamente o histórico da conversa.

A API Responses oferece duas formas de lidar com isso:

• Compactação no servidor (novidade): quando o contexto ultrapassa o limite configurado, a compactação ocorre automaticamente durante a transmissão da resposta, dispensando uma chamada separada.
• Endpoint independente de compactação: use /responses/compact quando quiser controlar explicitamente o momento da compactação.

Por que funcionam melhor em conjunto

• As habilidades simplificam os prompts ao reunir procedimentos estáveis e exemplos em um pacote reutilizável.
• O shell oferece um ambiente de execução completo para instalar código, executar scripts e gravar resultados.
• A compactação mantém a continuidade em execuções longas. Assim, o mesmo fluxo de trabalho pode prosseguir sem ajustes manuais no contexto.
• Juntos, esses recursos permitem repetir fluxos de trabalho que de fato executam as tarefas, sem transformar o prompt de sistema em um documento enorme e difícil de manter.

Dicas práticas

1) Escreva descrições de habilidades que orientem o roteamento, sem linguagem de marketing

Na prática, a descrição da habilidade define em quais situações o modelo deve escolhê-la. Ela deve responder às seguintes perguntas:

• Quando devo usar esta habilidade?
• Quando devo evitar usá-la?
• Quais são os resultados esperados e os critérios de sucesso?

Uma abordagem prática é incluir na própria descrição um bloco curto de “Quando usar e quando evitar”, com informações concretas sobre as entradas, as ferramentas envolvidas e os artefatos esperados.

2) Inclua exemplos negativos e casos de borda para reduzir erros de acionamento

Uma falha inesperada pode ocorrer no início: disponibilizar habilidades pode reduzir a frequência com que o modelo as aciona corretamente. Uma solução que vimos funcionar é combinar exemplos negativos com casos de borda.

Na prática, descreva algumas situações explícitas do tipo “Não acione esta habilidade quando…” e indique o que fazer em cada uma. Isso ajuda o modelo a escolher com mais precisão, especialmente quando várias habilidades parecem semelhantes à primeira vista.

A Glean observou isso em avaliações específicas: com o roteamento baseado em habilidades, a taxa de acionamento caiu inicialmente cerca de 20%, mas se recuperou depois que a equipe incluiu exemplos negativos e casos de borda nas descrições.

3) Coloque modelos de documento e exemplos dentro da habilidade (o custo é praticamente zero enquanto ela não é usada)

Se você costuma encher o prompt de sistema com modelos de documento, pare.

Manter modelos de documento e exemplos completos dentro das habilidades tem duas vantagens:

• Eles ficam disponíveis no momento em que são necessários, quando a habilidade é acionada.
• Eles não aumentam o consumo de tokens em consultas sem relação com a habilidade.

Isso funciona especialmente bem em tarefas que exigem conhecimento e geram resultados como:

• Relatórios estruturados.
• Resumos da triagem de casos escalados.
• Planos de gestão de contas de clientes.
• Análises de dados por escrito.

Segundo a Glean, essa abordagem trouxe alguns dos maiores ganhos de qualidade e reduções de latência em produção, porque os exemplos só são carregados quando a habilidade é acionada.

4) Planeje execuções longas desde o início com reutilização de contêineres e compactação

Agentes que realizam tarefas de longa duração raramente têm sucesso apenas com prompts one-shot. Planeje desde o início como o trabalho terá continuidade:

• Reutilize o mesmo contêiner entre as etapas quando precisar manter as dependências estáveis, os arquivos em cache e os resultados intermediários.
• Passe previous_response_id para que o modelo continue o trabalho na mesma conversa.
• Adote a compactação como parte padrão de execuções longas, sem esperar por uma emergência para usá-la.

Essa combinação reduz a tendência de recomeçar o trabalho e mantém a coerência entre as etapas à medida que a conversa cresce.

5) Quando precisar de determinismo, diga explicitamente ao modelo qual habilidade usar

Por padrão, o modelo decide quando usar uma habilidade. Muitas vezes, é isso mesmo que você quer.

Mas, se o fluxo de trabalho está em produção, tem um contrato claro e você prefere que a escolha da habilidade seja determinística, basta dizer:

“Use a habilidade <skill name>.”

Essa é a maneira mais simples de aumentar a confiabilidade. Uma instrução explícita elimina a ambiguidade na escolha da habilidade.

6) Trate a combinação de habilidades e acesso à rede como de alto risco e planeje medidas de contenção

É fácil deixar essa dica de segurança passar agora e difícil corrigir o problema depois.

Combinar habilidades com acesso irrestrito à rede cria uma via de alto risco para a exfiltração de dados. Se usar acesso à rede, restrinja as listas de destinos permitidos, trate a saída das ferramentas como não confiável e evite combinar acesso irrestrito à internet com procedimentos poderosos em fluxos voltados ao consumidor nos quais os usuários esperam controles rigorosos de confirmação.

Uma configuração padrão segura:

• Habilidades: permitidas
• Shell: permitido
• Rede: habilitada apenas com uma lista mínima de destinos permitidos, definida por solicitação, para tarefas de escopo delimitado

7) Use /mnt/data como ponto de entrega dos artefatos

Nos fluxos de trabalho com o Shell hospedado, use /mnt/data como local padrão para gravar resultados que você pretende recuperar, revisar ou encaminhar às etapas seguintes. Alguns exemplos são relatórios, conjuntos de dados após a limpeza e planilhas finalizadas.

Uma forma simples de pensar nisso: as ferramentas gravam no disco, os modelos raciocinam com base no que está no disco e os desenvolvedores recuperam os resultados do disco.

8) Entenda as duas camadas de destinos permitidos: organização e solicitação

O acesso à rede é controlado em dois níveis:

• A lista de destinos permitidos da organização, configurada por um administrador, define o conjunto máximo de destinos acessíveis.
• A network_policy de cada solicitação só pode incluir destinos que constem na lista da organização.

Na prática, isso tem duas implicações:

1. Mantenha a lista da organização pequena e estável, com os “destinos aprovados em que você confia”.
2. Mantenha as listas de cada solicitação ainda menores, com os “destinos necessários para esta tarefa específica”.

Se uma solicitação incluir domínios fora da lista da organização, a API retornará um erro.

9) Use domain_secrets em chamadas autenticadas para evitar o vazamento de credenciais

Se um domínio permitido exigir cabeçalhos de autenticação, use domain_secrets para que o modelo nunca veja os valores reais das credenciais.

Durante a execução, o modelo vê marcadores de posição, como $API_KEY, e um contêiner auxiliar injeta os valores reais apenas para destinos aprovados. Essa é uma boa prática padrão sempre que o agente precisar chamar uma API protegida de dentro de um contêiner.

10) Use as mesmas APIs na nuvem e localmente

Você pode usar os dois recursos sem precisar hospedar tudo:

• As habilidades funcionam tanto com o Shell hospedado quanto com o shell em modo local.
• O shell tem um modo de execução local no qual você mesmo executa shell_call e devolve shell_call_output ao modelo.
• Se usar o Agents SDK, você também pode integrar seu próprio executor de shell.

Um ciclo de desenvolvimento prático segue estas etapas:

1. Comece localmente para iterar com rapidez, acessar ferramentas internas e facilitar a depuração.
2. Passe para contêineres hospedados quando precisar de repetibilidade, isolamento e consistência na implantação.
3. Use as mesmas habilidades nos dois modos. O fluxo de trabalho permanece estável mesmo quando o ambiente de execução muda.

Três padrões de desenvolvimento

Você pode experimentar esses novos recursos para trabalhar com agentes de IA. Veja três exemplos de como combiná-los para criar aplicativos úteis.

Padrão A: instalar -> buscar dados -> gravar um artefato

Esta é a forma mais simples de aproveitar o Shell hospedado: um agente instala dependências, busca dados externos e produz um resultado concreto.

Por exemplo:

• Instale duas bibliotecas.
• Extraia dados de uma página ou chame uma API.
• Grave um relatório em /mnt/data/report.md.

Esse padrão serve de base para agentes que realizam tarefas reais porque cria um ponto claro de revisão. Seu aplicativo pode mostrar o artefato ao usuário, registrá-lo, comparar versões ou usá-lo como entrada em uma etapa posterior.

Padrão B: habilidades e shell para fluxos de trabalho repetíveis

Depois de criar um ou dois fluxos de trabalho que funcionam bem no shell, você vai perceber o próximo problema: à medida que os prompts se afastam do original, o fluxo perde confiabilidade.

É aí que entram as habilidades. Você pode adotar esta estrutura para manter o fluxo confiável ao longo do tempo:

1. Registre o fluxo de trabalho em uma habilidade, incluindo etapas, salvaguardas e modelos de documento.
2. Monte a habilidade no ambiente de shell.
3. Instrua o agente a seguir a habilidade para produzir os artefatos de forma determinística.

Isso funciona especialmente bem em fluxos de trabalho como:

• Análise ou edição de planilhas.
• Limpeza de conjuntos de dados e geração de resumos.
• Geração de relatórios padronizados para processos de negócio recorrentes.

Padrão C (avançado): habilidades para incorporar fluxos de trabalho empresariais

Algo que observamos logo no início foi uma queda na precisão ao passar da chamada de uma única ferramenta para a coordenação de várias. As habilidades podem recuperar essa precisão ao dar ao modelo procedimentos para orientar seu raciocínio sobre o uso das ferramentas, sem aumentar o tamanho dos prompts de sistema.

Um exemplo concreto da Glean:

• Uma habilidade voltada ao Salesforce elevou a precisão nas avaliações de 73% para 85% e reduziu o tempo até o primeiro token em 18,1%.
• Entre as técnicas adotadas estavam a definição criteriosa do roteamento, o uso de exemplos negativos e a inclusão de modelos de documento e exemplos na própria habilidade.
• A Glean também usa habilidades para registrar tarefas recorrentes em fluxos de trabalho empresariais, como o planejamento de contas de clientes, a triagem de casos escalados e a geração de conteúdo alinhado à marca.

É aqui que as habilidades mostram seu potencial. Elas se tornam procedimentos operacionais padrão (POPs) que acompanham a evolução da organização e que os agentes executam de forma consistente.

Desenvolva uma vez e execute em qualquer lugar

Agentes de longa duração se tornam muito mais úteis quando conseguem seguir procedimentos e realizar tarefas reais em um computador. As habilidades, o Shell hospedado e a compactação oferecem a base para isso. Em resumo:

• Use habilidades para definir como realizar o trabalho, com procedimentos, modelos de documento e salvaguardas.
• Use o shell para executar as tarefas, como instalar dependências, rodar scripts e gravar artefatos.
• Use a compactação para manter a coerência em execuções longas sem precisar gerenciar o contexto manualmente.
• Comece localmente quando precisar iterar com rapidez.
• Passe para contêineres hospedados quando quiser execuções repetíveis e isoladas.
• Restrinja o acesso à rede com listas de destinos permitidos por organização e por solicitação, e use segredos de domínio em chamadas autenticadas.

Comece no seu próprio aplicativo. Para saber como, consulte a documentação de habilidades, a documentação do shell e a documentação de compactação.