Passo a Passo: Construindo um Agente de Pesquisa no YouTube com Claude Code
Se você já passou uma tarde inteira mergulhado no YouTube, só para esquecer quais vídeos valiam a pena salvar, você não está sozinho. Agora, imagine um assistente incansável que pode encontrar os melhores vídeos, extrair resumos, coletar citações importantes, inserir de informações e retornar as fontes sob demanda — rapidamente. É exatamente isso que um agente de pesquisa no YouTube pode fazer. Neste guia passo a passo, construiremos um agente de pesquisa no YouTube prático com Claude Code, projetado para criadores, analistas, estudantes e aprendizes obcecados que desejam sinal em vez de ruído.
Tomaremos uma rota prática e direta: arquitetura, código, e . Ao longo do caminho, faremos escolhas opinativas que você pode trocar mais tarde. Ao final, você terá um agente funcional que pode pesquisar no YouTube, coletar transcrições, raciocinar entre vários vídeos e produzir de pesquisa claros.
O Que Estamos Construindo (e Por Que Isso Importa)
- Objetivo: Um agente de pesquisa no YouTube que pode:
- Pesquisar no YouTube por consulta
- Classificar os resultados por relevância/engajamento
- Buscar transcrições (legendas automáticas ou de terceiros)
- Dividir e incorporar conteúdo para recuperação
- Usar Claude Code para sintetizar de vários vídeos
- Gerar notas estruturadas: resumo, afirmações, , citações e referências
- Palavra-chave primária: "Construindo um agente de pesquisa no YouTube com Claude Code"
- Formato: Tutorial passo a passo com código executável e
- Saídas: de pesquisa em Markdown + JSON para uso programático
Por que isso importa: O YouTube é a maior base de conhecimento público de palestras, aulas, demonstrações e debates. Mas é barulhento. Construir um agente de pesquisa no YouTube com Claude Code oferece uma vantagem: você pode agregar de dezenas de vídeos em minutos, não em horas.
Arquitetura em Resumo
Manteremos a primeira versão simples e robusta.
- Entradas: uma consulta de pesquisa (por exemplo, "arquiteturas de agentes LLM 2025"), restrições opcionais (intervalo de datas, canal, duração)
- Pesquisa no YouTube: YouTube Data API v3 (ou para SerpAPI)
- Transcrições: YouTube Transcript API; para ASR (por exemplo, Whisper) quando indisponível
- Divisão: Segmentação com reconhecimento de frases (aproximadamente 800–1.200 )
- <i>Embeddings</i>: Use um modelo de local ou hospedado (por exemplo,
text-embedding-3-large, nomic-embed-text ou bge-large)
- Armazenamento de Vetores:
FAISS local para velocidade; pode trocar para Pinecone, Weaviate ou Qdrant
- Raciocínio: Claude Code para orquestração, uso de ferramentas, síntese e execução de código dentro de um controlado
- Saídas: Relatório em Markdown + índice JSON com citações, e pontuações
Fluxo de dados: Consulta → Pesquisa → Buscar metadados → Transcrição → Divisão → Incorporação → Recuperar Top‑K → Síntese com Claude Code → Relatório.
Pré-requisitos e Configuração
- Chaves de API:
YOUTUBE_API_KEY, ANTHROPIC_API_KEY (para Claude Code)
- Opcional:
OPENAI_API_KEY ou locais
google-api-python-client, youtube-transcript-api
faiss-cpu, numpy, pandas, tiktoken (ou sentencepiece)
requests, pydantic, tenacity
pip install google-api-python-client youtube-transcript-api faiss-cpu numpy pandas requests pydantic tenacity anthropic tiktoken
Variáveis de ambiente:
export YOUTUBE_API_KEY=YOUR_YT_KEY
export ANTHROPIC_API_KEY=YOUR_ANTHROPIC_KEY
Passo 1: Pesquisa no YouTube com Filtros
Pesquisaremos no YouTube e retornaremos metadados estruturados: título, canal, data de publicação, duração, visualizações (se disponíveis) e videoId.
# arquivo: yt_search.py
from googleapiclient.discovery import build
import os
YOUTUBE_API_KEY = os.environ — channel, date\n\n"
"---\n"
"JSON schema: {\"claims\":[{\"claim\":str,\"support\":[{\"video_id\":str,\"start\":float,\"end\":float}]}]}\n"
)
def call_claude(goal: str, passages: list[dict]):
passages_str = "\n\n".join(
f"[rank {p['rank']} | score {p['score']:.3f}] (vID={p.get('video_id','?')}, {p.get('start',0):.1f}-{p.get('end',0):.1f})\n{p['text']}"
for p in passages
)
msg = client.messages.create(
model="claude-3-5-sonnet-20240620",
max_tokens=1800,
temperature=0.2,
system=SYSTEM_PROMPT,
messages=[
{"role": "user", "content": USER_TEMPLATE.format(goal=goal, passages=passages_str)}
])
return msg.content[0].text
Dicas de ao construir um agente de pesquisa no YouTube com Claude Code:
- Peça saídas estruturadas em formatos legíveis por humanos e por máquinas
- Incentive divulgações de incertezas e contradições
Passo 6: Juntando Tudo
Vamos conectar consulta → pesquisa → transcrições → divisões → → recuperar → sintetizar.
# arquivo: run_agent.py
from yt_search import search_youtube
from transcripts import fetch_transcript
from chunking import transcript_to_docs
from embeddings import VectorStore
from orchestrator import call_claude
from datetime import datetime
def build_corpus(query: str, max_videos=8):
results = search_youtube(query, max_results=max_videos)
corpus_docs = []
for r in results:
tx = fetch_transcript(r["video_id"]) or []
if not tx:
continue
docs = transcript_to_docs(tx)
for d in docs:
d.update({
"video_id": r["video_id"],
"title": r["title"],
"channel": r["channel"],
"url": r["url"],
})
corpus_docs.extend(docs)
return corpus_docs
def research(query: str, k=12):
corpus = build_corpus(query)
if not corpus:
return "No transcripts available."
vs = VectorStore
vs.add(corpus)
passages = vs.search(query, k=k)
md = call_claude(query, passages)
timestamp = datetime.utcnow.isoformat
return f"<!-- generated {timestamp} UTC -->\n\n" + md
if __name__ == "__main__":
print(research("LLM agents for YouTube research"))
Esta versão básica de um agente de pesquisa no YouTube com Claude Code irá pesquisar, recuperar e sintetizar de vários vídeos com citações. Atualize os e adicione para deixá-lo pronto para produção.
Sete Atualizações Para Torná-lo Ótimo
- Melhores e pesquisa híbrida
- Troque por de alta qualidade e adicione pesquisa de palavras-chave BM25. A abordagem híbrida oferece mais em termos de nicho e melhor precisão em tópicos abstratos.
- Expanda as ferramentas para metadados mais ricos
- Extraia comentários, taxa de / e autoridade do canal. Adicione um () para os 100 principais candidatos.
- Planejamento de pesquisa em várias etapas
- Use Claude Code para propor um plano de pesquisa: subperguntas, hipóteses e verificações de cobertura. Execute iterativamente até que os limites de cobertura sejam atendidos.
- Rastreamento de evidências e contra‑evidências
- Para cada afirmação, registre trechos de apoio e contraditórios. Apresente ambos nos relatórios; adicione pontuações de confiança.
- Estratégias para vídeos longos
- Use a detecção de cena por meio de legendas ou de palavras do Whisper. Resuma por seção antes da síntese global para evitar a diluição do contexto.
- Armazene transcrições, e relatórios por consulta. Reutilize quando os usuários ajustarem os filtros. Adicione a desduplicação por ID de vídeo.
- Formatos de exportação e entrega
- Exporte Markdown, PDF e JSON. Envie por e-mail ou Slack. Renderize os como clicáveis
?t=mmss.
Que Você Pode Reutilizar
Use esses modelos ao construir um agente de pesquisa no YouTube com Claude Code.
Sistema: Você é um agente de pesquisa meticuloso. Sintetize várias transcrições do YouTube. Cite embutido com [vID @ mm:ss] e inclua uma seção de Fontes com URLs. Retorne um em Markdown e uma carga JSON de afirmações com suporte com .
Usuário: Objetivo da pesquisa: {topic}
Restrições: concentre-se em {audience or scope}; prefira fontes dentro de {date range}; inclua discordâncias.
Passagens candidatas (classificadas):
{retrieved_passages}
Saída: Resumo → Principais (marcadores) → Citações Notáveis (com ) → Contradições e Lacunas → Fontes. Em seguida, JSON {"claims": ...}
e Ética
- Respeite os direitos do criador: Vincule aos vídeos originais e evite publicar grandes transcrições textuais.
- Seja transparente: Mostre de onde vêm as afirmações usando e IDs de vídeo.
- Evite a <i>over‑summarization</i>: Preserve as nuances; sinalize quando as legendas são geradas automaticamente e provavelmente ruidosas.
- Manuseie tópicos delicados com cuidado: Destaque a incerteza e busque fontes diversas.
Solução de Problemas: Problemas Comuns e Correções
- "Nenhuma transcrição encontrada"
- Use para Whisper; tente idiomas diferentes; verifique se o vídeo está bloqueado por região.
- Má qualidade de recuperação
- Atualize os ; adicione BM25; aumente a sobreposição de trechos; ajuste o parâmetro .
- Force um esquema de citação estrito; penalize afirmações não suportadas; exija exatos presentes nos trechos recuperados.
- Armazene em agressivamente; reduza
max_results; solicite em lote; adicione com tenacity.
- Resuma por seção; restrinja o número máximo de ; use de planejamento com um esboço explícito.
Medindo a Qualidade
- Precisão@K de trechos recuperados vs. um conjunto rotulado
- Taxa de fidelidade: proporção de afirmações com suporte verificável com
- Cobertura: número de vídeos relevantes exclusivos citados
- Latência: tempo desde a consulta até o relatório
Exemplo: Pesquisando "Bancos de Dados Vetoriais Explicados"
- Consulta: "bancos de dados vetoriais explicados para desenvolvedores 2025"
- Filtros: vídeos após 2023, duração de 6–30 minutos
- Resultado: O agente cita 6 vídeos, destaca as vantagens e desvantagens de HNSW vs. IVF‑PQ, discute custo/ e para . A seção de contradições compara as alegações do fornecedor com os resultados de código aberto.
A Propósito: Automatizando Isso Dentro Do Seu Fluxo De Trabalho
Se você trabalha com documentos e código, vale a pena automatizar a última etapa. Uma pequena CLI pode executar consultas noturnas e soltar em Markdown em sua base de conhecimento. Você também pode conectá-lo a modelos de problemas para pesquisa de .
Vale a pena notar: se o seu fluxo de trabalho já existe em uma barra lateral do navegador ou assistente de IA, ferramentas como Sider.AI podem otimizar o de pesquisa — selecione um tópico, execute uma pesquisa, capture transcrições e crie um resumo com tecnologia Claude diretamente onde você trabalha. Isso pode economizar a troca de contexto e tornar a construção de um agente de pesquisa no YouTube com Claude Code ainda mais prática para as equipes. Principais Conclusões
- Construir um agente de pesquisa no YouTube com Claude Code é uma maneira de alto impacto de transformar vídeos em acionáveis.
- A mínima: YouTube API + transcrições + divisão + + FAISS + síntese com Claude.
- Caminhos de atualização: pesquisa híbrida, , de planejamento e rastreamento estrito de citações.
- Comece simples, meça a fidelidade e itere em direção à confiabilidade.
Próximos Passos
- Implemente um modelo de real e recuperação híbrida
- Adicione uma etapa de e métricas de qualidade
- Crie um trabalho agendado para atualizar os tópicos semanalmente
- Empacote como uma CLI e uma IU da web leve
FAQ
Q1:Como começo a construir um agente de pesquisa no YouTube com Claude Code?
Comece com a pesquisa no YouTube, busque transcrições, divida o conteúdo, incorpore em um armazenamento de vetores e use Claude Code para sintetizar os resultados. O guia acima fornece código passo a passo para montar um funcional.
Q2:Quais bibliotecas são melhores para um agente de pesquisa no YouTube?
Use a YouTube Data API para pesquisa, youtube-transcript-api para legendas, FAISS para pesquisa vetorial e o Anthropic SDK para chamar Claude Code. Você pode trocar os com OpenAI, Nomic ou BGE.
Q3:Como garantir citações e precisos?
Mantenha os de início/fim durante a divisão e exija que Claude Code cite [video_id @ mm:ss]. Valide se os citados existem nos trechos recuperados antes de publicar.
Q4:Posso usar este agente para vídeos privados ou não listados?
Sim, se você tiver acesso e puder buscar transcrições ou executar ASR local (por exemplo, Whisper). Sempre respeite as permissões e evite distribuir conteúdo protegido por direitos autorais.
Q5:Como posso dimensionar este agente de pesquisa no YouTube para equipes?
Adicione , um armazenamento de vetores compartilhado, filas de trabalho e execuções agendadas. Integre com Slack ou uma e considere um assistente baseado em navegador como o Sider.AI para otimizar os fluxos de trabalho dos pesquisadores.