Habilidade de Pesquisa Profunda
Propósito
Esta habilidade permite pesquisas abrangentes e habilitadas para internet sobre qualquer tópico usando a API de Pesquisa Profunda da OpenAI (modelo o4-mini-deep-research). Ela aprimora de forma inteligente os prompts de pesquisa do usuário por meio de perguntas de esclarecimento interativas, garante que os parâmetros de pesquisa sejam salvos para reprodutibilidade e executa pesquisas profundas com recursos completos de busca na web.
Quando Usar Esta Habilidade
Ative esta habilidade quando:
- O usuário solicitar pesquisa sobre um tópico específico
- O usuário pedir análise, investigação ou coleta abrangente de informações
- O usuário quiser explorar um assunto com busca na web e raciocínio
- O usuário fornecer uma consulta de pesquisa breve que possa ser refinada
- O usuário quiser entender o estado atual, tendências ou comparações em uma área
Exemplos de solicitações de usuário:
- "Pesquise as soluções RAG de código aberto mais eficazes com alto desempenho em benchmarks"
- "Quais são os últimos desenvolvimentos de IA em 2025?"
- "Preciso de uma análise abrangente de sistemas de banco de dados distribuídos"
- "Encontre melhores práticas para implementar busca vetorial"
- "Investigue como a IA está impactando a indústria de engenharia de software"
Visão Geral do Fluxo de Trabalho
Entrada do Usuário
↓
Avaliação: Prompt muito breve?
↓
SIM → Fazer Perguntas de Esclarecimento → Coletar Respostas
↓ ↓
└───────→ Construir Prompt Aprimorado ←──┘
↓
Salvar em Arquivo com Timestamp
↓
Executar deep_research.py
↓
Relatório de Saída + Fontes
↓
Apresentar ao Usuário
Como o Claude Deve Usar Esta Habilidade
Importante para Eficiência de Tokens: A pesquisa profunda leva de 10 a 20 minutos para ser concluída. A habilidade foi projetada para ser executada de forma síncrona (bloqueante) sem verificações de status intermediárias. Essa abordagem minimiza o uso de tokens durante a espera. Claude deve:
- Iniciar a pesquisa
- Aguardar a conclusão (o subprocesso bloqueia automaticamente)
- Apresentar os resultados finais assim que concluído
Não é necessário fazer polling periódico ou atualizações de status durante a execução.
Etapa 1: Aceitar a Solicitação de Pesquisa
Receba o prompt de pesquisa do usuário. Isso pode variar de breve ("Últimas tendências de IA") a altamente detalhado ("Impacto dos modelos de linguagem na produtividade do desenvolvedor com foco em 2024-2025").
Etapa 2: Executar o Script de Orquestração
Execute o script principal de orquestração da habilidade com o prompt de pesquisa do usuário:
python3 scripts/run_deep_research.py "Seu prompt de pesquisa aqui"
O script está localizado em scripts/run_deep_research.py dentro da instalação da habilidade.
Etapa 3: Fluxo de Execução do Script
O script automaticamente:
-
Avalia a completude do prompt: Verifica se o prompt é muito breve ou genérico (< 15 palavras ou começa com "o que é", "como", etc.)
-
Faz perguntas de esclarecimento (se necessário):
- Apresenta 2 a 3 perguntas focadas relevantes para o tipo de pesquisa
- Detecta se a pesquisa é técnica ou geral com base em palavras-chave
- Permite que os usuários selecionem opções predefinidas (1-4) ou forneçam texto personalizado
- Perguntas cobrem: Escopo/Período de tempo, Nível de profundidade, Áreas de foco
-
Aprimora o prompt: Combina o prompt original com as respostas do usuário em parâmetros de pesquisa estruturados
-
Salva o arquivo de prompt: Escreve o prompt aprimorado em
research_prompt_YYYYMMDD_HHMMSS.txtpara reprodutibilidade -
Executa a pesquisa profunda: Executa o script principal
deep_research.pycom:- Modelo: o4-mini-deep-research (configurável via
--model) - Timeout: 1800 segundos / 30 minutos (configurável via
--timeout) - Ferramentas: Busca na web habilitada por padrão
- Modelo: o4-mini-deep-research (configurável via
Etapa 4: Apresentar Resultados ao Usuário
O script automaticamente:
- Salva arquivo markdown: Relatório de pesquisa com fontes salvo em
research_report_YYYYMMDD_HHMMSS.md - Imprime no terminal: Relatório de pesquisa completo com formatação markdown
- Lista fontes da web: URLs numeradas referenciadas na pesquisa
- Confirma a conclusão: Caminho onde os arquivos de pesquisa foram salvos
Nota de Eficiência de Tokens: A pesquisa profunda leva de 10 a 20 minutos. O script é executado de forma síncrona (bloqueante) sem polling intermediário, minimizando o uso de tokens durante a espera.
Recursos Inclusos
Scripts
scripts/run_deep_research.py (Ponto de Entrada Principal)
O script de orquestração que lida com:
- Avaliação da qualidade do prompt
- Perguntas interativas de aprimoramento (com detecção inteligente para pesquisa técnica vs. geral)
- Salvamento e timestamp do prompt
- Execução da pesquisa profunda principal
Principais Recursos:
- Aprimoramento inteligente: Só faz perguntas se o prompt for breve/genérico
- Perguntas baseadas em modelo: Conjuntos de perguntas diferentes para pesquisa técnica vs. geral
- Entrada flexível: Opções numeradas + entrada de texto personalizado
- Tratamento de erros: Mensagens úteis se deep_research.py não for encontrado
Opções disponíveis:
python3 run_deep_research.py <prompt> [OPÇÕES]
--no-enhance Pular perguntas de aprimoramento
--model <model> Modelo a ser usado (padrão: o4-mini-deep-research)
--timeout <segundos> Timeout em segundos (padrão: 1800)
--output-dir <caminho> Onde salvar o arquivo de prompt
assets/deep_research.py
Script principal que faz interface com a API de Pesquisa Profunda da OpenAI. Lida com:
- Autenticação da API via OPENAI_API_KEY
- Criação e execução de solicitações
- Salvamento automático em markdown: Salva arquivos de relatório com timestamp por padrão
- Formatação de saída (relatório + fontes com metadados)
- Tratamento de erros e tentativas
Novas opções de linha de comando:
--output-file <caminho> Caminho personalizado para arquivo de saída
--no-save Desativar salvamento automático em markdown
Referências
references/workflow.md
Documentação detalhada do fluxo de trabalho cobrindo:
- Fluxo de trabalho completo da habilidade com exemplos
- Estratégias de aprimoramento de prompt
- Explicação dos parâmetros de pesquisa
- Guia de integração para Claude
- Referência da interface de linha de comando
- Tratamento de erros e solução de problemas
- Dicas para pesquisa eficaz
Comportamentos Chave
Aprimoramento Inteligente de Prompt
A habilidade determina de forma inteligente se o aprimoramento é necessário:
- Ativa aprimoramento para prompts com < 15 palavras ou início genérico
- Pula aprimoramento para prompts detalhados e específicos
- Permite que usuários desativem com a flag
--no-enhance - Consciente de modelo: Usa perguntas diferentes para pesquisa técnica vs. geral
Parâmetros de Pesquisa
Prompts aprimorados incluem:
- Consulta original do usuário com contexto completo
- Preferências de escopo e período de tempo
- Nível de profundidade desejado (resumo, técnico, implementação, comparativo)
- Áreas de foco específicas (desempenho, custo, segurança, etc.)
Esses parâmetros ajudam o modelo de pesquisa profunda a entregar resultados mais direcionados e relevantes.
Reprodutibilidade
Cada execução de pesquisa:
- Salva o prompt exato usado em um arquivo com timestamp
- Permite rastrear decisões de pesquisa
- Permite pesquisas de acompanhamento usando os mesmos prompts ou modificados
- Mantém trilha de auditoria dos parâmetros de pesquisa
Exemplos
Prompt Breve com Aprimoramento
Usuário: "Pesquise as soluções RAG de código aberto mais eficazes"
Comportamento do script:
- Detecta prompt breve (12 palavras) + palavras-chave técnicas ("código aberto", "RAG")
- Faz perguntas de pesquisa técnica:
- Escopo de tecnologia: Apenas código aberto? (Usuário: Sim)
- Métricas chave: Desempenho/benchmarks? (Usuário: Velocidade e Precisão)
- Casos de uso: Implantação em produção? (Usuário: Vários aspectos)
- Aprimora para um prompt detalhado com parâmetros
- Salva e executa pesquisa profunda
- Retorna relatório abrangente com benchmarks comparativos e URLs de fontes
Prompt Detalhado Sem Aprimoramento
Usuário: "Analise o impacto dos grandes modelos de linguagem na produtividade de desenvolvedores de software em 2024-2025, focando em ferramentas de geração de código, programação em par e métricas de produtividade."
Comportamento do script:
- Detecta prompt detalhado (24 palavras) com escopo/foco específico
- Pula perguntas de aprimoramento
- Salva e executa pesquisa profunda imediatamente
- Retorna análise focada alinhada com as especificações do usuário
Requisitos
- Python 3.7+
- Chave de API OpenAI (definida via variável de ambiente
OPENAI_API_KEYou arquivo.env) - Conexão com a internet (para busca na web)
- 30+ minutos para conclusão da pesquisa (timeout configurável)
Fluxo de Trabalho Eficiente em Tokens
Otimização de Tarefas de Longa Execução
Consultas de pesquisa profunda normalmente levam de 10 a 20 minutos para serem concluídas. Esta habilidade é otimizada para minimizar o uso de tokens durante longas esperas:
Como funciona:
- Execução síncrona: O script é executado como um subprocesso bloqueante (sem polling em segundo plano)
- Sem verificações intermediárias: Claude espera silenciosamente pela conclusão sem atualizações de status
- Saída única: Os resultados são apresentados uma vez no final
- Salvamento automático: Arquivos Markdown são salvos automaticamente, sem necessidade de intervenção manual
Economia de tokens:
- Abordagem tradicional: Verificar status a cada 30 segundos = ~40 verificações × 500 tokens = ~20.000 tokens desperdiçados
- Esta abordagem: Espera única = ~1.000 tokens no total
Gerenciamento Automático de Arquivos
A habilidade gera e salva arquivos automaticamente:
Arquivos gerados:
research_prompt_YYYYMMDD_HHMMSS.txt- Prompt de pesquisa aprimorado com parâmetrosresearch_report_YYYYMMDD_HHMMSS.md- Relatório markdown completo com:- Seções de pesquisa (histórica, cognitiva, cultural, etc.)
- Citações de fontes numeradas
- Rodapé de metadados (data, modelo)
Opções de personalização:
# Local de saída personalizado
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md
# Desativar salvamento automático (apenas saída no terminal)
python3 deep_research.py --prompt-file prompt.txt --no-save
Solução de Problemas
OPENAI_API_KEY Ausente
Erro: "Missing OPENAI_API_KEY"
Solução:
- Defina a variável de ambiente:
export OPENAI_API_KEY="sua-chave" - Ou crie um arquivo
.envno diretório de trabalho comOPENAI_API_KEY=sua-chave
deep_research.py Não Encontrado
Erro: "Could not find deep_research.py"
Solução:
- Certifique-se de que a habilidade está instalada corretamente com os assets
- O script pesquisa em: pasta de assets da habilidade → diretório atual → diretório pai
Timeout da Pesquisa
Erro: Solicitação expira após 30 minutos
Solução:
- Aumente o timeout:
--timeout 5400(90 minutos) - Simplifique o prompt para reduzir o escopo da pesquisa
- Execute durante horários de menor movimento para respostas potencialmente mais rápidas da API