Lucas

Posted on Oct 2 Originally published at apidog.com

Como usar a API de Agentes OpenAI?

#openai #ai #api #agents

A API OpenAI Agents executa para você o harness Codex de código aberto da OpenAI. Envie uma requisição POST https://api.openai.com/v1/agents/sessions com o cabeçalho OpenAI-Beta: agents=v1, a definição do 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 específica da API Agents: você paga por tokens, ferramentas e tempo de contêiner hospedado — de US$ 0,03 a US$ 0,48 por sessão de 20 minutos, conforme o sandbox de 1 GB a 16 GB. A API entrou em beta público em 10 de setembro de 2026, e a OpenAI adicionou uso de computador no DevDay em 29 de setembro.

Experimente o Apidog hoje

Neste guia, você vai criar uma sessão REST, acompanhar eventos, configurar ferramentas MCP e subagentes e implementar o fluxo de aprovação para uso de computador. Para comparar as 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. Como todas as chamadas são HTTP, você pode validá-las no Apidog antes de implementar a integração.

API OpenAI Agents em um relance

Item	Valor
Status	Beta público desde 10 de setembro de 2026; uso de computador adicionado em 29 de setembro
Criar uma sessão	`POST /v1/agents/sessions`
Cabeçalho beta	`OpenAI-Beta: agents=v1` — os SDKs da OpenAI o adicionam
Permissões de chave	`api.agents.read`, `api.agents.write`, `api.responses.write`
Preço	Sem taxa da API Agents; tokens do modelo a taxas de API e ferramentas a taxas padrão, como pesquisa web por US$ 10 a cada 1 mil chamadas
Contêineres hospedados	US$ 0,03 (`small`, 1 GB), US$ 0,12 (`medium`, 4 GB) e US$ 0,48 (`large`, 16 GB) por sessão de 20 minutos
Ambientes	`none`, `openai_hosted`, `self_hosted`
Modelo usado nos exemplos da documentação	`gpt-6-astra`
Controles de dados	Residência de dados apenas nos EUA; sem Retenção de Dados Zero (ZDR)
Tamanho máximo da requisição	4 MiB

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

Os quatro conceitos que você precisa configurar

A API é organizada em quatro partes:

Agente: modelo, instruções, ferramentas e servidores MCP. Você pode defini-lo inline ou salvar e reutilizar um agent_id.
Ambiente: sandbox ou computador opcional onde o agente lê arquivos e executa comandos.
Sessão: instância durável que preserva configuração, conversação e trabalho salvo.
Eventos e itens: eventos mostram o progresso em tempo real; itens guardam mensagens e chamadas de ferramentas.

Enviar uma mensagem para uma sessão ociosa inicia um turno. Enviar uma mensagem enquanto o turno está em execução direciona o agente. O harness — a instância hospedada do Codex que executa o modelo e o ciclo de ferramentas, conforme a página de arquitetura — também faz compactação de contexto automaticamente.

Escolha o ambiente de execução

Defina environment.type conforme o nível de execução necessário.

`none`

Use quando o agente não precisa executar código nem manipular arquivos.

Servidores MCP remotos e ferramentas de função continuam disponíveis.
Bash embutido, apply-patch, arquivos de workspace e MCPs executores não funcionam.

`openai_hosted`

Use quando o agente precisa de um sandbox Linux gerenciado pela OpenAI.

O ambiente inclui Python e Node.js em /workspace.
Escolha container_size: small (1 GB), medium (padrão, 4 GB) ou large (16 GB).
Configure network.access como enabled, disabled ou restricted.
Com rede restrita, defina allowed_domains.
Arquivos criados em /workspace/outputs tornam-se artefatos quando o turno termina.
Um sandbox ocioso sem keep-alives pode ser excluído após uma hora.

`self_hosted`

Use quando você precisa executar o ambiente na sua própria infraestrutura.

Execute codex exec-server em um laptop, contêiner ou sandbox remoto. Ele se conecta externamente usando uma chave de ambiente separada.

