OpenAI Agents API: como começar e evitar erros de custo e segurança

Resposta rápida

A OpenAI Agents API é indicada quando a aplicação precisa manter sessões duráveis, executar tarefas longas, usar ferramentas ou MCP, trabalhar em um ambiente isolado e retomar o agente depois. A OpenAI gerencia o harness, a orquestração, a compactação de contexto e a recuperação; a sua aplicação continua responsável pelas ferramentas, permissões, dados e escolha do ambiente.

O recurso entrou em beta pública em 10 de setembro de 2026. Para testar com segurança, comece com uma tarefa pequena em sandbox, sem credenciais de produção, acompanhe os eventos, defina limite de gasto e só depois conecte ferramentas externas.

O que a Agents API faz

A API organiza o trabalho em quatro conceitos: agente, ambiente, sessão e eventos. O agente reúne modelo, instruções e ferramentas. O ambiente oferece arquivos e execução. A sessão preserva o trabalho entre turnos. Os eventos mostram entradas, chamadas e resultados enquanto a tarefa avança.

O harness gerenciado pode executar código, editar arquivos, carregar skills, usar MCP, receber orientação durante a execução, delegar subtarefas e retomar uma sessão. Isso evita que cada equipe precise construir toda a camada de execução e continuidade por conta própria.

Agents API, Responses API e Agents SDK não são a mesma coisa

A Responses API atende chamadas de modelo e ferramentas controladas pela aplicação. O Agents SDK é uma biblioteca para montar a orquestração no código da equipe. A Agents API entrega o harness do Codex como serviço gerenciado, incluindo sessões e ambientes de execução.

Não migre apenas porque o nome é novo. Se o fluxo é curto e a aplicação já controla estado, ferramentas e execução com a Responses API, a Agents API pode adicionar complexidade e custo sem benefício claro. Ela ganha valor quando o trabalho precisa continuar por mais tempo, manipular arquivos, executar código, recuperar estado ou coordenar agentes.

Como criar a primeira sessão

O quickstart oficial usa o namespace beta.agents dos SDKs. No exemplo JavaScript, a instalação é feita com npm install openai. A criação da sessão informa o modelo, as instruções, o ambiente openai_hosted, a tarefa inicial e stream: true para acompanhar os eventos.

Teste primeiro uma tarefa reversível, como criar e executar um arquivo simples dentro do sandbox. Não use o primeiro teste para alterar um repositório, chamar uma API de produção ou acessar dados de clientes.

• Crie um projeto separado na plataforma da OpenAI e gere uma chave com os escopos mínimos necessários.
• Atualize o SDK oficial e confirme que a versão usada contém o namespace beta.agents.
• Crie uma sessão com instruções específicas, um ambiente isolado e uma tarefa curta.
• Leia os eventos transmitidos e registre o identificador da sessão sem salvar a chave em logs.
• Confirme os arquivos e resultados produzidos antes de enviar uma segunda tarefa para a mesma sessão.
• Exclua sessões e artefatos de teste quando não forem mais necessários.

Como evitar custos inesperados

A OpenAI informa que a Agents API não cobra uma taxa adicional própria. O custo vem do modelo escolhido, das ferramentas da OpenAI, do tempo de container no sandbox hospedado e de eventuais serviços de terceiros.

Uma única tarefa pode realizar várias chamadas de modelo. Subagentes, tentativas, histórico, arquivos e resultados de ferramentas também entram no consumo. Os campos de usage são estimativas de melhor esforço, podem ficar nulos ou mudar e não substituem a fatura.

• Defina limite de gasto e alerta no projeto antes do primeiro teste longo.
• Comece sem subagentes e aumente a concorrência somente quando houver ganho medido.
• Registre número de turnos, chamadas, duração do sandbox, ferramentas e tentativas.
• Compare o custo da tarefa concluída, não apenas tokens de uma resposta isolada.
• Mantenha instruções e definições de ferramentas estáveis quando isso ajudar o cache, sem assumir que haverá acerto de cache.

Como conectar MCP sem abrir acesso demais

A Agents API aceita MCP remoto por HTTP e MCP executado dentro do ambiente. Na conexão padrão pelo serviço, o endpoint precisa ser acessível pela OpenAI. Para rede privada ou servidor local ao sandbox, use connection_origin como environment ou transporte stdio em um ambiente compatível.

A posição da conexão muda a fronteira de rede e credenciais. Liste apenas as ferramentas necessárias, restrinja destinos e prefira leitura. Ações de escrita, publicação, exclusão, pagamento ou mudança de permissão devem exigir uma confirmação adequada fora do texto do prompt.

Credenciais e rede no sandbox

Código gerado pelo agente pode acessar arquivos, rede e credenciais disponíveis no ambiente. A documentação de segurança orienta isolar workloads, permitir tráfego somente para destinos aprovados e manter a chave principal da aplicação fora do executor.

Em ambientes próprios, a chave CODEX_API_KEY conecta o executor, mas pode ser lida pelo código executado. Credenciais de terceiros devem permanecer fora do sandbox quando possível e ser adicionadas por um broker apenas às solicitações aprovadas. Nunca grave tokens em código, imagem, prompt ou log.

• Separe usuários ou cargas que não podem compartilhar dados.
• Use uma lista curta de destinos de saída e revise onde cada MCP realiza a conexão.
• Conceda api.agents.read, api.agents.write e api.responses.write somente ao serviço que precisa deles.
• Mantenha a chave da aplicação fora do ambiente usado pelo agente.
• Revogue credenciais e interrompa a sessão se uma ferramenta sair do escopo esperado.

Observabilidade que precisa existir antes da produção

A sessão pode ser acompanhada pelos eventos, pelo histórico salvo e pelos registros do dashboard. Os turnos mostram o trabalho do agente principal e dos subagentes, além do uso de tokens quando disponível.

Registre sessão, turno, ferramenta, duração, resultado, aprovação e erro sem copiar segredos ou conteúdo desnecessário. Uma tarefa concluída não prova que o resultado está correto; valide o artefato produzido e crie testes para falhas, cancelamentos e retomadas.

Limitações verificadas da beta

Este guia foi verificado em 13 de setembro de 2026. A Agents API está em beta pública e usa o namespace beta.agents, portanto contratos e recursos podem mudar antes da disponibilidade geral. Fixe versões, acompanhe o changelog e valide atualizações em homologação.

A documentação informa que o estado das sessões é retido para permitir continuidade. Neste momento, a Agents API oferece residência de dados somente nos Estados Unidos e não oferece Zero Data Retention, mesmo quando o sandbox é próprio. Equipes com exigências de localização ou retenção precisam avaliar esse limite antes de enviar dados reais.

A página pública de status mostra disponibilidade agregada. Uma indicação normal não elimina erro restrito à sua conta, região, modelo, limite ou configuração. Use o identificador da requisição e os eventos da sessão para investigar problemas específicos.

Próxima ação útil

Crie uma prova de conceito que leia arquivos fictícios e produza um relatório, sem escrita externa. Defina antes os destinos de rede, o orçamento, o tempo máximo e os critérios de aprovação. Depois da execução, confira os eventos, o usage e os artefatos. Se houver falha ampla, consulte o status oficial; se apenas a sua integração falhar, revise chave, escopos, limites e conexão MCP.

Fontes consultadas

Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.

• Introducing the Agents APIOpenAI
• Agents API overviewOpenAI Developers
• Agents API quickstartOpenAI Developers
• Sandbox securityOpenAI Developers
• MCP connectionsOpenAI Developers
• Observability and usageOpenAI Developers
• OpenAI API pricingOpenAI Developers
• OpenAI StatusOpenAI