--- name: parallel-deep-research description: "ONLY use when user explicitly says 'deep research', 'exhaustive', 'comprehensive report', or 'thorough investigation'. Slower and more expensive than parallel-web-search. For normal research/lookup requests, use parallel-web-search instead. Supports follow-ups with a known prior Task interaction ID." compatibility: Requires parallel-cli >= 0.3.0 and internet access. allowed-tools: Bash(parallel-cli:*) metadata: author: parallel --- # Deep Research Research topic: the user's request > Requires `parallel-cli` ≥ 0.3.0 for text output and context chaining. If a documented command or option is missing, check `parallel-cli --version` and that command's `--help`, then follow the installation-specific upgrade guidance in Setup. API, authentication and input errors are not evidence of an older CLI. ## When to use (vs parallel-web-search) ONLY use this skill when the user explicitly requests deep/exhaustive research. It can take several minutes and costs more than a quick search, depending on the processor and task. For normal "research X" requests, quick lookups, or fact-checking, use **parallel-web-search** instead. ## Step 1: Start the research Choose a descriptive output base in a persistent directory (e.g., `reports/ai-chip-market-2026`). Include the returned run ID to make it unique, then use this base in step 2 as `-o "$FILENAME"`. Check for existing `.json` and `.md` files before saving. ```bash parallel-cli research run "the user's request" --processor pro-fast --text --no-wait --json ``` The `--text` flag tells the API to return a markdown report (with inline citations) when the task completes, instead of the default structured JSON. Use it for narrative/report-style requests, which is what most users want from "deep research." Drop `--text` if the user explicitly wants structured JSON output. Optional with `--text`: pass `--text-description "Keep under 1500 words, focus on M&A activity"` to steer length, format, or focus. If this is a **follow-up** and you have a prior Task's returned `interaction_id`, add context chaining. An enrichment `taskgroup_id` and a Search/Extract `session_id` are not Task interaction IDs. Async enrichment does not return a new interaction ID; retain the prior Task ID instead. Context chaining is unavailable for Zero Data Retention (ZDR) accounts, so omit it there and provide the needed context explicitly. ```bash parallel-cli research run "the user's request" --processor lite-fast --text --no-wait --json --previous-interaction-id "$INTERACTION_ID" ``` This reuses the prior Task's context. A lighter processor (`lite-fast` or `base-fast`) can suit a focused follow-up; choose based on the new question's depth rather than assuming all follow-ups are simple. Always use `--no-wait` to separate creation from bounded polling. Save the returned IDs immediately. If creation is interrupted or its response is lost, do not submit a replacement until you have checked whether the first task was created. Use `pro-fast` by default for exploratory research. Run `parallel-cli research processors` for the installed CLI's processor list and latency estimates; these are not deadlines. Choose `ultra` tiers only when explicitly requested and within the user's approved budget. Check [current pricing](https://parallel.ai/pricing) rather than quoting fixed cost multipliers. Fast variants prioritize speed and may use less fresh indexed data. Standard variants may suit freshness-sensitive work, but neither choice guarantees that every source was fetched live. State the relevant date or freshness requirement in the research prompt and check the returned evidence. Parse the JSON output to save `run_id`, `interaction_id`, and `result_url`. Immediately tell the user: - Deep research has been kicked off - The estimated latency for the selected processor, if available - The monitoring URL where they can track progress The task runs server-side; polling can resume later using the saved `run_id`. ## Step 2: Poll for results ```bash parallel-cli research poll "$RUN_ID" -o "$FILENAME" --timeout 60 ``` Important: - Keep each poll bounded; `--timeout 60` allows progress updates between waits. - Avoid `--json` when polling a large report. The `-o` flag saves the full result to files. - With `-o "$FILENAME"`: - `$FILENAME.json` is always written (metadata + basis) - `$FILENAME.md` is written only for returned text output, normally requested with `--text`; auto-schema results can remain JSON-only. - For text, JSON references `output.content_file` relative to the saved JSON file instead of duplicating the report body. - Share the executive summary if one was printed. Some successful outputs have no summary; do not invent one or treat its absence as failure. - Existing output files are refused unless `--force` is explicit. Prefer a new base; use `--force` only when overwriting those files is intended. - Read the actual printed paths. On a write error, the CLI may fall back to the system temp directory, and writes may be partial. Inspect both locations before retrying. Copy a final report from temporary storage to the intended persistent location before presenting it as saved durably. ### If polling times out or is interrupted Timeout exit 5 or interruption ends the local wait, not necessarily the server task. Check the saved task: ```bash parallel-cli research status "$RUN_ID" --json ``` Resume the same poll only for a pending/running task; retrieve completed output and report failed/cancelled or `action_required` states accurately. The CLI's polling loop may not recognize `action_required`, so do not poll that state indefinitely. Never recreate the task merely because a local wait ended. ## Response format **After step 1:** Share the monitoring URL for tracking progress. **After step 2:** 1. Share the executive summary if printed; otherwise say the result is saved and provide a brief summary only from inspected output when needed. 2. Tell the user the generated file paths: - Actual `.md` path, if a text report exists - Actual `.json` path with metadata and basis (and structured content for JSON output) 3. Share the `interaction_id` and tell the user they can ask follow-up questions that build on this research (e.g., "drill deeper into X" or "compare that to Y") After completion, link the saved files rather than repeating the monitoring URL. Avoid loading the whole report into context. Read only the relevant sections when answering a requested summary or follow-up, and cite the returned sources. **Remember the `interaction_id`:** use it for a related research or enrichment follow-up when context chaining is supported by the account. ## If the `parallel-cli` binary is not installed If the shell reports `command not found: parallel-cli`, stop and tell the user to install it, preferably with pipx (`pipx install "parallel-web-tools[cli]"`, then `pipx ensurepath`) or else with the standalone installer (`curl -fsSL https://parallel.ai/install.sh | bash`), then retry their request. If an agent sandbox blocks installation, explain the specific error and give the user the terminal command; do not tell them to disable sandboxing. Do not substitute built-in search, another provider or an answer from memory. ### Command and authentication failures `No such command`, `No such option` or `unrecognized arguments` from an installed CLI indicate a stale or mismatched interface. Check its version and upgrade through its installation method (pipx: `pipx upgrade parallel-web-tools`; uv tool: `uv tool upgrade parallel-web-tools`; Homebrew: `brew upgrade parallel-web/tap/parallel-cli`; npm global: `npm update -g parallel-web-cli`); `parallel-cli update` is for standalone installs only. Verify the required command in the same terminal before retrying. For authentication errors, run `parallel-cli auth --json` and inspect `authenticated`; exit zero alone does not prove authentication. If `authenticated` is false, tell the user to run `parallel-cli login` in their terminal or to set `PARALLEL_API_KEY` in the environment the agent inherits, without requesting credentials in chat. A `403` can be an authorization or billing error: report the actual error and do not assume insufficient balance or add funds automatically. For other API/input errors, report the error without calling it a version problem. Reuse saved run IDs to resume asynchronous work. After an ambiguous creation failure, resolve whether a job exists before retrying creation.