Como usar a API de Agentes OpenAI?

A API OpenAI Agents executa o harness Codex de código aberto da OpenAI para você. Você envia POST https://api.openai.com/v1/agents/sessions com o cabeçalho OpenAI-Beta: agents=v1, uma definição de agente e uma tarefa; a OpenAI executa o modelo e o ciclo de ferramentas, mantém a sessão e pode provisionar um sandbox. Não há taxa da API Agents: você paga por tokens, ferramentas e tempo de contêiner hospedado (US$ 0,03 a US$ 0,48 por sessão de 20 minutos para tamanhos de sandbox de 1 GB a 16 GB). Ele entrou em beta público em 10 de setembro de 2026, e a OpenAI adicionou o uso de computador no DevDay em 29 de setembro.

Abaixo: uma primeira sessão REST, eventos de progresso, ferramentas MCP, subagentes e o fluxo de aprovação de uso de computador. Para saber como ele se compara com outras interfaces de agente da OpenAI, leia API Agents vs API Responses vs SDK Agents; para o restante do evento, veja o resumo do DevDay 2026. Cada chamada é HTTP puro, então você pode enviá-la do Apidog antes de escrever o código da aplicação.

API OpenAI Agents em um relance

Fontes: Apresentando a API Agents, a visão geral da API Agents e a página de preços.

Os quatro conceitos

A documentação estrutura a API em torno de quatro partes:

• Agente: o modelo, instruções, ferramentas e servidores MCP. Passe-o inline ou salve-o e reutilize seu agent_id.
• Ambiente: um sandbox ou computador opcional onde o agente lê arquivos e executa comandos.
• Sessão: uma instância durável do agente que mantém a configuração, conversação e trabalho salvo.
• Eventos e itens: eventos reportam o progresso ao vivo; itens são as mensagens e chamadas de ferramentas salvas.

Uma mensagem enviada a uma sessão ociosa inicia um novo turno; uma mensagem enviada no meio do turno o direciona. O harness (conforme a página de arquitetura, a instância hospedada do Codex que executa o modelo e o ciclo de ferramentas) também lida com a compactação de contexto, então você não precisa configurá-lo.

Escolha um ambiente

environment.type decide onde os comandos são executados:

• none: sem computação. Servidores MCP remotos e suas ferramentas de função ainda funcionam; Bash embutido, apply-patch, arquivos de workspace e MCPs executor não.
• openai_hosted: A OpenAI gerencia um sandbox Linux com Python e Node.js em /workspace. Defina container_size para small (1 GB), medium (padrão, 4 GB) ou large (16 GB), e network.access para enabled, disabled ou restricted com allowed_domains. Arquivos em /workspace/outputs tornam-se artefatos quando um turno é concluído. Um sandbox ocioso sem keep-alives pode ser excluído após uma hora.
• self_hosted: sua infraestrutura. Você executa codex exec-server em um laptop, contêiner ou sandbox remoto, e ele se conecta externamente com uma chave de ambiente separada.

A postagem de lançamento lista os parceiros de sandbox Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop e Vercel; o guia de auto-hospedagem adiciona AWS Lambda MicroVMs.

Sua primeira sessão via REST

Exporte uma chave com as permissões acima como OPENAI_API_KEY, então envie a tarefa de início rápido com um contêiner pequeno:

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

Com stream: true, a resposta é o stream de eventos do primeiro turno. Salve o ID da sessão a partir dela; o restante do ciclo de vida usa o mesmo recurso:

O SDK JavaScript tem a mesma forma. Esta versão, adaptada da postagem de lançamento, adiciona uma ferramenta, subagentes e um cofre:

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

Acompanhar o progresso: stream ou webhooks

Streaming. Abra GET /v1/agents/sessions/{id}/events?stream=true com Accept: text/event-stream antes de enviar a entrada, para não perder eventos iniciais. Fique atento a:

• agent.session.turn.output_text.delta e agent.session.turn.output_text.done para texto
• agent.session.turn.completed, agent.session.turn.failed ou agent.session.turn.cancelled para o resultado
• agent.session.requires_action quando o agente precisa de um resultado de função, uma conexão de ambiente ou uma aprovação de uso de computador

Três armadilhas: agent.session.idle não significa que o turno foi bem-sucedido, um turno concluído pode conter chamadas de ferramentas falhas, e fechar o stream não interrompe a tarefa. Streams não reproduzem eventos perdidos, então após uma desconexão, abra um novo stream e recupere a sessão e seus itens.

Webhooks. Assine agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle e agent.session.failed. Observe a nomenclatura: o stream diz requires_action, o webhook diz action_required. Os payloads omitem detalhes da chamada, então seu manipulador recupera a sessão e lê required_actions. Verifique cada assinatura (verificação de assinatura de webhook); operações de API de longa duração explica por que webhooks são adequados para tarefas de vários minutos.

Ferramentas MCP, pesquisa de ferramentas, chamada de ferramentas programática e subagentes

MCP. Adicione um servidor a agent.tools:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

Por padrão, a OpenAI faz a conexão (connection_origin: "service"), então o servidor deve ser acessível a partir da OpenAI. Use connection_origin: "environment" para um servidor de rede privada, ou stdio para iniciar um no sandbox. Para credenciais, passe transport.authorization para uma sessão, ou anexe uma credencial de cofre (static_bearer ou mcp_oauth) com vault_ids.

