Na era da sobrecarga de informações, a capacidade de conduzir pesquisas rápidas, precisas e abrangentes é um superpoder. Desenvolvedores, analistas e estrategistas gastam incontáveis horas peneirando documentos, verificando fontes e sintetizando descobertas. E se você pudesse automatizar todo esse fluxo de trabalho? A API Deep Research da OpenAI é um passo significativo nessa direção, oferecendo uma ferramenta poderosa para transformar perguntas de alto nível em relatórios estruturados e ricos em citações.
A API Deep Research não é apenas mais um grande modelo de linguagem. É um sistema de agente projetado para lidar com tarefas de pesquisa complexas. Ele pode decompor autonomamente uma consulta, realizar pesquisas na web, executar código para analisar dados e sintetizar os resultados em um relatório coerente e verificável. É construído para profundidade, nuance e confiança, fornecendo não apenas respostas, mas também as evidências por trás delas.
Este guia fornecerá um passo a passo focado no desenvolvedor da API Deep Research. Abordaremos tudo, desde a sua primeira chamada de API até técnicas avançadas de prompt. Nos concentraremos principalmente em dois modelos disponíveis através da API:
o3-deep-research-2025-06-26: O modelo principal, otimizado para a mais alta qualidade de síntese e análise aprofundada.o4-mini-deep-research-2025-06-26: Um modelo mais leve e rápido, perfeito para aplicações sensíveis à latência.
Ao final deste artigo, você terá uma compreensão sólida de como integrar este poderoso agente de pesquisa em suas próprias aplicações.
Quer uma plataforma integrada e All-in-One para sua Equipe de Desenvolvedores trabalhar em conjunto com máxima produtividade?
Apidog entrega todas as suas demandas e substitui o Postman por um preço muito mais acessível!
Preços e Limites de Taxa da API Deep Research da OpenAI
Escolher o modelo certo e entender os custos são cruciais para aplicações em produção.
Escolhendo Seu Modelo
o3-deep-research: Este é o seu modelo para tarefas complexas que exigem o mais alto nível de raciocínio e síntese. É mais lento, mas oferece qualidade superior.o4-mini-deep-research: Use este modelo quando a velocidade for uma prioridade. É ideal para tarefas de pesquisa mais diretas ou aplicações interativas onde a baixa latência é fundamental.
Entendendo os Custos
A partir do final de 2024, o preço para o poderoso modelo o3-deep-research é baseado em tokens:
- Entrada (Input): $10.00 por 1 milhão de tokens
- Saída (Output): $40.00 por 1 milhão de tokens
O custo mais alto para tokens de saída reflete o trabalho intensivo de síntese e geração que o modelo executa.
Especificações Chave (o3-deep-research)
- Janela de Contexto: Uma enorme janela de 200.000 tokens.
- Máx. Tokens de Saída: Generosos 100.000 tokens, permitindo relatórios de formato muito longo.
- Corte de Conhecimento: 01 de junho de 2024. O conhecimento interno do modelo está atualizado até esta data, mas a ferramenta
web_search_previewlhe dá acesso a informações em tempo real.
Faça Sua Primeira Chamada à API Deep Research da OpenAI
Vamos direto ao ponto. Antes de usar a API, você precisará do SDK Python da OpenAI.
Configuração
Se você ainda não o fez, instale a versão mais recente da biblioteca:
pip install --upgrade openai
Em seguida, você precisará se autenticar. Importe o cliente OpenAI e inicialize-o com sua chave de API.
from openai import OpenAI
import os
# É uma boa prática usar uma variável de ambiente para sua chave de API
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
Fazendo a Requisição
Uma tarefa de Deep Research pode levar vários minutos para ser concluída, especialmente para consultas complexas. Para evitar timeouts, é altamente recomendável executar as requisições em segundo plano. A API facilita isso.
Vamos imaginar que estamos construindo uma ferramenta para uma empresa de serviços financeiros de saúde. A tarefa é produzir um relatório sobre o impacto econômico de novos medicamentos para diabetes e obesidade. Veja como você estruturaria essa requisição:
system_message = """ Você é um pesquisador profissional preparando um relatório estruturado e baseado em dados em nome de uma equipe global de economia da saúde. Sua tarefa é analisar a questão de saúde que o usuário apresenta. Faça: - Foco em insights ricos em dados: inclua figuras, tendências, estatísticas e resultados mensuráveis específicos. - Quando apropriado, resuma os dados de forma que possam ser transformados em gráficos ou tabelas. - Priorize fontes confiáveis e atualizadas: pesquisa revisada por pares, organizações de saúde (ex: OMS, CDC), etc. - Inclua citações inline e retorne todos os metadados da fonte. Seja analítico, evite generalidades e garanta que cada seção apoie um raciocínio baseado em dados. """ user_query = "Pesquise o impacto econômico da semaglutida nos sistemas globais de saúde." response = client.responses.create( model="o3-deep-research", # Ou "o3-deep-research-2025-06-26" input=[ { "role": "developer", "content": [ { "type": "input_text", "text": system_message, } ] }, { "role": "user", "content": [ { "type": "input_text", "text": user_query, } ] } ], reasoning={ "summary": "auto" }, tools=[ { "type": "web_search_preview" }, { "type": "code_interpreter" } ] )
Vamos detalhar esta chamada:
model: Especificamoso3-deep-researchpara um relatório de alta qualidade.input: É aqui que fornecemos nossos prompts. Osystem_messagedefine a persona e o objetivo geral para o agente. Ouser_queryé a tarefa de pesquisa específica.reasoning: Definirsummarycomo"auto"permite que o modelo gere o melhor resumo possível para o relatório. Para relatórios mais detalhados, você pode definir isso como"detailed".tools: Este array informa ao agente quais ferramentas ele tem à sua disposição.web_search_previewé necessário para que ele navegue na web.code_interpreteré opcional, mas permite que o agente execute código Python para análise e visualização de dados.
O verdadeiro poder da API Deep Research reside no objeto de resposta estruturado e detalhado que ela retorna. É mais do que apenas um bloco de texto; é um registro transparente do processo de pesquisa.
O Relatório Final
A saída principal é, claro, o relatório final. Você pode acessá-lo a partir do último item no array output:
# Acesse o relatório final do objeto de resposta
print(response.output[-1].content[0].text)
Isso lhe dará o texto completo e sintetizado gerado pelo modelo.
Citações e Fontes
Uma das características mais críticas para qualquer pesquisa séria é a citação. A API Deep Research incorpora metadados de citação diretamente na resposta. Cada citação é vinculada a uma parte específica do texto, permitindo fácil verificação.
Veja como você pode extrair e exibir as citações:
annotations = response.output[-1].content[0].annotations
for i, citation in enumerate(annotations):
print(f"Citação {i+1}:")
print(f" Título: {citation.title}")
print(f" URL: {citation.url}")
print(f" Localização: caracteres {citation.start_index}–{citation.end_index}")
Esta estrutura é inestimável para construir aplicações que exigem altos graus de confiança e transparência. Você pode usá-la para criar notas de rodapé clicáveis, construir uma bibliografia ou rastrear programaticamente as afirmações até sua fonte original.
Espiando por Trás da Cortina: Passos Intermediários
A API também expõe todo o processo de pensamento do agente. O response.output contém um registro de todos os passos intermediários tomados para chegar à resposta final. Isso é incrivelmente útil para depuração, análise ou simplesmente para entender como o agente funciona.
- Passos de Raciocínio: Estes representam os planos internos e os resumos do modelo enquanto ele decompõe o problema.
reasoning = next(item for item in response.output if item.type == "reasoning")
for s in reasoning.summary:
print(s.text)
- Chamadas de Pesquisa na Web: Você pode ver as consultas de pesquisa exatas que o agente usou.
search = next(item for item in response.output if item.type == "web_search_call")
print("Consulta:", search.action["query"])
- Execução de Código: Se a ferramenta
code_interpreterfoi usada, você pode inspecionar o código que ela executou e a saída resultante.
code_step = next((item for item in response.output if item.type == "code_interpreter_call"), None)
if code_step:
print("Entrada do Código:", code_step.input)
print("Saída do Código:", code_step.output)
Usando a Pesquisa Profunda da OpenAI com Servidores MCP
Pesquisa Avançada com Servidores MCP
Enquanto a pesquisa na web dá ao agente Deep Research acesso a um vasto repositório de informações públicas, seu verdadeiro poder é desbloqueado quando você o conecta aos seus próprios dados privados.
É aqui que entra o Protocolo de Contexto do Modelo (MCP). O MCP permite que você construa ferramentas personalizadas que estendem as capacidades do agente, permitindo que ele consulte suas bases de conhecimento internas, bancos de dados ou outros serviços proprietários.
Um dos servidores MCP populares atualmente é o Apidog MCP Server, que permite que você se conecte à sua Documentação de API dentro do Cursor e outras ferramentas de Codificação de IA, e reduz grandemente a alucinação da IA ao puxar de Especificações de API factuais.
Conclusão: O Futuro da Pesquisa Automatizada
A API Deep Research da OpenAI é mais do que apenas uma melhoria incremental. Ela representa uma mudança fundamental em como podemos alavancar a IA para o trabalho de conhecimento. Ao fornecer um agente que pode raciocinar, planejar, executar ferramentas e produzir resultados verificáveis, a OpenAI criou um bloco de construção para uma nova geração de aplicações de pesquisa.
Seja você construindo painéis de inteligência competitiva, automatizando revisões de literatura ou criando relatórios sofisticados de análise de mercado, a API Deep Research fornece o poder, a transparência e a confiança necessários para casos de uso sérios e do mundo real. Como o "cookbook" sugere, o próximo passo provavelmente são "Agentes de Pesquisa Profunda" totalmente desenvolvidos, sugerindo um futuro ainda mais autônomo e capaz. Por enquanto, a API oferece aos desenvolvedores uma nova ferramenta incrível para explorar. Comece a construir com ela hoje mesmo.