A postagem de lançamento lista Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop e Vercel como parceiros de sandbox. O guia de auto-hospedagem também inclui AWS Lambda MicroVMs.

Crie sua primeira sessão via REST

Primeiro, exporte uma chave com as permissões necessárias:

export OPENAI_API_KEY="sua_chave"

Em seguida, crie uma sessão com um contêiner pequeno e streaming ativado:

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 contém o stream de eventos do primeiro turno. Capture o ID da sessão e reutilize-o nas próximas operações.

Ação	Requisição
Acompanhar ou direcionar o agente	`POST /v1/agents/sessions/{id}/events` com `agent.session.input.message`
Cancelar o turno ativo	Mesmo endpoint, com `agent.session.input.cancel`
Ler trabalho salvo	`GET /v1/agents/sessions/{id}/items?order=asc&limit=100`
Excluir a sessão	`DELETE /v1/agents/sessions/{id}`

Faça o mesmo com o SDK JavaScript

O SDK JavaScript segue a mesma estrutura. Este exemplo adiciona pesquisa web, 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);

Use vault_ids quando ferramentas ou servidores MCP precisarem acessar credenciais armazenadas em um cofre.

Acompanhe o progresso com streaming ou webhooks

Streaming SSE

Abra o stream antes de enviar a entrada para evitar perder os eventos iniciais:

GET /v1/agents/sessions/{id}/events?stream=true
Accept: text/event-stream

Monitore principalmente:

agent.session.turn.output_text.delta e agent.session.turn.output_text.done para saída de texto;
agent.session.turn.completed, agent.session.turn.failed e agent.session.turn.cancelled para o estado final;
agent.session.requires_action quando o agente precisa de resultado de função, conexão de ambiente ou aprovação de uso de computador.

Evite estes erros comuns:

agent.session.idle não garante sucesso do turno.
Um turno concluído pode conter chamadas de ferramenta que falharam.
Fechar o stream não cancela a tarefa.
Streams não reproduzem eventos perdidos. Após desconectar, abra outro stream e consulte a sessão e seus itens.

Webhooks

Para tarefas longas, assine estes eventos:

agent.session.created
agent.session.action_required
agent.session.in_progress
agent.session.idle
agent.session.failed

Há uma diferença importante de nomenclatura:

No stream: requires_action
No webhook: action_required

Os payloads de webhook não incluem todos os detalhes da chamada. Portanto, seu handler deve recuperar a sessão e consultar required_actions.

Sempre valide a assinatura recebida. Veja verificação de assinatura de webhook. Para fluxos que podem levar vários minutos, consulte também operações de API de longa duração.

Configure ferramentas MCP, pesquisa de ferramentas e subagentes

Adicione um servidor MCP

Inclua o servidor em 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 cria a conexão com connection_origin: "service". Nesse caso, o servidor MCP deve estar acessível pela infraestrutura da OpenAI.

Use alternativas conforme a rede:

connection_origin: "environment" para servidores em rede privada;
stdio para iniciar o servidor dentro do sandbox;
transport.authorization para credenciais de uma sessão;
vault_ids para anexar credenciais de cofre, como static_bearer ou mcp_oauth.

Habilite pesquisa de ferramentas

Ferramentas MCP são descobertas automaticamente quando o modelo suporta pesquisa de ferramentas.

Se você tiver muitas ferramentas de função, reduza o contexto inicial adicionando:

{
  "type": "tool_search"
}

Depois, marque ferramentas que podem ser carregadas sob demanda:

{
  "defer_loading": true
}

Controle chamadas de ferramentas programáticas

Por padrão, o agente recebe uma ferramenta exec que executa JavaScript em um runtime V8 isolado. Isso permite agrupar chamadas de ferramentas e reduzir resultados antes que eles entrem no contexto do modelo.

Para desativar:

{
  "type": "programmatic_tool_calling",
  "enabled": false
}

Habilite subagentes

Configure subagentes assim:

{
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 3
  }
}

O limite padrão é 6 subagentes simultâneos.

Os subagentes:

