Como colocar seu primeiro agente para rodar na Agents API da OpenAI

Fala aí, beleza? A OpenAI pegou o harness que já roda o Codex e expôs ele como serviço gerenciado, com orquestração, sessões longas e uso de ferramentas 😀

Ou seja: dá pra disparar uma tarefa, fechar o terminal, ir tomar um café e a sessão continua lá, guardando a configuração, a conversa e o trabalho salvo

A Agents API foi anunciada em beta público no dia 10/09/2026, disponível para todos os desenvolvedores da API, com iteração rápida rumo à disponibilidade geral (dá pra ler o anúncio em Introducing the Agents API)

Neste guia a gente vai da chave até a primeira execução acompanhada até o fim: criar a sessão, expor uma ferramenta, disparar a tarefa e conferir o estado depois. E fecho respondendo o que muda de fato em relação a rodar o Codex na sua máquina

O que você precisa antes de criar a primeira sessão

Nada de PC da Nasa aqui, o trabalho pesado roda do lado de lá. O que você precisa é bem curtinho:

• Conta de desenvolvedor na API da OpenAI, porque o beta público está liberado pra todos os devs da API
• Chave de API criada no dashboard, em platform.openai.com/api-keys
• A chave exportada como variável de ambiente, já que cada SDK da OpenAI lê ela automaticamente do ambiente
• SDK oficial da OpenAI (Python ou JavaScript), que já injeta o header de beta pra você
• Uma decisão de ambiente: sandbox hospedado pela OpenAI ou self-hosted

Sobre o header: as requisições da Agents API exigem OpenAI-Beta: agents=v1

Nos SDKs isso vai automático, no cURL você precisa incluir na mão

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

E essa história de Environment?

Environment é o sandbox opcional, o lugar onde as coisas realmente rodam quando a ferramenta precisa de um ambiente de execução

Com environment.type: "openai_hosted" você recebe um workspace Linux com Python, Node.js e ferramentas de linha de comando, provisionado e conectado pela própria OpenAI, configurado com workspace_directory e capability_directories. O agente roda código, lê e escreve arquivos, instala pacotes e gera artefatos

Com environment.type: "self_hosted" a lógica inverte: você roda o executor codex exec-server dentro do seu ambiente, e ele executa comandos de shell, lê e escreve arquivos e usa servidores MCP locais a pedido do harness. Aí a conexão e o ciclo de vida (provisionamento, reconexão, shutdown e preservação de arquivos) ficam com a sua aplicação

Se a ideia é ter uma máquina sua de plantão pra isso, vale dar uma olhada em como rodar agentes de IA numa VPS antes de escolher o caminho self-hosted

Tome cuidado! Tem duas limitações atuais que podem travar seu projeto antes mesmo da primeira linha de código: a Agents API suporta residência de dados apenas nos Estados Unidos e não suporta Zero Data Retention (ZDR)

Se o seu cliente exige ZDR ou dado fora dos EUA, melhor descobrir isso agora e não depois de três sprints, né? 😛

Passo a passo: do primeiro agente até a execução concluída

A sequência abaixo é a mesma que o quickstart oficial segue, com o erro comum de cada etapa logo embaixo

1. Criar a chave e exportar no ambiente:

Cria a chave no dashboard e joga ela pro ambiente

No macOS ou Linux:

export OPENAI_API_KEY="sua_chave"

No PowerShell:

setx OPENAI_API_KEY "sua_chave"

O erro comum deste passo: colar a chave direto no código. Não precisa, cada SDK da OpenAI lê a chave automaticamente do ambiente

2. Entender os quatro conceitos antes de escrever código:

A Agents API é organizada em quatro conceitos centrais, e entender eles agora economiza MUITA confusão depois:

• Agent: a configuração, ou seja, modelo, instruções, ferramentas e servidores MCP
• Environment: o sandbox opcional
• Session: a instância durável do agente
• Events/Items: as entradas e saídas

Se você conhece a diferença entre uma imagem e um container, é bem parecido: Agent é a receita, Session é a coisa viva rodando

