Shell + Habilidades + Compactação: dicas para agentes de longa duração que fazem trabalho de verdade

Estamos passando de assistentes de um único turno para agentes de longa duração que realizam trabalho intelectual de verdade: ler grandes conjuntos de dados, atualizar arquivos e criar aplicativos.

Com base no feedback de desenvolvedores e na nossa própria experiência criando o Codex e agentes internos, estamos lançando um novo conjunto de primitivas agênticas que tornam o trabalho de longa duração mais viável:

• 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 um agente pode instalar dependências, executar scripts e gravar resultados (por exemplo, relatórios e artefatos).
• Compactação no servidor: uma maneira fácil de compactar automaticamente execuções agênticas longas para que você nunca atinja os limites de contexto.

A documentação e a referência da API abordam cada item acima individualmente. Este artigo se concentra nas dicas e nos padrões menos óbvios que, até agora, vimos funcionar melhor, tanto no nosso trabalho na OpenAI quanto em produção na Glean, uma das primeiras clientes a usar habilidades.

Um breve modelo mental

Habilidades: "procedimentos" que o modelo pode carregar sob demanda

Uma habilidade é um conjunto de arquivos acompanhado de um manifesto SKILL.md que contém frontmatter e instruções. Pense nela como um manual de procedimentos versionado que o modelo pode consultar na hora de fazer trabalho de verdade.

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 invocar uma habilidade. Se decidir usá-la, lê SKILL.md para obter o fluxo de trabalho completo.

Ferramenta de shell: "execução" para agentes

A ferramenta de shell permite que os modelos trabalhem em um ambiente de terminal real, em uma destas opções:

• Contêineres hospedados e gerenciados pela OpenAI.
• Um ambiente de execução de shell local que você mesmo executa (com a mesma semântica da ferramenta, mas com a máquina sob seu controle).

O shell hospedado funciona por meio da Responses API, o que significa que suas solicitações contam com execução com estado persistente, chamadas de ferramentas, continuidade entre turnos e artefatos.

Compactação: mantenha as execuções longas em andamento

À medida que os fluxos de trabalho se prolongam, eles esbarram nos limites da janela de contexto. A compactação no servidor mantém as execuções longas em andamento ao gerenciar a janela de contexto e compactar automaticamente o histórico da conversa.

A compactação na Responses API oferece duas maneiras de lidar com isso:

• Compactação no servidor (nova): quando o contexto ultrapassa o limite definido, a compactação ocorre automaticamente durante o fluxo, sem uma chamada separada de compactação.
• Endpoint independente de compactação: use /responses/compact quando quiser controlar explicitamente quando a compactação acontece.

Por que funcionam melhor em conjunto

• As habilidades reduzem o emaranhado de prompts ao reunir procedimentos e exemplos estáveis em um pacote reutilizável.
• O shell oferece um ambiente de execução completo, permitindo instalar código, executar scripts e gravar resultados.
• A compactação preserva a continuidade das execuções longas, para que o mesmo fluxo de trabalho continue em execução sem intervenções manuais no contexto.
• Juntos, esses recursos permitem fluxos de trabalho repetíveis com execução real, sem transformar seu prompt de sistema em um documento gigantesco e frágil.

Dicas e truques

1) Escreva as descrições das habilidades como lógica de roteamento (não como texto de marketing)

Na prática, a descrição da habilidade define os critérios de decisão do modelo. Ela deve responder:

• Quando devo usar isso?
• Quando não devo usar isso?
• Quais são os resultados e os critérios de sucesso?

Uma abordagem prática é incluir um bloco curto de "Use quando / Não use quando" diretamente na descrição, com informações concretas (entradas, ferramentas envolvidas e artefatos esperados).

2) Adicione exemplos negativos e casos extremos para reduzir acionamentos incorretos