compartilham o sistema de arquivos do ambiente;
herdam ferramentas MCP e pesquisa web;
não podem usar ferramentas de função.

Nos itens de um turno, subagent_id é null para o agente principal.

Implemente uso de computador com aprovação explícita

O uso de computador fornece um navegador hospedado ao agente. Para habilitá-lo, adicione a ferramenta e um desktop ao 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 exige aprovação do usuário antes de visitar cada nova origem, inclusive sites públicos.

Quando receber agent.session.requires_action:

Recupere a sessão.
Localize entradas computer_use_approval_request.
Inspecione o request.type.
Envie uma resposta pelo endpoint de eventos.

Há dois tipos de solicitação.

Aprovação de origem

Para browser_origin_access, mostre ao usuário:

origin
reason

Depois envie approve, deny ou cancel.

Autenticação no navegador

Para browser_authentication, você recebe:

campos de formulário em fields;
opções de login em options, quando disponíveis;
a origem da credencial em credential_origin.

Envie action: "submit" com os valores fornecidos pelo usuário ou action: "cancel".

Exemplo de aprovação de origem:

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 nos itens como computer_use_call. Cada item pode incluir:

id
turn_id
title
status
output

Com include_screenshots ativado, output pode carregar uma captura JPEG em base64. Não registre essas imagens em logs: elas podem conter dados de conta.

O guia de uso de computador destaca estas restrições:

Aprovar uma origem não confirma ações individuais, como compras ou exclusões.
Login cobre 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.
Desative tentativas automáticas para envios de credenciais: maxRetries: 0 no SDK ou --retry 0 no curl.
Uma resposta 202 significa apenas que a solicitação foi aceita.
Solicitações de autenticação expiram após cinco minutos.
A aprovação de origem não substitui a política de rede: permita também domínios de redirecionamento em network.

O resumo informa que o uso de computador é oferecido “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ê ao agente sua API, não sua UI

Use o navegador como alternativa para sistemas que não têm API. Se o sistema é seu, prefira expô-lo por um servidor MCP.

Isso oferece:

ferramentas tipadas;
resultados verificáveis;
menos dependência de fluxos visuais;
ausência de prompts de aprovação de origem para operações de API.

Leia Uso de computador vs APIs estruturadas para avaliar esse trade-off. O Apidog MCP Server pode usar sua especificação de API como base para o assistente de codificação criar esse wrapper.

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

Como a API está em beta, valide manualmente a estrutura de cada chamada no Apidog antes de integrá-la à aplicação.

Crie um ambiente no Apidog com OPENAI_API_KEY, VAULT_ID e SESSION_ID.
Envie Bearer {{OPENAI_API_KEY}} e OpenAI-Beta: agents=v1 em todas as requisições.
Crie a sessão sem stream, valide um status 2xx e confirme que o campo id não está vazio.
Extraia o id da resposta para SESSION_ID.
Abra o stream de eventos em uma requisição SSE.
Envie a entrada usando uma segunda requisição e acompanhe os eventos recebidos.
Salve payloads de aprovação e cancelamento para reproduzir cenários de required_actions.
Encadeie as requisições 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 inclui padrões de asserção para respostas não determinísticas. 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 seu modelo antes de adotar a integração.

A API Agents suporta Retenção Zero de Dados?

Não. Ela oferece residência de dados apenas nos EUA e não é elegível para ZDR, mesmo com sandbox auto-hospedado.

Qual é a diferença entre o SDK Agents e a API Responses?

O SDK executa o loop de agente dentro da sua aplicação. A API Responses é a chamada ao modelo em torno da qual você constrói seu próprio loop. Veja a comparação completa.

Comece com uma sessão somente leitura

Comece com um agente que apenas lê dados. Em seguida, adicione um servidor MCP. Só então habilite uso de computador, sempre atrás de um handler de aprovação que negue solicitações por padrão.

Quando o ChatGPT precisar reagir a eventos emitidos pelo seu próprio servidor, use Eventos MCP como a peça de integração.

DEV Community