{"slug": "5-ways-to-run-deepresearch-plus-deliverables-tools-and-workflows", "title": "5 Ways to Run DeepResearch, Plus Deliverables, Tools, and Workflows", "summary": "A developer published a guide to Valyu's DeepResearch API, detailing five ways to run multi-step research tasks that produce deliverables such as Markdown, PDF, schema-based JSON or TOON reports, plus spreadsheets, documents and slide decks. The walkthrough covers Valyu CLI 1.2.2 and the valyu 2.12.2 Python package, separating research modes (fast, standard, heavy, max) from output formats and showing asynchronous task creation, watching, webhooks and human-review pauses.", "body_md": "*Day 3 of 30 Days of Search.*\n\nA research task does not always end with a report. Your app might need JSON. An analyst might need an Excel workbook. A team meeting might need slides.\n\nSearching is very common and popular. However there's a flow that makes use multi-step searches and analysis in such a way that gives you better & deeper research-analyst-type results. It's called **DeepResearch**. \n\nWith [deep research](https://docs.valyu.ai/guides/deepresearch), you can choose a research depth, an output format, the files to generate, and the tools the agent can use. You can also pause for human review or run a reusable workflow.\n\nBy the end of this guide, you will know how to:\n\nThe CLI examples in this article use **Valyu CLI 1.2.2**. The Python examples use **`valyu` 2.12.2**. Mode names, prices, and feature details below were checked against the current documentation.\n\nA Search API returns results for your application to use. DeepResearch takes responsibility for the broader investigation: planning searches, reading sources, following up on gaps, and writing a cited result.\n\nThe conceptual flow looks like this:\n\n[Valyu](https://valyu.ai) can search the web alongside academic, financial, medical, patent, and other specialised sources. The sources available to a particular run depend on your account access and search configuration.\n\nTasks are **asynchronous**: create a task, save its ID, then wait or receive a webhook notification. If you need a quick synchronous answer rather than an investigation, consider the [Answer API](https://docs.valyu.ai/guides/answer-api).\n\nKeep three decisions separate:\n\n| Decision | What you choose | \n|---|---|\n| Research mode | How much research budget to allocate: `fast` ,`standard` ,`heavy` , or`max` | \n| Report output | Markdown, PDF, schema-based JSON, or schema-based TOON | \n| Deliverables | Additional files such as a spreadsheet, document, or slide deck | \n\nPDF and JSON are **output choices**, not research modes. A longer run also does not guarantee that every finding is correct. Read the cited evidence before relying on important conclusions.\n\nYou need a [Valyu account](https://www.valyu.ai) with available free credits. Get access at [platform.valyu.ai](https://platform.valyu.ai).\n\nInstall the CLI:\n\n```\nnpm install -g @valyu/cli@1.2.2\nvalyu login\nvalyu --version\n```\n\n`valyu login` opens a browser authentication flow. Standalone installation options are in the [CLI documentation](https://docs.valyu.ai/integrations/cli).\n\nUse `fast` when you need a limited research pass rather than a broad investigation. For example, compare two approaches for one specific application:\n\n```\nvalyu deepresearch create \\\n  \"Compare RAG and fine-tuning for a developer-support assistant. Focus on updating knowledge and citing sources.\" \\\n  --mode fast \\\n  --output-format markdown\n```\n\nCreation returns a task ID. Paste it into the variable below:\n\n```\nTASK_ID=\"paste-the-returned-task-id\"\nvalyu deepresearch watch \"$TASK_ID\"\n```\n\n*Completed report on Valyu platform*\n\nUse standard mode when you need a wider comparison with practical constraints:\n\n```\nvalyu deepresearch create \\\n  \"Compare RAG and fine-tuning for a developer-support assistant. Cover freshness, citations, maintenance, and evaluation.\" \\\n  --mode standard \\\n  --research-strategy \"Prioritise official documentation and published evaluations. Separate evidence from recommendations.\" \\\n  --report-format \"Write an engineering brief with a comparison table, recommendations, limitations, and citations.\" \\\n  --output-format markdown\n```\n\nThe distinction between the two instruction flags is useful:\n\n`--research-strategy` guides the investigation: what to examine and which evidence to prioritise.`--report-format` guides the result: its structure, style, and length.\nThe typical runtime is **10 to 20 minutes**. A well-scoped question matters more than asking for a long report.\n\nUse `heavy` when the work involves conflicting evidence, multiple approaches, or a detailed research review:\n\n```\nvalyu deepresearch create \\\n  \"Evaluate RAG, fine-tuning, and hybrid approaches for developer support. Compare published evaluations, failure cases, and operational trade-offs.\" \\\n  --mode heavy \\\n  --research-strategy \"Compare evaluation methods and their limitations. Flag results that are not directly comparable.\" \\\n  --output-format markdown\n```\n\nIt takes approximately 90 minutes** for heavy mode.\n\nThere is also **`max`** mode for exhaustive research. It has a higher base price and requires at least $15 in available credits. Check the task scope before choosing it.\n\n| Mode | Listed base price per task | Runtime listed on the pricing page | Useful starting point | \n|---|---|---|---|\n| `fast` | $0.10 | About 5 minutes | A focused lookup or lightweight comparison | \n| `standard` | $0.50 | About 10 to 20 minutes | A balanced research brief | \n| `heavy` | $2.50 | Up to about 90 minutes | Complex analysis with competing evidence | \n| `max` | $15.00 | Up to about 180 minutes | An exhaustive investigation | \n\nThe API defaults to Markdown. Request both formats explicitly when you want text for your app and a PDF for readers:\n\n```\nvalyu deepresearch create \\\n  \"Compare RAG and fine-tuning for developer support. Write an executive summary with an evidence table and citations.\" \\\n  --mode standard \\\n  --output-format markdown \\\n  --output-format pdf\n```\n\nAfter the task completes, its response includes the report in `output` and, when generated successfully, the PDF link in `pdf_url`.\n\nPDF changes how you distribute the report. It does not select a deeper research mode. The CLI's `--no-pdf` flag and default format behaviour are separate from the API's Markdown default; explicit formats avoid that ambiguity.\n\n*Example of a deepresearch report with PDF output*\n\nUse a JSON schema when your next step is a dashboard, database, or another agent. This avoids an extra prose-to-data extraction step.\n\nThis example runs **DeepResearch**, not the separate Answer API:\n\n```\nvalyu deepresearch create \\\n  \"Compare RAG and fine-tuning for developer support. Return each approach, its best fit, its limitations, and supporting source URLs.\" \\\n  --mode standard \\\n  --structured '{\n  \"type\": \"object\",\n  \"properties\": {\n    \"approaches\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"name\": { \"type\": \"string\" },\n          \"best_fit\": { \"type\": \"string\" },\n          \"limitations\": { \"type\": \"string\" },\n          \"source_urls\": {\n            \"type\": \"array\",\n            \"items\": { \"type\": \"string\" }\n          }\n        },\n        \"required\": [\"name\", \"best_fit\", \"limitations\", \"source_urls\"]\n      }\n    }\n  },\n  \"required\": [\"approaches\"]\n}'\n```\n\nFor larger schemas, save the JSON to a file and use `--structured-file schema.json`.\n\n**Do not combine a schema with Markdown or PDF report output.** Structured output is an alternative report representation. Validate the returned data and check its evidence before using it for decisions.\n\nDeepResearch also supports **TOON**, a token-oriented structured representation. It requires a schema. \n\nIn the CLI, use `--structured-file schema.json --output-format toon`. Use JSON when your existing application expects JSON; TOON is an optional representation, not another file-deliverable type.\n\nA report format controls the main response. **Deliverables** are additional files generated from the research, each with its own type, description, status, and download URL.\n\nYou can specify all five of these file types:\n\n| Deliverable type | File format | Example use | \n|---|---|---|\n| `csv` | CSV ( `.csv` ) | A research table to import into another system | \n| `xlsx` | Excel workbook ( `.xlsx` ) | A comparison workbook with evidence columns | \n| `docx` | Word document ( `.docx` ) | An editable research brief | \n| `pptx` | PowerPoint presentation ( `.pptx` ) | A slide deck for a team review | \n| `pdf` | PDF document ( `.pdf` ) | A separately specified formatted document | \n\nThe task API accepts up to **10 deliverables**. Excel, Word, and PowerPoint deliverables require **code execution** to be enabled. The basic PDF report requested through `output_formats` is separate from the `deliverables` list.\n\n``` python\nfrom valyu import Valyu\n\nclient = Valyu()\ntask = client.deepresearch.create(\n    query=\"Compare RAG and fine-tuning for a developer-support assistant. \"\n          \"Cover freshness, citations, maintenance, and evaluation.\",\n    mode=\"heavy\",\n    output_formats=[\"markdown\"],\n    tools={\"code_execution\": True, \"charts\": True},\n    deliverables=[\n        {\n            \"type\": \"xlsx\",\n            \"description\": \"Comparison workbook with an evidence URL for each row.\",\n            \"columns\": [\"Approach\", \"Best fit\", \"Limitations\", \"Source URL\"],\n        },\n        {\n            \"type\": \"pptx\",\n            \"description\": \"Six-slide engineering review with recommendations \"\n                           \"and a sources slide.\",\n            \"slides\": 6,\n        },\n    ],\n)\n\nif not task.success or not task.deepresearch_id:\n    raise RuntimeError(\"Could not create the research task.\")\n\nprint(\"Save this task ID:\", task.deepresearch_id, flush=True)\nresult = client.deepresearch.wait(\n    task.deepresearch_id,\n    poll_interval=20,\n    max_wait_time=7200,\n)\n\nif not result.success or result.status != \"completed\":\n    raise RuntimeError(\"Research did not complete successfully. Check the task status.\")\n\nprint(result.output)\nprint(\"Reported total cost:\", result.cost)\nfor item in result.deliverables or []:\n    if item.status == \"completed\":\n        print(item.type, item.title, item.url)\n    else:\n        print(item.type, \"deliverable status:\", item.status)\n```\n\nThe waiting options use **seconds** in Python. `7200` is a two-hour polling budget, not a guaranteed completion time. If waiting stops, keep the task ID and inspect that existing run rather than creating it again.\n\nCheck each file's status, not only the report status. Deliverable download URLs are signed and expire; download files you need to keep.\n\nThe optional tools are off by default for a freeform task. Enabling a tool makes it available; the agent decides whether to use it.\n\n| Tool | What it enables | Important detail | \n|---|---|---|\n| `code_execution` | Run Python calculations and generate files in a sandbox | No network access; required for XLSX, DOCX, and PPTX deliverables | \n| `screenshots` | Capture web pages, including charts and dashboards | Captures appear in the task's `images` ; usage is chargeable | \n| `browser_use` | Navigate pages through autonomous browser sessions | Enable it when the investigation needs browser interaction | \n| `charts` | Generate charts for the report | Generated charts appear in `images` ; no chart surcharge | \n\nFor a terminal-based run with code execution, screenshots, and browser use:\n\n```\nvalyu deepresearch create \\\n  \"Compare publicly listed pricing for developer-support tools. Capture relevant pricing pages and distinguish monthly from annual billing.\" \\\n  --mode standard \\\n  --code-execution \\\n  --screenshots \\\n  --browser-use \\\n  --output-format markdown\n```\n\nThe Python example above enables charts through `tools={\"code_execution\": True, \"charts\": True}`. The API also accepts per-tool `max_calls` limits. You can lower the documented limits, not raise them.\n\nA screenshot records a page; it does not prove a pricing claim is complete or current. A calculation is only as good as its inputs. Keep the source links and assumptions with the result.\n\n*A deepresearch report showing research activity*\n\nHuman-in-the-loop, or **HITL**, adds optional checkpoints. You can enable any combination of four:\n\n| Checkpoint | What the reviewer does | \n|---|---|\n| `planning_questions` | Answer clarifying questions before research begins | \n| `plan_review` | Approve the research plan or request changes | \n| `source_review` | Include or exclude source domains after research | \n| `outline_review` | Review the report outline before writing | \n\nThe CLI uses hyphenated checkpoint names. Start an interactive session with plan and source review:\n\n```\nvalyu deepresearch create \\\n  \"Compare RAG and fine-tuning for developer support, focusing on evidence quality and deployment constraints.\" \\\n  --mode heavy \\\n  --hitl plan-review,source-review \\\n  --output-format markdown \\\n  --watch\n```\n\nRun this in an interactive terminal so `watch` can prompt for your decisions. In an application, use the SDK's interaction callback or the task's `respond` endpoint to collect and submit a person's response.\n\nAt a checkpoint, status becomes `awaiting_input`. The documentation says an unanswered checkpoint becomes `paused` after five minutes, with state saved; you can respond later to resume. Human response time adds to the overall runtime.\n\nHITL is available for individual tasks, **not batch requests**. It is useful when scope, source selection, or the report structure needs review before the work proceeds.\n\nIf you produce the same kind of brief repeatedly, a **workflow** gives you a reusable, versioned starting point.\n\nA workflow can bundle a prompt with typed variables, a research strategy, report instructions, output formats, deliverables, tools, and a recommended mode. You supply the changing inputs, such as a company or sector.\n\nValyu provides [curated workflows](https://platform.valyu.ai/user/workflows), and organisations can create private ones. Examples of these workflows include company profiles, diligence briefs, earnings research, and competitor scans. **Workflows are currently in beta.**\n\nThe workflow runs through the normal DeepResearch lifecycle. It is not a separate synchronous API.\n\n*Curated workflows on the platform*\n\nUsing the Python environment above, save this as `preview_workflow.py` and run `python preview_workflow.py`:\n\n``` python\nfrom valyu import Valyu\n\nclient = Valyu()\nlisting = client.workflows.list(scope=\"valyu\", vertical=\"investment-banking\")\nif not listing.success:\n    raise RuntimeError(\"Could not list workflows.\")\n\nfor workflow in listing.workflows or []:\n    print(workflow.slug, workflow.title)\n\nprofile = client.workflows.get(\"ib-company-profile\")\nif not profile.success or not profile.workflow or profile.workflow.version is None:\n    raise RuntimeError(\"Could not inspect the workflow.\")\n\nprint(\"Workflow inputs:\", profile.workflow.variables)\npreview = client.workflows.preview(\n    \"ib-company-profile\",\n    workflow_params={\"company\": \"NVIDIA (NVDA)\"},\n    workflow_version=profile.workflow.version,\n)\nif not preview.success or not preview.resolved:\n    raise RuntimeError(\"Could not preview the workflow.\")\n\nprint(\"Resolved research request:\", preview.resolved.input)\nprint(\"Mode:\", preview.resolved.mode)\nprint(\"Deliverables:\", preview.resolved.deliverables)\nprint(\"Estimated credits:\", preview.estimated_credits)\n```\n\nA preview resolves the template **without starting research or spending research credits**. Inspect the workflow's `variables`: a different template can require different parameter names.\n\nWhen you are ready to start the billed task, add this to the same file:\n\n```\ntask = client.deepresearch.create(\n    workflow_id=\"ib-company-profile\",\n    workflow_params={\"company\": \"NVIDIA (NVDA)\"},\n    workflow_version=profile.workflow.version,\n)\nif not task.success or not task.deepresearch_id:\n    raise RuntimeError(\"Could not start the workflow.\")\n\nprint(\"Workflow task ID:\", task.deepresearch_id)\n```\n\nWatch that ID with `valyu deepresearch watch` using the same account, or wait through the SDK.\n\nDo not send `query`, `research_strategy`, or `report_format` alongside `workflow_id`. The template supplies those fields. Pinning `workflow_version` keeps later template changes from silently changing the process, although live sources can still produce different results.\n\nYou can override options such as mode, deliverables, or search filters per run. Tools merge with the template's settings: explicitly disable a template-enabled tool if you do not want it.\n\n*Workflow preview with filled variables in the platform UI*\n\n**Note:** Give your agents DeepResearch access with a key from [platform.valyu.ai](https://platform.valyu.ai). $20 in free credits; check the current offer before signing up.\n\nYes. Use `--output-format markdown --output-format pdf` in the CLI, or `output_formats=[\"markdown\", \"pdf\"]` in Python. A schema cannot be combined with those report formats.\n\nCSV (`csv`), Excel (` xlsx`), Word (` docx`), PowerPoint (` pptx`), and PDF (` pdf`). XLSX, DOCX, and PPTX require code execution. Deliverables have their own statuses and download links.\n\nYes, when you enable those tools. Code execution runs Python in a sandbox without network access. Browser use is a separate capability. Screenshots and charts are also optional tools.\n\nYes. Enable `plan_review`, or `plan-review` in the CLI's `--hitl` list. The task waits for your response. You can also enable clarifying questions, source review, and outline review.\n\nNo. A workflow is a template for new research runs. A preview resolves its inputs without executing research; running it creates a new DeepResearch task with normal billing.\n\nNo. A larger research budget can support a broader investigation. It does not replace checking citations, comparing sources, and reviewing the assumptions behind calculations.", "url": "https://wpnews.pro/news/5-ways-to-run-deepresearch-plus-deliverables-tools-and-workflows", "canonical_source": "https://dev.to/valyuai/5-ways-to-run-deepresearch-plus-deliverables-tools-and-workflows-2c04", "published_at": "2026-10-03 15:00:39+00:00", "updated_at": "2026-10-03 15:07:57.144128+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-search", "developer-tools"], "entities": ["Valyu", "Valyu CLI", "Valyu DeepResearch", "Answer API"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/5-ways-to-run-deepresearch-plus-deliverables-tools-and-workflows", "markdown": "https://wpnews.pro/news/5-ways-to-run-deepresearch-plus-deliverables-tools-and-workflows.md", "text": "https://wpnews.pro/news/5-ways-to-run-deepresearch-plus-deliverables-tools-and-workflows.txt", "jsonld": "https://wpnews.pro/news/5-ways-to-run-deepresearch-plus-deliverables-tools-and-workflows.jsonld"}}