Uma falha surpreendente é que disponibilizar habilidades pode, de início, reduzir os acionamentos corretos. Uma solução que vimos funcionar é combinar exemplos negativos com a cobertura de casos extremos.

Na prática, isso significa escrever alguns casos explícitos de "Não invoque esta habilidade quando..." (e o que fazer em vez disso). Isso ajuda o modelo a fazer um roteamento mais preciso, especialmente quando há várias habilidades que parecem semelhantes à primeira vista.

A Glean observou isso diretamente: o roteamento baseado em habilidades reduziu inicialmente os acionamentos em cerca de 20% em avaliações específicas. Depois, a taxa se recuperou quando a equipe adicionou exemplos negativos e cobertura de casos extremos às descrições.

3) Coloque modelos e exemplos dentro da habilidade (eles praticamente não têm custo quando não são usados)

Se você tem enchido o prompt de sistema de modelos, pare.

Modelos e exemplos resolvidos dentro das habilidades têm duas vantagens:

• Estão disponíveis exatamente quando são necessários (quando a habilidade é invocada).
• Não aumentam o consumo de tokens em consultas sem relação com a habilidade.

Isso é especialmente eficaz para entregas de trabalho intelectual, como:

• Relatórios estruturados.
• Resumos de triagem de casos escalados.
• Planos para contas de clientes.
• Relatórios de análise de dados.

A Glean relatou que esse padrão proporcionou alguns de seus maiores ganhos de qualidade e reduções de latência em produção, porque esses 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 de longa duração raramente têm sucesso com prompts one-shot. Planeje a continuidade desde o início:

• Reutilize o mesmo contêiner entre as etapas quando quiser manter dependências estáveis, arquivos em cache e resultados intermediários.
• Passe previous_response_id para que o modelo possa continuar o trabalho na mesma conversa.
• Use a compactação como uma primitiva padrão para execuções longas, não como uma alternativa de emergência.

Essa combinação reduz os reinícios e mantém a coerência das tarefas com várias etapas à medida que a conversa cresce.

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

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

Mas, ao executar um fluxo de trabalho em produção com um contrato claro (e quando você prefere determinismo a inventividade), basta dizer:

"Use a habilidade <skill name>."

Essa é a maneira mais simples de aumentar a confiabilidade. Ela transforma um roteamento impreciso em um contrato explícito.

6) Trate habilidades com acesso à rede como uma combinação de alto risco (planeje a contenção)

Essa é uma dica de segurança fácil de ignorar agora, mas cujas consequências são difíceis de corrigir depois.

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

Uma postura de segurança sólida por padrão:

• Habilidades: permitidas
• Shell: permitido
• Rede: habilitada apenas com uma lista mínima de permissões, por requisição, para tarefas com escopo bem delimitado

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

Nos fluxos de trabalho com shell hospedado, use /mnt/data como local padrão para gravar os resultados que você vai recuperar, revisar ou usar nas etapas seguintes. Alguns exemplos são relatórios, conjuntos de dados limpos e planilhas concluídas.

Uma boa forma de pensar nisso: as ferramentas gravam no disco, os modelos raciocinam sobre o conteúdo do disco e os desenvolvedores recuperam esse conteúdo.

8) Entenda as listas de permissões como um sistema de duas camadas (organização e requisição)

O acesso à rede é controlado em dois pontos:

• Uma lista de permissões da organização (configurada por um administrador), que define o conjunto máximo de destinos permitidos.
• Uma network_policy por requisição, que deve ser um subconjunto da lista de permissões da organização.

Duas implicações importantes para a operação:

1. Mantenha a lista de permissões da organização pequena e estável (o conjunto de “destinos aprovados em que você confia”).
2. Mantenha as listas de permissões das requisições ainda menores (o conjunto de “destinos necessários para esta tarefa específica”).

Se uma requisição incluir domínios que não estejam na lista de permissões da organização, ela retornará um erro.

9) Use domain_secrets para chamadas autenticadas (evite o vazamento de credenciais)

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

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