O erro comum deste passo: tratar agente e sessão como a mesma coisa. Quem é durável, guarda a conversa e você recupera depois é a sessão

3. Criar a sessão e disparar a tarefa:

Aqui acontece tudo de uma vez: a chamada cria a sessão, envia a tarefa e, com stream, transmite o progresso na mesma requisição

Em Python, com o client do SDK já em mãos:

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Você é um agente de suporte ao meu projeto.",
    },
    environment={"type": "openai_hosted"},
    input="Liste os arquivos do workspace e resuma o que você encontrou.",
    stream=True,
)

Em JavaScript:

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions: "Você é um agente de suporte ao meu projeto.",
  },
  environment: { type: "openai_hosted" },
  input: "Liste os arquivos do workspace e resuma o que você encontrou.",
  stream: true,
});

O gpt-6-astra é o modelo usado nos exemplos oficiais do quickstart. Ele foi lançado em 03/09/2026 pra um conjunto limitado de organizações, com disponibilidade geral no dia seguinte, e roda via API da OpenAI, Microsoft Azure e AWS Bedrock

O erro comum deste passo: testar no cURL e esquecer o header de beta. Caso apareça erro logo na primeira chamada, confere se essa linha está lá:

OpenAI-Beta: agents=v1

4. Declarar a sua ferramenta em agent.tools:

Ferramenta própria é declarada na configuração do agente, dentro de agent.tools

E aqui vai a parte que pega muita gente: quem executa a função é a SUA aplicação. O modelo pede, você roda

agent={
    "model": "gpt-6-astra",
    "instructions": "Use a ferramenta quando precisar de dados do sistema.",
    "tools": [
        # definição da sua função aqui
    ],
}

Se a ferramenta precisa de um ambiente de execução de verdade (rodar código, mexer em arquivo, instalar pacote), aí você conecta um sandbox

O erro comum deste passo: achar que declarar a ferramenta já é o suficiente e esperar que ela rode sozinha lá do outro lado

5. Tratar o requires_action e devolver o resultado:

Quando a sessão fica com status requires_action, ela está esperando uma ação da sua aplicação

O caminho é: receber o evento agent.session.requires_action, recuperar a sessão e inspecionar cada entrada de required_actions

São dois tipos:

• function_call: executa a função identificada por name com os arguments e devolve o resultado na mesma sessão, usando o turn_id e o call_id daquela ação
• environment_connection: conecta o ambiente identificado por environment_id

O erro comum deste passo: devolver o resultado sem amarrar no turn_id e no call_id corretos. É por esse par que a sessão sabe qual chamada você está respondendo

6. Identificar o fim do turno pelos eventos:

Três eventos indicam que o turno acabou:

• agent.session.turn.completed
• agent.session.turn.failed
• agent.session.turn.cancelled

Só que se liga nisso: a documentação orienta inspecionar TAMBÉM a saída do agente, porque um turno concluído não garante que toda ferramenta tenha tido sucesso

O erro comum deste passo: comemorar no turn.completed e nem olhar o que saiu. Turno concluído não é sinônimo de tudo certo

7. Conferir o estado e continuar o trabalho:

Com o turno encerrado, recupere a sessão pelo ID pra ler status, configuração do agente, ambiente e required_actions

Pra ver o que já aconteceu por lá, recupere os itens salvos da sessão

E como a sessão guarda configuração, conversa e trabalho salvo ao longo do tempo, você reutiliza o mesmo ID pra mandar mensagens de acompanhamento e seguir de onde parou

O erro comum deste passo: tratar queda de stream como falha da execução. Se o stream cair antes do fim, a orientação é recuperar a sessão e os itens salvos ANTES de tentar de novo, senão você duplica trabalho à toa

Recursos que valem ligar quando o agente cresce

O primeiro dia é fazer rodar. O segundo dia é fazer rodar sem torrar token e sem virar espaguete

Busca de ferramentas (tool_search): adicione tool_search como ferramenta no array tools e marque as que devem ser adiadas com defer_loading: true. O modelo busca e carrega as definições conforme precisa, o que ajuda a reduzir tokens e custo

