> Public product help. This page has no customer entries, projects, chat transcripts, API keys, or horizon contents.
> Reading that data requires `Authorization: Bearer` (a signed-in app session JWT, or a Headless access token).
> Do not call Supabase `/rest/v1` with a Headless JWT. Data reads go through `/casc/v1/headless/v1/rest`.

# Deep Research Agent

The **Deep Research Agent** runs multi-step AI research jobs: it searches the web, reads pages, searches internal Zagger documentation, stores cited sources, and produces a written report plus structured JSON. Use it for competitive briefs, grant scouting, investor lists, customer discovery, document synthesis, and **prediction market contest** packages with CSV export.

## Where to find it

Open **Research** in the main sidebar (between Projects and Horizon). The left panel defaults to **All recent runs** (every job for your account, including chat-started ones) and also lists saved research projects. Select a project to filter runs and edit saved settings.

You can also start and follow jobs from **project chat** via tools `start_deep_research`, `get_deep_research_status`, and `get_deep_research_report` (available on agent prompts and workflow buttons). Jobs still run in the background worker — chat only queues and polls. Starting from chat also creates a linked research project so the run shows under Research.

## From project chat / workflow buttons

Deep Research in chat is three separate tool actions. Jobs run in a background worker — chat only queues, polls, and fetches the report. Create separate Tools UI tools (or use the built-in slugs) for **start**, **status**, and **report** if the model should use all three.

| Action | Typical slug | Required args | What it does |
| --- | --- | --- | --- |
| **Start** | `start_deep_research` (or a Tools UI tool with Research action = Start) | `prompt` (full research brief) | Queues a background job and returns immediately with a `job_id` and initial `status` (usually `queued`). |
| **Status** | `get_deep_research_status` | `job_id` | Returns current status: `queued`, `running`, `completed`, `needs_review`, `failed`, or `cancelled`. |
| **Report** | `get_deep_research_report` | `job_id` | Returns `final_report` (and optional structured output) when status is `completed` or `needs_review`. Long reports may be truncated (~12k chars) with `report_truncated: true`. |

### Does start return an id?

**Yes.** Start returns a `job_id` immediately. Status and report both require that same `job_id`. The tool summary also tells the model not to invent a full report and to poll later.

### Recommended chat flow

1. Call the **start** tool with a self-contained `prompt` (optional `mode`, `title`, provider/model).
2. Receive `job_id`; tell the user research is running (they can also follow it under **Research**).
3. Later, call **status** with `job_id` until status is `completed` or `needs_review` (or `failed` / `cancelled`).
4. Call **report** with the same `job_id` and use `final_report` in the reply.

```
`1) start tool → job_id 2) tell user research is running 3) status(job_id) until completed / needs_review 4) report(job_id) → final_report`
```

### Setup checklist

1. On a catalog prompt (or workflow button prompt), pick the Deep Research tools in the tools list (or leave tools empty so the global allowlist applies — research tools are re-injected like email drafts).
2. If you configure Tools UI research tools, create separate tools for Start, Status, and Report so the model can poll and fetch the report.
3. Instruct the model to call start with a self-contained `prompt`, keep the returned `job_id`, poll status, then fetch the report — and not invent findings while the job is still running.

Jobs appear under **Research → All recent runs** whether started from chat or the Research UI. If a run stays `queued` for a long time, restart the API server so the research worker can recover stuck jobs, then use **Edit settings & re-run** / retry if needed.

## Research projects (saved settings)

Each research topic is saved as a **research project** — title, objective, mode, provider, model, and limits. Settings persist so you can edit and re-run without retyping. Chat start also auto-creates a project when one is not supplied.

- **New** — Opens a popup to enter settings. Click **Save & run** to save the project and queue a job.
- **All recent runs** — Default view: recent jobs across all projects (and older chat jobs that had no project link).
- **Project dropdown** — Switch between active projects on the left. Enable **Show archived** to include archived projects.
- **Edit settings** — Change parameters before the next run. Use **Save** to update only, or **Save & run** to update and queue a new job.
- **Run** — Re-run the saved project settings without opening the editor.
- **Archive / Unarchive** — Hide finished topics from the default list without deleting run history.
- **Edit settings & re-run** — On failed, cancelled, or needs-review runs, opens the settings popup pre-filled so you can adjust parameters and start a new run.