10) Use as mesmas APIs na nuvem e localmente

Você pode usar ambas as primitivas sem precisar hospedar tudo:

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

Um ciclo de desenvolvimento prático funciona assim:

1. Comece localmente (iterações rápidas, acesso a ferramentas internas e facilidade de depuração).
2. Migre para contêineres hospedados quando quiser repetibilidade, isolamento e consistência na implantação.
3. Mantenha as mesmas habilidades nos dois modos (o fluxo de trabalho permanece estável mesmo quando o local de execução muda).

Três padrões de desenvolvimento

Fique à vontade para experimentar essas novas primitivas agênticas. Aqui estão três exemplos de como combiná-las para criar aplicativos úteis.

Padrão A: Instalar -> buscar -> gravar artefato

Esta é a maneira mais simples de aproveitar o shell hospedado: um agente instala dependências, busca dados externos e produz uma entrega concreta.

Por exemplo:

• Instale algumas bibliotecas.
• Faça raspagem de dados ou chame uma API.
• Grave um relatório em /mnt/data/report.md.

Esse padrão é a base para agentes que realizam trabalho de verdade, pois estabelece um ponto claro de revisão: seu aplicativo pode mostrar o artefato ao usuário, registrá-lo em log, comparar suas versões ou usá-lo como entrada em uma etapa posterior.

Padrão B: Habilidades + shell para fluxos de trabalho repetíveis

Depois de criar um ou dois fluxos de trabalho bem-sucedidos com shell, você vai perceber o próximo problema: a solução funciona, mas a confiabilidade cai conforme os prompts se afastam da formulação original.

É aí que entram as habilidades. Veja uma estrutura que se sustenta ao longo do tempo:

1. Defina o fluxo de trabalho (etapas, mecanismos de proteção e modelos) em uma habilidade.
2. Monte a habilidade no seu ambiente de shell.
3. Faça o agente seguir a habilidade para produzir artefatos de forma determinística.

Isso é especialmente eficaz para 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 que encapsulam fluxos de trabalho empresariais

Um dos primeiros padrões que observamos foi a perda de precisão ao passar da chamada de uma única ferramenta para a orquestração de várias. As habilidades podem preencher essa lacuna ao fazer com que o raciocínio sobre o uso de ferramentas siga procedimentos, sem inflar os prompts de sistema.

Um exemplo concreto da Glean:

• Uma habilidade voltada ao Salesforce aumentou a precisão nas avaliações ( 73% -> 85% ) e reduziu o tempo até o primeiro token em 18,1%.
• As táticas práticas incluíram roteamento cuidadoso, exemplos negativos e a inclusão de modelos e exemplos dentro da habilidade.
• A Glean também usa habilidades para definir tarefas recorrentes em fluxos de trabalho empresariais, incluindo planejamento de contas, triagem de casos escalados e geração de conteúdo alinhado à marca.

É nesse tipo de uso que o potencial se revela. As habilidades se tornam POPs (procedimentos operacionais padrão) vivos: atualizados conforme a organização evolui e executados de forma consistente pelos agentes.

Crie uma vez, execute em qualquer lugar

Agentes de longa duração se tornam muito mais úteis quando conseguem tanto seguir procedimentos quanto realizar trabalho de verdade em um computador. Habilidades, shell hospedado e compactação criam essa base. Recapitulando:

• Use habilidades para definir como fazer (procedimentos, modelos e mecanismos de proteção).
• Use o shell para colocar em prática (instalar, executar e gravar artefatos).
• Use a compactação para manter a coerência de execuções longas (sem gerenciar o contexto manualmente).
• Comece localmente quando estiver iterando rapidamente.
• Migre para contêineres hospedados quando quiser uma execução repetível e isolada.
• Mantenha o acesso à rede restrito com listas de permissões por organização e por requisição, e use segredos de domínio para chamadas autenticadas.

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