Pesquisa de ferramentas. As ferramentas MCP são descobertas automaticamente quando o modelo suporta pesquisa de ferramentas. Para muitas ferramentas de função, adicione {"type": "tool_search"} e marque as funções defer_loading: true.

Chamada de ferramentas programática. Ativado por padrão: o agente obtém uma ferramenta exec que executa JavaScript em um tempo de execução V8 isolado, para que possa fazer um loop sobre chamadas de ferramentas e cortar grandes resultados antes que cheguem ao contexto. Desative-o com {"type": "programmatic_tool_calling", "enabled": false}.

Subagentes. Defina multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (o limite padrão é 6). Os subagentes compartilham o sistema de arquivos do ambiente e herdam ferramentas MCP e pesquisa web, mas não podem usar ferramentas de função. O subagent_id de um turno é null para o agente principal.

Uso de computador: a adição do DevDay

O uso de computador oferece ao agente um navegador hospedado. Adicione a ferramenta e um desktop a um ambiente hospedado:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

O navegador precisa da aprovação do usuário antes de visitar cada nova origem de site, incluindo sites públicos. Em agent.session.requires_action, recupere a sessão e encontre as entradas computer_use_approval_request. O request.type aninhado é de um dos dois tipos:

• browser_origin_access: mostre origin e reason, então envie approve, deny ou cancel.
• browser_authentication: um formulário de login com fields, options de login opcionais e um credential_origin. Envie action: "submit" com os valores do usuário, ou action: "cancel".

Ambas as respostas voltam pelo endpoint de eventos:

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "agent.session.input.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

O trabalho do navegador aparece como itens computer_use_call com id, turn_id, title, status e output, que carrega uma captura de tela JPEG base64 quando include_screenshots está ativado e uma está disponível. Mantenha as capturas de tela fora dos logs; elas podem mostrar dados da conta.

O guia de uso de computador aponta estas ressalvas:

• A aprovação de origem não é uma confirmação de ação. Aprovar um site não faz o agente perguntar antes de cada compra ou exclusão. Se precisar disso, restrinja o navegador a recursos que não podem realizar essas ações, ou use um tempo de execução de navegador que você controla.
• O login abrange e-mail, senhas e códigos de verificação. Chaves de acesso e login por código QR não são suportados.
• Apenas o agente principal pode solicitar autenticação. Subagentes não podem.
• Desative as tentativas automáticas em envios de credenciais (maxRetries: 0 no SDK, --retry 0 no curl).
• Um 202 significa aceito, não que a navegação ou o login foi bem-sucedido. As requisições de autenticação expiram após cinco minutos.
• A aprovação de origem não anula a política de rede. Permita o site e seus domínios de redirecionamento também em network.

O resumo diz que o uso de computador é fornecido "através da API e no Codex e ChatGPT Work no Pro 500 e Enterprise." Para testes baseados em UI com o mesmo modelo, veja Uso de computador GPT-6 Astra para testes de API.

Dê a seu agente sua API, não sua UI

Um navegador é o substituto para software sem uma API. Se o sistema for seu, envolva-o em um servidor MCP: ferramentas tipadas, sem prompts de origem, resultados verificáveis. Uso de computador vs APIs estruturadas aborda o trade-off, e o Apidog MCP Server alimenta sua especificação de API para o assistente de codificação que escreve o wrapper.

Teste a API Agents no Apidog antes de escrever código

A API está em beta, então confirme a forma de cada chamada manualmente no Apidog primeiro:

1. Crie um ambiente Apidog com OPENAI_API_KEY, VAULT_ID e SESSION_ID. Envie Bearer {{OPENAI_API_KEY}} e OpenAI-Beta: agents=v1 em cada requisição.
2. Envie a requisição de criação de sessão sem stream, verifique um status 2xx e um id não vazio, e extraia id para SESSION_ID.
3. Abra o stream de eventos como uma requisição SSE, envie a entrada de uma segunda requisição e observe os eventos chegarem.
4. Salve os payloads de aprovação e cancelamento como requisições para reproduzir cada caso de required_actions.
5. Encadeie-os em um cenário de teste e execute-o em CI com o Apidog CLI.

O guia de teste de API de agente de IA possui padrões de asserção para saída não determinística. Baixe o Apidog para acompanhar.

Perguntas Frequentes

A API OpenAI Agents é gratuita? Não há taxa de plataforma, mas você paga por tokens do modelo, chamadas de ferramentas e tempo de contêiner hospedado.

Quais modelos funcionam com a API Agents? Os exemplos da documentação, incluindo todos os exemplos de uso de computador, usam gpt-6-astra. As páginas não listam outros modelos suportados, então teste o seu primeiro.

A API Agents suporta Retenção Zero de Dados? Não. Ela suporta residência de dados apenas nos EUA e não é elegível para ZDR, mesmo com um sandbox auto-hospedado.

Qual a diferença entre o SDK Agents e a API Responses? O SDK executa o loop dentro do seu aplicativo; a API Responses é a chamada do modelo em torno da qual você constrói um loop. Veja a comparação completa.

Comece com uma sessão somente leitura

Comece com uma sessão que apenas lê, adicione um servidor MCP, então adicione o uso de computador atrás de um manipulador de aprovação que nega por padrão. Quando o ChatGPT deve reagir a eventos do seu próprio servidor, em vez disso, Eventos MCP é a peça que se encaixa.