## Starting a research job

1. Click **New** (or **New research project** in the main panel).
2. Enter a **title** and **objective** (what you want researched).
3. Choose a **mode** (see below), **provider**, and **model**.
4. Set **max steps** and **max sources** if needed.
5. Click **Save & run**. The job is queued and processed in the background.

While a job is `queued` or `running`, the detail panel refreshes automatically. You can **Cancel** an active job. For finished jobs that need another attempt, use **Edit settings & re-run** so you can change parameters before retrying.

## Research modes

| Mode | Output |
| --- | --- |
| `general_report` | Executive summary, findings, risks, recommendations |
| `competitive_analysis` | Competitor profiles and positioning |
| `grant_research` | Grant opportunities with fit and requirements |
| `investor_research` | Investor targets with thesis and relevance |
| `prediction_market_contest` | Contest title, CTA, and objective questions with resolution methods; supports **CSV export** |
| `customer_discovery` | Segments, pain points, hypotheses |
| `document_synthesis` | Themes across internal or cited documents |

## What the agent can do (tools)

- **webSearch** (Zagger research provider) — Uses your configured web search API keys (Brave, Serper, Tavily, or feel-lucky scrape). Configure under **Settings → User → Web Search API Keys**.
- **fetchUrl** — Fetches and extracts readable text from public URLs.
- **searchInternalDocs** — Semantic search over ingested product documentation (default: `zagger_product_help` horizon, `product_docs_search` tool). Requires product docs to be ingested and embedded.
- **storeSource** — Persists citations (title, URL, snippet, scores) for the job.

The agent is instructed not to fabricate citations and to call `storeSource` for important evidence.

## Job status

| Status | Meaning |
| --- | --- |
| `queued` | Waiting for the background worker |
| `running` | Agent loop in progress |
| `completed` | Report and structured output saved |
| `needs_review` | Finished but some sources had low credibility scores |
| `failed` | Error recorded on the job (missing API key, timeout, etc.) |
| `cancelled` | Stopped by the user |

## Exports and follow-up actions

- **Export as Markdown** — Full report, structured JSON, sources, and step timeline.
- **Export as JSON** — Machine-readable job, sources, and steps.
- **Export as CSV** — Only for `prediction_market_contest` mode.
- **Open in project chat** — Pick a project; Zagger creates a new session with the research report as the first message so you can continue in chat.
- **Ingest to Horizon** — Pick a project, select ingestion planes, preview gap-fill updates, and apply structured data from the research into your horizon groups (same flow as chat message ingest).

## Provider and model

Choose a research provider on the project settings popup:

- **OpenAI** — Responses API model + `openai.tools.webSearch` for provider-native web research.
- **Anthropic** — Claude model + `anthropic.tools.webSearch_20250305` for provider-native web research.
- **Zagger research** — Any chat model from your catalog plus Zagger `webSearch` (Brave, Serper, Tavily, or feel-lucky scrape). Configure keys under **Settings → User → Web Search API Keys**.

Your API key for the selected LLM provider must be configured under **Settings → User**. Structured JSON output may use a separate cheap OpenAI model (env: `RESEARCH_STRUCT_PROVIDER`, `RESEARCH_STRUCT_MODEL`).

## Requirements and limits

- **LLM API keys** — Same as chat: add OpenAI, Anthropic, or other provider keys under **Settings → User**.
- **Web search keys** — Required for web research unless using feel-lucky scrape.
- **Embeddings** — Internal doc search works when product help docs are ingested and embedded (see Help embedding banner for admins).
- Default limits: 125 agent steps (max 500), 40 stored sources, 5-minute job timeout (server env overrides available).

## Research vs project chat

**Project chat** is interactive, session-based, and capped at a short tool loop per message. **Deep Research** is a dedicated background job with a longer multi-step loop, persistent sources, structured outputs, and exports — better for one-off briefs and contest packages than back-and-forth chat.

## API (advanced)

REST endpoints under `/casc/v1/api/research/`: manage research projects (create, update, archive, run), create and list jobs, fetch job/steps/sources, cancel, retry, and export. See server `routes/research.js` for the contract.

## Related docs

- Web search setup — [tools](tools.md)
- Product help and Ask Zagger — [workflows](workflows.md)
- Projects and chat — [projects](projects.md)