# deep-research A deep web research agent, built as a Coyote graph agent. It plans an investigation, decomposes it into sub-questions researched in parallel, grounds the work in a local knowledge corpus, vets the credibility of cited sources, runs a reflexion self-critique loop to revise weak findings, delegates the final write-up to a focused sub-agent, checks that the cited sources are reachable, and gates the result behind human approval. Unlike a regular agent (which takes a goal and improvises the steps), this agent runs a fixed graph: every request goes through the same `plan -> parallel research -> vet -> critique -> synthesize -> verify -> approve` pipeline. This agent is also the **canonical reference for the Coyote graph system**: it exercises every node type (`script`, `llm`, `rag`, `map`, `agent`, `input`, `approval`, `end`) and both static fan-out and dynamic `map` fan-out. If you are learning how to build a graph agent, this is the file to read alongside the [Graph-Agents wiki](https://github.com/Dark-Alex-17/coyote/wiki/Graph-Agents). ## Workflow 23 nodes. Solid arrows are static `next` / `routes` edges declared in `graph.yaml`; script nodes can also route dynamically via `_next` (shown as labeled branches out of the diamond). Dotted arrows show `map` fan-out — the `research_each_question` node spawns one `research_one_question` branch per sub-question and joins them before continuing — and `fallback` edges (labeled "fallback"), taken when a node fails outright (see *Fault paths* below). ```mermaid flowchart TD parse_request{"parse_request
script"} parse_request -->|"topic given"| bootstrap_research parse_request -->|"no topic"| ask_topic ask_topic[/"ask_topic
input"/] --> bootstrap_research bootstrap_research{"bootstrap_research
script"} bootstrap_research --> plan bootstrap_research --> knowledge_lookup plan["plan
llm + output_schema"] --> research_each_question plan -. "fallback" .-> plan_fault{"plan_fault
script"} plan_fault --> end_fault knowledge_lookup[("knowledge_lookup
rag")] --> research_each_question research_each_question[\research_each_question
map/] research_each_question -. "spawns × N" .-> research_one_question["research_one_question
llm + web tools"] research_one_question -. "fallback" .-> question_fault{"question_fault
script"} research_each_question --> combine_findings combine_findings{"combine_findings
script"} --> vet_sources vet_sources["vet_sources
llm + classify_source"] --> critique vet_sources -. "fallback" .-> vet_fault{"vet_fault
script"} vet_fault --> critique critique["critique
llm"] --> reflexion_gate critique -. "fallback" .-> critique_fault{"critique_fault
script"} critique_fault --> reflexion_gate reflexion_gate{"reflexion_gate
script"} reflexion_gate -->|"PASS"| synthesize reflexion_gate -->|"REVISE (budget left)"| research_each_question reflexion_gate -->|"REVISE (budget spent)"| synthesize synthesize[["synthesize
agent → report-writer"]] --> verify_sources synthesize -. "fallback" .-> synth_fault{"synth_fault
script"} synth_fault --> end_fault verify_sources{"verify_sources
script"} --> approve approve{{"approve
approval"}} approve -->|"accept"| end_accepted approve -->|"reject"| end_rejected approve -->|"other (free-form feedback)"| incorporate_feedback incorporate_feedback{"incorporate_feedback
script"} --> research_each_question end_accepted(["end_accepted
report"]) end_rejected(["end_rejected"]) end_fault(["end_fault
DEEP_RESEARCH FAILED"]) ``` ### Node-type breakdown | Type | Nodes | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------| | `script` (Python) | `parse_request`, `bootstrap_research`, `combine_findings`, `reflexion_gate`, `verify_sources`, `incorporate_feedback`, plus the fault markers `plan_fault`, `question_fault`, `vet_fault`, `critique_fault`, `synth_fault` | | `llm` (tools: `[]`) | `plan`, `critique` | | `llm` (with tool whitelist) | `research_one_question`, `vet_sources` | | `rag` | `knowledge_lookup` — local corpus retrieval | | `map` | `research_each_question` — dynamic fan-out per sub-question | | `agent` | `synthesize` — spawns the `report-writer` sub-agent | | `input` | `ask_topic` | | `approval` | `approve` | | `end` | `end_accepted`, `end_rejected`, `end_fault` | ## Parallel execution The graph has two parallel super-steps where Coyote's BSP scheduler runs branches concurrently. **1. Context loading (`plan` ‖ `knowledge_lookup`)** — after `bootstrap_research`, the LLM planner (which decomposes the topic into sub-questions) and the RAG retrieval over the local `knowledge/` corpus run side by side. They write disjoint state keys (`plan` writes `research_plan` and `questions`; `knowledge_lookup` writes `local_context` and `local_sources`) so no reducer is needed. **2. Per-question research (`research_each_question` map)** — the plan emits a `questions` array (3-5 entries, enforced by its `output_schema`). The `map` node spawns one parallel branch per question (`max_concurrency: 3`). Each branch is an isolated `research_one_question` LLM invocation with web tools, instructed to investigate exactly its assigned question. Outputs collect into `question_findings` in input order, then `combine_findings` joins them into a single `findings` Markdown document for downstream nodes. `settings.max_concurrency: 4` is the graph-wide cap; the per-`map` override (`max_concurrency: 3` on `research_each_question`) is deliberately lower to leave headroom for the planner's tool calls running alongside RAG. ## Local knowledge corpus `knowledge_lookup` is a `rag` node — it runs hybrid (vector + keyword) retrieval over every file in `knowledge/`. The directory ships with a small `research-style-notes.md` so the RAG node has something to retrieve against on a clean install; drop your own Markdown notes, PDFs, or text files into `knowledge/` to bias the research toward your local context. The knowledge base is built once, at agent-load time, into `~/.config/coyote/agents/deep-research/knowledge_lookup.yaml`. Because the node fully specifies its build config (`embedding_model`, `chunk_size`, `chunk_overlap`), the build is non-interactive. Delete that cached file after adding or changing knowledge to force a rebuild. ## Sub-agent: report-writer The `synthesize` node is an `agent` node that spawns the `report-writer` sub-agent (`assets/agents/report-writer/`). This is the agent-as-tool pattern: the orchestrating graph delegates the writing phase to a focused sub-agent dedicated to coherent prose, while the research phase uses different (typically cheaper) LLM nodes for fast-and-many-question investigation. The `report-writer` sub-agent has no tools — it cannot access the web, cannot search, and cannot invent facts. It reads only the findings it is given and produces a final Markdown report preserving every inline citation. See `assets/agents/report-writer/README.md` for details. ## Tools and tool scoping This agent demonstrates Coyote's three tool sources and how an `llm` node's `tools:` whitelist scopes them per node. The agent's full tool universe, declared in `graph.yaml`: - **Global tools** (`global_tools`): `web_search_coyote`, `fetch_url_via_curl`, `search_arxiv` - Coyote's built-in tool scripts. - **MCP server** (`mcp_servers`): `ddg-search` - a DuckDuckGo web search MCP server. Referenced in a whitelist as `mcp:ddg-search`. - **Custom agent tool** (`tools.sh`): `classify_source` - a deterministic source-credibility classifier shipped with this agent. No node receives all of these. Each `llm` node's `tools:` whitelist narrows the universe to exactly what that step needs: | Node | `tools:` whitelist | Draws from | |-------------------------|-----------------------------------------------------------------------------|--------------------------| | `plan`, `critique` | `[]` | nothing - pure reasoning | | `research_one_question` | `web_search_coyote`, `fetch_url_via_curl`, `search_arxiv`, `mcp:ddg-search` | global tools + MCP | | `vet_sources` | `classify_source` | the custom tool only | `research_one_question` (each parallel branch of the map) can search and fetch but cannot classify sources; `vet_sources` can classify sources but cannot touch the web. That separation is the point of the `tools:` whitelist: a node gets only the tools its job calls for, never the agent's full set. The `classify_source` custom tool (`tools.sh`) takes a URL and returns a credibility tier (government, academic, preprint, organization, unverified) derived from the host and top-level domain. It is deterministic - exactly the kind of logic a tool should own rather than the LLM guessing. Web search may require API-key configuration; see the [Tools](https://github.com/Dark-Alex-17/coyote/wiki/Tools) docs. `fetch_url_via_curl`, `search_arxiv`, and `classify_source` work without a key. ## Setup `research_one_question` (each parallel branch of the `map`) uses the `ddg-search` MCP server via `mcp:ddg-search`. It is one of Coyote's default MCP servers; make sure it is registered in `~/.config/coyote/mcp.json` (run `coyote --install mcp_config` to restore the default template if it is missing). If `ddg-search` is unavailable, the branches still have their global web-search tools to fall back on. The `synthesize` node spawns the `report-writer` sub-agent. Both agents ship with `coyote agents install`; if you install one manually, install both so the agent reference resolves. ## Reflexion The agent has two loops, both built with script nodes that route via `_next`. The engine allows back-edges at runtime; the validator only rejects cycles built from static `next` / `routes` edges, so script `_next` loops are always allowed. **Automated reflexion loop.** After the parallel research map and `vet_sources`, the `critique` node reviews the merged findings against the research plan and the source credibility assessment, and emits `VERDICT: PASS` or `VERDICT: REVISE` with specific feedback. `reflexion_gate.py` then: - `PASS` -> continue to `synthesize`. - `REVISE`, budget remaining -> loop back to `research_each_question`, with the critique injected as `research_feedback` so every parallel branch sees it on the retry. - `REVISE`, budget spent -> continue to `synthesize` anyway (the human approval step is the final backstop). The budget is `MAX_REFLEXION_REVISIONS` in `reflexion_gate.py` (default 2, so the research map runs at most 3 times per pass). **Human-feedback loop.** At `approve` the user answers `accept`, `reject`, or types their own feedback. A free-form answer routes via the approval node's `on_other` to `incorporate_feedback.py`, which folds that text into `research_feedback` and loops back to `research_each_question` for another parallel pass. `settings.max_loop_iterations` (40) is the engine's infinite-loop backstop: it caps the total visits to any single node. ## Fault paths Every stage that can die outright has a `fallback:` edge to a small fault-marker script — the dashed edges in the diagram. A fallback fires after a node's retries are exhausted (`research_one_question` and `synthesize` each get two attempts via `max_attempts: 2`); the engine writes its failure text into the node's state key before routing, and the marker normalizes that text into a `PIPELINE-FAULT: ...` entry in `pipeline_faults`. The five routes: - `plan -> plan_fault -> end_fault` — fail-closed: no plan means nothing to research. - `research_one_question -> question_fault` — branch-local, inside the map branch: one dead research lane becomes a fault finding instead of sinking the whole map. - `vet_sources -> vet_fault -> critique` — degrade-visibly: vetting is a quality lane, not the product; `source_assessment` becomes a neutral "unvetted" note. - `critique -> critique_fault -> reflexion_gate` — degrade-visibly: the rewritten critique deliberately has no `VERDICT:` line, so the gate's malformed-critique PASS default proceeds to synthesis. - `synthesize -> synth_fault -> end_fault` — fail-closed: no report means no product. On the fail-closed routes, `end_fault` renders the `DEEP_RESEARCH FAILED — PIPELINE-FAULT: ...` sentinel. On the degrade-visibly routes, `verify_sources` folds the accumulated faults into a `## Pipeline notes` section shown at the approval step and appended to the accepted report (`{{report}}{{pipeline_notes}}`; empty when there were no faults). Degraded output is never a silent pass — every fault is visible to the reviewer or the caller — and some end node always renders its sentinel, so the graph degrades instead of dying. All 11 scripts also carry a top-level crash guard: a script that throws records a fault and fails forward where the flow allows it (a crashed `reflexion_gate` proceeds to `synthesize`; a crashed `verify_sources` reports that sources were NOT checked) instead of killing the run. ## Running ```sh coyote agents install # ships deep-research coyote -a deep-research "How does HTTP/3 differ from HTTP/2?" coyote -a deep-research "Recent advances in solid-state batteries" coyote -a deep-research # no prompt -> triggers ask_topic ``` ## Anti-hallucination - `research_one_question` (each map branch) is instructed to back every claim with a real retrieved source and never to fabricate URLs, titles, or DOIs. - `vet_sources` classifies every cited source so weak sources are visible to the critique step. - `critique` independently reviews the merged findings and sends weak or uncited work back for another parallel research pass. - `synthesize` (the `report-writer` sub-agent) is grounded: it may use only the gathered findings and must keep each claim's inline source. It has no tools and cannot browse the web. - `verify_sources` probes every cited URL / DOI with an HTTP HEAD request and reports which are unreachable, so the human reviewer sees broken citations before approving. - Fault paths degrade visibly, never silently: a `PIPELINE-FAULT` can only ever surface as a failure sentinel or a `## Pipeline notes` section, never as a clean report. ## Customizing - **Loop budget.** `MAX_REFLEXION_REVISIONS` in `reflexion_gate.py`. - **Map concurrency.** The `research_each_question` node's `max_concurrency: 3` caps simultaneous web-research branches. Raise to investigate more questions in parallel; lower to be gentle on rate-limited providers. - **Per-node model.** Add `model: anthropic:...` to any `llm` node. Cheap models work well for `plan` / `critique` / `vet_sources`; the heavy intelligence is needed in `research_one_question` and the `report-writer` sub-agent. - **Tool scope.** Narrow the `research_one_question` node's `tools:` list to constrain where each branch looks (for example, drop `web_search_coyote` and `mcp:ddg-search` to force arXiv-only research). - **Local knowledge.** Drop files into `knowledge/` to bias every research branch toward your local context (see the *Local knowledge corpus* section above). - **Different writer.** Replace `agent: report-writer` on the `synthesize` node with the name of any other agent. The orchestrator does not care what kind of agent the writer is. - **Skip approval.** Point both `approve` routes at `end_accepted`, or wire `verify_sources` straight to an `end` node. ## Files ``` assets/agents/deep-research/ graph.yaml - agent config + 23-node workflow tools.sh - classify_source custom tool README.md - this file knowledge/ README.md - corpus-format notes research-style-notes.md - starter knowledge file (replace with your notes) scripts/ parse_request.py - _next: bootstrap_research, or ask_topic if no topic bootstrap_research.py - fan-out source: next [plan, knowledge_lookup] plan_fault.py - fail-closed fault marker: dead plan -> end_fault question_fault.py - branch-local fault marker for a dead research lane combine_findings.py - joins map output (question_findings) into findings vet_fault.py - degrade-visibly fault marker: unvetted sources critique_fault.py - degrade-visibly fault marker: skipped critique reflexion_gate.py - _next: research_each_question (revise) or synthesize synth_fault.py - fail-closed fault marker: no report -> end_fault verify_sources.py - HTTP HEAD on cited URLs / DOIs; folds pipeline_faults into the report's "## Pipeline notes" section incorporate_feedback.py - _next: research_each_question, with user feedback ``` See also `assets/agents/report-writer/` — the sub-agent the `synthesize` node spawns.