Research Agent Designer

Research Agent Designer

Quand utiliser ce skill

Conçois un agent de recherche autonome quand le besoin est : chercher sur le web ou un corpus documentaire, croiser des sources, extraire des données structurées et produire un rapport synthétique avec citations. Cas d'usage : veille concurrentielle, due diligence, fact-checking, recherche académique, production de contenu documenté.

---

Critères de choix d'architecture

| Besoin | Architecture recommandée | |---|---| | 1 sujet, réponse rapide | Mono-agent + outils multiples | | Sujets complexes / multi-domaines | Pipeline multi-agents (searcher → extractor → synthesizer) | | Corpus interne (PDF, SharePoint) | RAG + search hybride (vector + keyword) | | Fréquence élevée / coût maîtrisé | Cache Redis des résultats + deduplication URL | | Résultat fiable avec citations | Toujours : citation tracker JSON obligatoire |

---

Workflow en 10 étapes

1. Définir le scope et le budget

Avant tout code, fixe trois contraintes explicites :

• Budget sources : max 20-50 URLs par run
• Budget temps : timeout global 5-15 min (configurable)
• Budget tokens : max 10k tokens par source injectée dans le LLM

RESEARCH_CONFIG = {
    "max_sources": 30,
    "timeout_s": 600,
    "max_tokens_per_source": 8000,
    "max_iterations": 3,
    "alert_budget_pct": 0.80,
}

2. Architecturer les quatre couches

(a) Recherche — search tools (Tavily, Serper, SerpAPI) (b) Extraction — HTML cleaner (trafilatura), PDF (pdfplumber), JS (Playwright) (c) Analyse / synthèse — LLM fort (Claude Opus / GPT-4o) (d) Output — rapport structuré avec scores de confiance et citations

Choisis dès le départ LangGraph ou un simple loop Python ; LangGraph est préférable dès que le flow est conditionnel ou multi-agents.

3. Configurer les tools de recherche

# Tavily (recommandé — retourne directement le contenu extrait)
from tavily import TavilyClient
client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
results = client.search(
    query=query,
    search_depth="advanced",   # "basic" pour économiser des tokens
    max_results=10,
    include_raw_content=False, # True si tu veux le HTML brut
)

# Serper (alternative, moindre coût)
import httpx
resp = httpx.post(
    "https://google.serper.dev/search",
    json={"q": query, "num": 10},
    headers={"X-API-KEY": os.environ["SERPER_API_KEY"]},
)

Wrappe toujours chaque appel outil dans un bloc try/except avec retry exponentiel (max 3 tentatives).

4. Extraction de contenu propre

import trafilatura

def fetch_and_clean(url: str, max_tokens: int = 8000) -> str | None:
    downloaded = trafilatura.fetch_url(url, timeout=15)
    if not downloaded:
        return None
    text = trafilatura.extract(
        downloaded,
        include_tables=True,
        include_links=False,
        no_fallback=False,
    )
    # Tronquer pour respecter le budget tokens (approx 4 chars/token)
    return text[: max_tokens * 4] if text else None

Pour les pages JavaScript lourdes (SPA, dashboards), utilise Playwright :

from playwright.async_api import async_playwright

async def fetch_js_page(url: str) -> str:
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        page = await browser.new_page()
        await page.goto(url, wait_until="networkidle", timeout=20000)
        content = await page.content()
        await browser.close()
    return content

Pour les PDF : pdfplumber (tableaux) ou pypdf (texte brut).

5. Stratégie de requêtes itératives (iterative deepening)

L'agent génère 3-5 requêtes initiales → analyse les résultats → identifie les lacunes → génère des requêtes de suivi.

QUERY_GENERATION_PROMPT = """
Sujet de recherche : {topic}
Génère 5 requêtes de recherche complémentaires couvrant différents angles.
Format : JSON list de strings.
Contraintes : pas de doublons, chaque requête  float:
    score = 0.5  # base

    # Crédibilité domaine
    trusted_domains = ["reuters.com", "bbc.com", "nature.com", "arxiv.org"]
    low_quality = ["blogspot.com", "wordpress.com"]
    if any(d in url for d in trusted_domains): score += 0.2
    if any(d in url for d in low_quality): score -= 0.2

    # Fraîcheur (bonus si  2000: score += 0.1

    return min(max(score, 0.0), 1.0)

Filtre toute source avec score str: refid = f"[{len(citationstore) + 1}]" citationstore.append({ "refid": refid, "claim": claim, "sourceurl": url, "sourcetitle": title, "sourcedate": date, "verbatimquote": quote[:300], }) return refid # insérer inline dans le texte généré

Le rapport final doit inclure une section `## Sources` avec la liste complète.

### 8. Prompt de synthèse structuré

```python
SYNTHESIS_PROMPT = """
Tu es un analyste expert. Synthétise les documents fournis sur le sujet : {topic}