Chamada programática de ferramentas: o agente roda chamadas em paralelo, encadeia operações relacionadas e filtra ou combina resultados em código. Se você já brincou de rodar vários agentes em paralelo, a ideia de coordenar trabalho concorrente vai soar familiar

Compactação automática de contexto: ao se aproximar do limite de contexto, a API compacta o contexto anterior preservando o que o agente precisa pra continuar. Isso permite fluxos que atravessam várias janelas de contexto sem você escrever lógica própria de compactação, o que é bem massa

Servidores MCP e orquestração multiagente: o harness do Codex exposto pela API já traz suporte a servidores MCP e orquestração multiagente

E o custo disso tudo?

Não existe taxa adicional pela Agents API em si: você paga apenas pelos tokens e ferramentas que seus agentes consomem

A conta soma tokens de modelo, ferramentas fornecidas pela OpenAI e taxas de container quando o sandbox é hospedado pela OpenAI

A referência de preço do container hospedado é US$ 0,03 por sessão-container de 20 minutos na configuração de 1GB de memória

Só que esse valor é referência, e não um bloco fechado que você paga sempre inteiro: o faturamento das sessões elegíveis é por minuto, com mínimo de 5 minutos por sessão

Agents API x Codex CLI na sua máquina: o que muda de fato

O Codex CLI continua existindo e continua fazendo o que sempre fez: um agente de código leve que roda no seu terminal, inspeciona código, faz alterações, roda comandos e automatiza trabalho repetitivo. Dá pra usar interativo ou via codex exec em pipelines e fluxos repetíveis, e a instalação segue pelo npm com npm install -g @openai/codex (o projeto vive no repositório do Codex)

A Agents API é outra pegada: é o mesmo harness, só que gerenciado

Repara que não é briga de ferramenta: a Agents API nasceu da infraestrutura que já roda o Codex e dá acesso ao harness dele por uma API gerenciada

A sessão seguiu sem o seu terminal aberto? Como confirmar

Essa é a dúvida que mais aparece, então vamos direto: o stream é só uma janela de observação

Quem segura o trabalho é a sessão, que é durável e guarda configuração do agente, conversa e trabalho salvo ao longo do tempo

Pra confirmar que tudo seguiu, o roteiro é esse:

1. Recupere a sessão pelo ID e leia status, configuração do agente, ambiente e required_actions
2. Recupere os itens salvos da sessão pra inspecionar o que já aconteceu
3. Liste as sessões do projeto quando você perdeu o ID no meio do caminho (o SDK tem helpers de paginação)
4. Cancele o turno atual se a tarefa saiu do trilho: a sessão e o trabalho anterior continuam disponíveis
5. Delete sessões e artefatos publicados quando o assunto terminou de vez

E o veredito honesto? Se o seu caso é mexer no código do projeto que está aberto na sua máquina, rodar comando e ir vendo, o Codex CLI resolve e você não paga container nenhum

O gerenciado começa a valer quando a tarefa é longa, precisa sobreviver ao seu terminal, precisa ser disparada pela sua aplicação e precisa de estado consultável depois. Aí a conta de escrever sua própria lógica de sessão, compactação e recuperação fica bem mais cara que os tokens

Só não esquece das duas limitações atuais antes de prometer entrega pro cliente: residência de dados só nos EUA e sem ZDR

Conclusão

A Agents API está em beta público desde 10/09/2026, aberta pra todos os desenvolvedores da API e em iteração rápida rumo à disponibilidade geral, então espere mudança pelo caminho

O próximo passo concreto é bem simples: pega o ID daquela sessão que você acabou de criar e manda uma mensagem de acompanhamento nela, só pra sentir na prática o que significa "sessão durável"

Depois, se o seu agente precisar do seu próprio ambiente (suas credenciais, seus arquivos, seus servidores MCP locais), troca o openai_hosted por self_hosted e sobe o codex exec-server do seu lado

Qualquer coisa, volta nos passos e confere o header de beta antes de xingar a API, haha

até o próximo post! =)