Construa com CometAPIPrecisa de uma API para vários modelos?Teste o fluxo no Playground e depois crie uma chave da API quando o modelo e o custo atenderem ao seu caso de uso.
A OpenAI Agents API é uma plataforma gerenciada para construir agentes de IA que raciocinam, usam ferramentas, executam código e concluem tarefas em múltiplas etapas. Foi projetada para aplicativos que precisam continuar o trabalho entre turnos, executar ferramentas e se recuperar de interrupções sem implementar todo o loop de agente por conta própria. Este guia ajuda desenvolvedores a avaliar suas capacidades, opções de integração e custos.
Ao contrário de uma API de LLM convencional, a OpenAI Agents API oferece sessões persistentes, ambientes de execução gerenciados, coordenação multiagente, eventos em streaming e artefatos. Os desenvolvedores podem usar endpoints nativos da OpenAI Agents API para execução gerenciada, ou integrar modelos OpenAI compatíveis via CometAPI para construir fluxos de trabalho de agentes personalizados. Estes são caminhos de integração distintos.
Principais conclusões
A OpenAI Agents API gerencia sessões persistentes e execução em múltiplas etapas, reduzindo a orquestração que os desenvolvedores precisam operar.
Revisado para maior clareza, atribuição de fontes e terminologia de API atual.
Suas capacidades centrais incluem execução de código em sandbox, ferramentas e conexões MCP, subagentes e artefatos salvos.
Os custos da OpenAI Agents API combinam tokens de modelo, ferramentas elegíveis e computação hospedada opcional; avalie o custo por tarefa concluída.
Ganhos relatados por clientes fornecem evidência específica de carga de trabalho, em vez de uma referência padronizada para todo aplicativo.
Execução gerenciada nativa e agentes personalizados usando CometAPI são escolhas de integração separadas com diferentes responsabilidades de infraestrutura.
O que é a OpenAI Agents API?
A OpenAI Agents API é um serviço de execução gerenciado para aplicativos que realizam tarefas em múltiplas etapas usando modelos de raciocínio e ferramentas externas. Ela expõe o harness de agente Codex como serviço. Em vez de gerenciar manualmente chamadas de modelo, execução de ferramentas, estado de sessão e recuperação de tarefas, os desenvolvedores podem delegar grande parte dessa coordenação ao runtime.
Um chatbot convencional gera uma resposta; um agente consegue planejar etapas, executar código em um ambiente autorizado, inspecionar erros, tentar novamente e entregar arquivos gerados. Isso torna a API adequada a fluxos de trabalho operacionais, e não apenas chat.
Fluxo de trabalho da OpenAI Agents API
Um fluxo de trabalho de agente reúne quatro partes: o agente define o modelo, as instruções e as ferramentas disponíveis; o ambiente fornece computação e acesso a arquivos; a sessão preserva o contexto e o trabalho salvo; e eventos e itens expõem o progresso e os resultados. Juntos, esses componentes permitem que seu aplicativo envie uma tarefa, acompanhe sua execução e continue o trabalho em turnos posteriores. Consulte a Visão geral da Agents API para os conceitos subjacentes.
Fluxo típico: criar uma sessão; enviar um objetivo; permitir que o modelo raciocine e escolha as ferramentas permitidas; executar essas ferramentas; inspecionar resultados intermediários; e transmitir o progresso e os artefatos finais. A sessão pode ser continuada conforme necessário.
O diagrama oficial mostra o aplicativo trocando entrada e eventos com o harness gerenciado e a sandbox. Diagrama de arquitetura da documentação de arquitetura da OpenAI Agents API; arte original por OpenAI.
Quais são os principais recursos da OpenAI Agents API?
As capacidades do harness gerenciado abrangem execução de código, gestão de contexto, conexões de ferramentas, direcionamento e delegação. A disponibilidade também depende do ambiente e das ferramentas configurados.
Recurso
Especificação
Benefício prático
Runtime gerenciado
Harness baseado em Codex
Reduz código de orquestração
Persistência de sessão
Estado multi-turno
Suporta trabalho de acompanhamento
Gestão de contexto
Compactação gerenciada
Fluxos de trabalho estendidos
Execução hospedada
Sandbox Linux; Python e Node.js
Execução real de código
Ambiente self-hosted
Computação gerenciada pelo dev
Controle de infraestrutura
Execução multiagente
Subagentes configuráveis
Subtarefas em paralelo
Conexões de ferramentas
Funções e MCP
Integra serviços
Uso do computador
Interação controlada com a UI
Automação de interface
Streaming e webhooks
Eventos de progresso
Aplicativos responsivos
Artefatos
Arquivos salvos
Relatórios entregáveis
Sessões persistentes e gestão de contexto
As sessões preservam configuração, contexto de conversa e trabalho salvo entre turnos. Os desenvolvedores podem enviar uma nova instrução a uma sessão existente; a gestão de contexto ajuda a sustentar tarefas prolongadas, reduzindo a necessidade de escrever lógica própria de compactação de transcrições.
Execução de código em sandbox
Ambiente
Infraestrutura
Melhor uso
none
Sem execução local
Fluxos de trabalho com ferramentas remotas
openai_hosted
Sandbox gerenciada pela OpenAI
Código, análise e processamento de arquivos
self_hosted
Computação controlada pelo dev
Infraestrutura personalizada
Ambientes hospedados podem executar programas em Python, Node.js e linha de comando em um workspace isolado. Um ambiente self-hosted permite que o agente gerenciado use computação controlada pelo desenvolvedor. Os desenvolvedores operam e protegem esse ambiente, enquanto a Agents API continua a gerenciar o harness do agente e o estado da sessão.
Colaboração multiagente
Um agente coordenador pode delegar tarefas independentes a subagentes especialistas. Agentes de pesquisa podem examinar fontes separadas enquanto um agente primário concilia evidências. O paralelismo pode melhorar a vazão, mas chamadas adicionais de modelo e coordenação podem aumentar a despesa. A API oferece configurações de concorrência e subagentes configuráveis.
OpenAI Agents API vs Agents SDK vs Responses API vs AgentKit
Dimensão
Agents API
Agents SDK
Responses API
AgentKit
Propósito
Execução gerenciada
Orquestração code-first
Inferência e ferramentas
Componentes de agente
Loop de agente
Gerenciado
App/SDK
Gerenciado pelo dev
Depende do componente
Infraestrutura
Hospedada ou externa
Controlada pelo dev
App + ferramentas hospedadas
Varia
Multiagente
Coordenação embutida
Handoffs
Personalizado
Específico do componente
Ideal para
Tarefas autônomas duráveis
Agentes personalizados
Controle granular
Ferramental de agente embutido
A Agents API fornece execução gerenciada; o Agents SDK é adequado para aplicativos que possuem sua pilha de orquestração; a Responses API é apropriada para inferência e fluxos de trabalho com ferramentas mais leves; o AgentKit fornece componentes de desenvolvimento complementares, em vez de outro runtime de agente hospedado equivalente.
Como começar com a OpenAI Agents API
Etapa 1: Configurar acesso à API
Use uma chave de projeto da OpenAI Platform com as permissões de agente e inferência exigidas pelos pré-requisitos do quickstart. Os exemplos com curl visam um shell compatível com Bash com curl instalado; o exemplo em PowerShell apenas define a variável de ambiente. Mantenha as chaves fora do controle de versão.
Exemplo de código Bash: execute os comandos a seguir em um terminal compatível com Bash.
export OPENAI_API_KEY="your-openai-api-key"
Exemplo de código PowerShell: defina a chave da API no processo atual do PowerShell.
$env:OPENAI_API_KEY="your-openai-api-key"
Etapa 2: Criar seu primeiro agente
Exemplo de código Bash: execute os comandos a seguir em um terminal compatível com Bash.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Write reliable Python code, execute it, and report observed results."
},
"environment": {"type": "openai_hosted", "container_size": "small"},
"input": "Calculate the mean and standard deviation of [12,15,19,20,24] in Python.",
"stream": true
}'
A sessão inicia seu primeiro turno e transmite eventos de status conforme o agente executa ferramentas e prepara uma resposta.
Etapa 3: Habilitar execução multiagente
Exemplo de código Bash: execute os comandos a seguir em um terminal compatível com Bash.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Delegate independent analyses and reconcile the results.",
"multi_agent": {"enabled": true, "max_concurrent_subagents": 2}
},
"environment": {"type": "none"},
"input": "Compare two release changes: date filtering in search and export URL behavior.",
"stream": true
}'
Etapa 4: Continuar uma sessão existente
Exemplo de código Bash: execute os comandos a seguir em um terminal compatível com Bash.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.message","input":[{"role":"user","content":[{"type":"input_text","text":"Summarize the findings in an executive report."}]}]}]}'
Armazene identificadores de sessão, aplique salvaguardas de retry e distinga novas instruções de mensagens usadas para direcionar trabalho ativo.
Etapa 5: Inspecionar resultados e limpar
Exemplo de código Bash: execute os comandos a seguir em um terminal compatível com Bash.
O esforço de raciocínio afeta latência, consumo de tokens e profundidade de planejamento. Selecione o esforço suportado pelo modelo escolhido e pela interface usando a orientação oficial do GPT-6; configurações em nível de modelo não devem ser presumidas como aplicáveis de forma idêntica a todos os endpoints.
Como construir um agente de IA com CometAPI?
A CometAPI pode fornecer inferência de modelo para um aplicativo de agente personalizado. Seu aplicativo permanece responsável pelo loop do agente, execução de ferramentas, estado de sessão, recuperação e qualquer roteamento entre modelos compatíveis. Isso dá controle sobre a orquestração, mas também torna essa infraestrutura sua para operar.
Escolha a integração nativa da Agents API quando você quiser que a OpenAI gerencie a execução do agente e o estado da sessão. Escolha um aplicativo baseado em CometAPI quando quiser construir e operar sua própria orquestração em torno de APIs de modelos compatíveis. O acesso a um modelo via CometAPI não estabelece por si só suporte aos endpoints nativos de sessão da Agents API; verifique a interface que você pretende usar. Os custos também seguem caminhos diferentes: o uso nativo é faturado pela OpenAI, enquanto um aplicativo personalizado combina cobranças da CometAPI com seus custos de infraestrutura.
Etapa 1: Conectar-se à CometAPI
Exemplo de código Bash: execute os comandos a seguir em um terminal compatível com Bash.
Exemplo de código Python: envie uma solicitação de inferência de modelo e imprima a resposta.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.responses.create(
model="gpt-6-astra",
input=(
"Analyze an API latency spike after a database migration. "
"Identify possible causes and prioritize diagnostic steps."
),
)
print(response.output_text)
Os desenvolvedores podem acessar a GPT-6 Astra API na CometAPI. O exemplo acima realiza inferência de modelo; implementar o loop de ferramentas descrito abaixo é uma responsabilidade separada do aplicativo.
Etapa 2: Adicionar uma camada de execução de ferramentas
Um controlador personalizado pode instruir o modelo, inspecionar solicitações de chamada de ferramentas, autorizar e executar ações, retornar resultados e repetir até a conclusão ou um limite predefinido. Defina limites de turnos, chamadas de ferramentas, tempo de execução e gastos; exija confirmação independente para operações destrutivas.
Quais são as melhores aplicações da OpenAI Agents API?
Engenharia de software: analisar problemas, gerar alterações de código, executar testes e preparar revisões, com aprovação antes de mesclar ou implantar mudanças.
Análise e relatório de dados: processar datasets enviados, executar cálculos em Python, criar gráficos e transformar os resultados em relatórios que apoiem decisões.
Resposta a incidentes de TI: inspecionar alertas, correlacionar logs, consultar runbooks e recomendar remediação, com autorização humana para ações arriscadas.
Automação de suporte ao cliente: recuperar registros relevantes, resumir tickets, redigir respostas e encaminhar casos não resolvidos via acesso CRM permitido.
Pesquisa e processamento de documentos: comparar documentos, verificar alegações, extrair fatos e preparar conclusões com citações de apoio.
Avalie seu fluxo de trabalho
Comece com uma tarefa representativa de sua própria carga de trabalho e defina como é uma conclusão bem-sucedida. Compare o agente com seu processo atual usando as mesmas entradas e critérios de aceitação. Inclua solicitações de acompanhamento e falhas de ferramentas para que a avaliação teste a recuperação, bem como o caminho ideal.
Métrica
Mede
Motivo
Conclusão da tarefa
Objetivos bem-sucedidos
Utilidade de ponta a ponta
Sucesso de ferramentas
Integrações corretas
Detecção de falhas
Taxa de recuperação
Conclusão após falha
Durabilidade
Tempo para conclusão
Tempo decorrido
Latência
Custo por tarefa concluída
Despesa / tarefa bem-sucedida
Eficiência
Intervenção humana
Ações manuais
Autonomia
Conformidade de segurança
Adesão a políticas
Controle de risco
Leia essas medidas em conjunto. Um fluxo de trabalho que conclui mais tarefas ainda pode ser uma má escolha se exigir correções manuais frequentes ou exceder seus limites de tempo e custo. Use os resultados para decidir onde automatizar, onde manter revisão humana e quais falhas abordar antes de expandir o uso.
Quanto custa a OpenAI Agents API?
Não há taxa separada da plataforma de harness gerenciado. Tokens de modelo, chamadas de ferramentas elegíveis e computação hospedada opcional determinam o custo total de uso. As tarifas de modelo abaixo estão em USD por milhão de tokens para processamento Standard com prompts de contexto curto (até 272K tokens de entrada), verificadas em 21 de outubro de 2026. Prompts mais longos, outros níveis de processamento, gravações de cache e processamento regional podem alterar a tarifa aplicável.
Precificação de modelos OpenAI
Entrada / 1M
Entrada em cache / 1M
Saída / 1M
GPT-6 Astra
$10.00
$1.00
$50.00
GPT-6.1 Sol
$2.00
$0.10
$10.00
GPT-6 Luna
$0.10
$0.01
$0.50
Para acesso a modelos via CometAPI, os desenvolvedores podem usar GPT-6.1 Sol e GPT-6 Luna. A tabela acima mostra tarifas da OpenAI; a cobrança da CometAPI segue suas próprias tarifas aplicáveis.
Recurso ou ferramenta
Configuração / base de cobrança
Tarifa
Container hospedado — Small
1 GB de memória; período de 20 minutos
$0.03 por período
Container hospedado — Medium
4 GB de memória; período de 20 minutos
$0.12 por período
Container hospedado — Large
16 GB de memória; período de 20 minutos
$0.48 por período
Busca na web
Por 1.000 chamadas; tokens de conteúdo cobrados separadamente
$10 por 1.000 chamadas, mais tokens de conteúdo
Armazenamento de busca em arquivos
Por GB por dia, após a franquia grátis
$0.10 por GB/dia
Exemplo: estimando o custo de uma tarefa
Componente
Cálculo ilustrativo
Custo
Tokens de entrada
50.000 × $10 / 1M
$0.50
Tokens de saída
10.000 × $50 / 1M
$0.50
Buscas na web
2 × $0.01
$0.02
Container Small
Um período de 20 minutos
$0.03
Total
Excluindo encargos incidentais
$1.05
Esse total ilustrativo de $1.05 presume os volumes de tokens mostrados, duas buscas, um período de 20 minutos em container small e nenhum token de conteúdo de busca adicional faturável ou gravações de cache. O custo real também depende de novas tentativas, uso de subagentes, comportamento de cache e das regras de cobrança da sandbox aplicáveis à sessão. Acompanhe o custo por tarefa concluída com sucesso em uma carga de trabalho representativa.
Quais são as limitações da OpenAI Agents API?
Limites de dados. A Agents API atualmente oferece residência de dados apenas nos Estados Unidos e não suporta Zero Data Retention (ZDR). Uma sandbox self-hosted não altera sua elegibilidade de ZDR. Antes de enviar material sensível, verifique se os termos de retenção e residência do serviço atendem às suas exigências.
Compatibilidade de API e modelo. Interfaces em beta público podem mudar, e os recursos suportados podem variar por modelo. Teste exatamente o modelo, o endpoint, as configurações de raciocínio e as ferramentas usadas por seu aplicativo. Repita as verificações de integração quando você alterar um modelo ou adotar uma atualização de API.
Controle de execução. Tarefas em múltiplas etapas podem acumular tokens, levar tempos variáveis e encontrar falhas de ferramentas. Defina orçamentos e limites de turnos e runtime, conceda apenas as permissões de que a tarefa precisa e monitore trabalhos de longa duração de forma assíncrona. Planeje como se recuperar de chamadas de ferramentas interrompidas e exija aprovação humana para ações com consequências significativas.
FAQ
Como clientes da OpenAI Agents API devem repetir (retry) mensagens de acompanhamento?
Reutilize a mesma chave de submissão ao repetir a mesma mensagem lógica, seguindo o padrão de entrada e retry de sessão. Mantenha o ID da sessão e a chave de submissão juntos no estado do aplicativo. Uma instrução de usuário separada deve usar sua própria chave; uma resposta HTTP perdida não deve ser automaticamente tratada como uma nova instrução.
Uma sessão da OpenAI Agents API pode mudar de modelo?
O endpoint de configurações de sessão permite atualizar o modelo, o esforço de raciocínio e o nível de serviço. As atualizações afetam turnos posteriores; um turno ativo mantém suas configurações existentes. Confirme se a configuração resultante é suportada pelo modelo selecionado e crie uma nova sessão quando precisar alterar configurações que esse endpoint não aceita.
Como a OpenAI Agents API restringe acesso de rede da sandbox?
Ambientes hospedados pela OpenAI suportam acesso de saída habilitado, desabilitado ou restrito. O modo restrito usa listas de permissão explícitas de hosts, e redirecionamentos ou subdomínios podem precisar de suas próprias entradas. Configure a política de rede da sandbox para os serviços de que a tarefa precisa; acesso de rede e credenciais de aplicativo são controles separados.
Conclusão
Avalie a Agents API com uma tarefa representativa que exija várias chamadas de ferramentas e pelo menos um turno de acompanhamento. Meça taxa de conclusão, comportamento de recuperação, latência e custo por tarefa bem-sucedida. Esses resultados mostrarão se a execução gerenciada atende aos requisitos do seu aplicativo.
