| name | agentic-search |
| description | Grok-primary deep research skill for source-backed web work. Use when the task needs current web research, grounded citations, supplementary Tavily/Firecrawl source discovery, high-fidelity page-to-Markdown fetch, Tavily site mapping, verbatim quote extraction, source reranking, or reusable multi-step research sessions. Use as a supplement when ordinary search results feel incomplete, thinly sourced, or need more URLs, quotes, fetched pages, or session composition; not for simple one-off facts. |
agentic-search
| # | Script | Intent |
|---|
| 1 | scripts/agentic_search.py | Research a topic — AI-reasoned answer with citations |
| 2 | scripts/agentic_fetch.py | Full page → Markdown, no summarization |
| 3 | scripts/agentic_map.py | Enumerate URLs under a site (Tavily-only) |
| 4 | scripts/agentic_extract.py | Verbatim title + 2–4 quotes from a URL |
| 5 | scripts/agentic_rank.py | Rerank session sources by a refined query |
| 6 | scripts/agentic_get_sources.py | Retrieve or list cached sessions |
How to invoke
All scripts use PEP 723 inline deps — always invoke via uv run. Allow up to 3 minutes per call.
uv run scripts/agentic_search.py --query "..." [--extra-sources N] [--auto-fetch-top N] [--platform "..."]
uv run scripts/agentic_fetch.py --url "..." [--engine auto|tavily|firecrawl|grok]
uv run scripts/agentic_map.py --url "..." [--instructions "..."] [--limit N]
uv run scripts/agentic_extract.py --url "..." [--session-id S]
uv run scripts/agentic_rank.py --query "..." --session-id S
uv run scripts/agentic_get_sources.py --list | --session-id S
Session workflow
agentic_search generates a session_id persisted to disk — the connective tissue for composing steps:
agentic_search → session_id
├─→ agentic_rank --session-id S --query Q (rerank in place; mutates session)
├─→ agentic_extract --session-id S --url U (append verbatim quotes)
└─→ agentic_get_sources --session-id S (inspect full session)
Sessions survive between invocations but may be cleared on OS reboot.
Operating discipline
Load the relevant reference before composing a non-trivial query — don't load all four upfront.
references/search-discipline.md — two-pass methodology, citation contract, time-context heuristic. Read for research tasks.references/fetch-fidelity.md — engine trade-offs, fidelity guarantees, when not to fetch. Read before presenting extracted content.references/extract-and-rank.md — extract vs fetch, when to rank, session composition patterns. Read for multi-step workflows.references/provider-quirks.md — env vars, provider schemas, retry policy, debugging. Read when configuring or debugging.
Failure modes
- No
GROK_API_KEY / GROK_API_URL → config error on any Grok-using script.
agentic_fetch --engine auto total failure → retry with --engine grok or fall back to built-in WebFetch.agentic_map without TAVILY_API_KEY → hard exit.agentic_rank --session-id S session expired → re-run agentic_search.sources_count: 0 with non-empty content → Grok used training data; check providers_used (grok-web-search = real citations, grok = heuristic fallback).