Documents (avec IDs source) :
{documents}

Produis un rapport structuré :
1. Résumé exécutif (200-400 mots)
2. Findings principaux (par thème, avec citations inline [N])
3. Points de divergence entre sources
4. Niveau de confiance global : Haute / Moyenne / Basse (justifié)
5. Gaps identifiés et questions ouvertes

Règle absolue : chaque affirmation factuelle doit citer au moins une source [N].
Ne jamais inventer ou inférer des faits non présents dans les documents.
"""

9. Formatage de l'output

Propose trois niveaux selon le contexte :

| Mode | Contenu | Longueur cible | |---|---|---| | brief | Résumé exécutif + 3-5 key findings + sources | ~400 mots | | standard | Rapport complet structuré + tableau comparatif | ~800-1200 mots | | exhaustif | Tout le dessus + annexes par source + contradictions détaillées | 2000+ mots |

Ajoute toujours un niveau de confiance par section et la liste des sources avec scores.

10. Validation itérative et arrêt

Après le premier draft, l'agent identifie automatiquement les gaps :

GAP_ANALYSIS_PROMPT = """
Rapport produit : {draft}
Sujet initial : {topic}

Identifie :
1. Les questions du sujet restées sans réponse
2. Les contradictions non résolues entre sources
3. Les sections avec seulement 1 source (triangulation insuffisante)

Format : JSON avec clés "unanswered", "contradictions", "weak_sections".
"""

Si des gaps critiques existent et que le budget le permet → nouvelle itération. Sinon → finaliser et remettre le rapport.

---

Garde-fous et anti-patterns

Anti-patterns critiques

• Hallucination de sources : ne jamais générer une URL qui n'a pas été réellement visitée. Toujours construire le citation_store depuis les fetches réels.
• Source unique : présenter un fait comme établi depuis une seule source = erreur. Exige 2-3 sources concordantes.
• Injection de contenu non filtré : injecter des pages entières dans le LLM sans tronquer → coûts explosifs et hallucinations. Toujours tronquer à max_tokens_per_source.
• Boucle infinie : sans limite d'itérations, un agent peut looper indéfiniment. Toujours imposer max_iterations.
• Confusion corrélation/causalité : le LLM de synthèse peut inférer des liens causaux. Le prompt doit interdire explicitement toute inférence non étayée.

Pièges courants

• Contenu paywallé : Tavily et Serper retournent souvent des snippets plutôt que le contenu complet — vérifie que le contenu est suffisant avant de scorer la source.
• Pages JS-only : trafilatura retourne None sur les SPA. Détecter et basculer sur Playwright.
• Dates manquantes : beaucoup de pages n'exposent pas de date. Ne pas pénaliser excessivement ; utiliser la date de fetch comme fallback.
• Résultats redondants : plusieurs URLs peuvent pointer vers le même contenu (syndication). Déduplique par hash du contenu extrait.

---

Stack recommandée (2026)

| Composante | Outil privilégié | Alternative | |---|---|---| | Search web | Tavily | Serper, SerpAPI, Perplexity API | | Extraction HTML | trafilatura | Firecrawl, readability-lxml | | Pages JS | Playwright | Puppeteer (Node) | | PDF | pdfplumber | pypdf, LlamaParse | | Orchestration | LangGraph | CrewAI, plain Python | | Synthèse LLM | Claude Opus 4 / GPT-4o | Gemini 1.5 Pro | | Cache résultats | Redis + TTL 24h | SQLite local |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: khalilbenaz
• Source: khalilbenaz/claude-skills-collection
• License: MIT
• Homepage: https://khalilbenaz.github.io/claude-skills-collection/

Install and usage instructions live in the source repository linked above.