5 Ways to Run DeepResearch, Plus Deliverables, Tools, and Workflows

Day 3 of 30 Days of Search.

A 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.

Searching 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.

With deep research, 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.

By the end of this guide, you will know how to:

• Run fast, standard, or heavy deep research from the terminal.
• Request a PDF report or schema-based structured output.
• Generate CSV, Excel, Word, PowerPoint, and PDF deliverables.
• Enable code execution, screenshots, browser use, and charts.
• Review the plan and sources through human-in-the-loop checkpoints.
• Discover, preview, and run reusable research workflows.

The 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.

DeepResearch is a research loop, not a longer search result

A 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.

The conceptual flow looks like this:

Valyu 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.

Tasks 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.

Keep three decisions separate:

Decision	What you choose
Research mode	How much research budget to allocate: fast, standard, heavy, or max
Report output	Markdown, PDF, schema-based JSON, or schema-based TOON
Deliverables	Additional files such as a spreadsheet, document, or slide deck

PDF 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.

Prerequisite Setup.

You need a Valyu account with available free credits. Get access at platform.valyu.ai.

Install the CLI:

npm install -g @valyu/cli@1.2.2
valyu login
valyu --version

...or use the best option for installing the CLI for your system.

valyu login opens a browser authentication flow. Standalone installation options are in the CLI documentation.

Five ways to run DeepResearch

1. Fast mode: answer a focused research question

Use fast when you need a limited research pass rather than a broad investigation. For example, compare two approaches for one specific application:

valyu deepresearch create \
  "Compare RAG and fine-tuning for a developer-support assistant. Focus on updating knowledge and citing sources." \
  --mode fast \
  --output-format markdown

Creation returns a task ID. Paste it into the variable below:

TASK_ID="paste-the-returned-task-id"
valyu deepresearch watch "$TASK_ID"

Completed report on Valyu platform

2. Standard mode: start here for a broader brief

Use standard mode when you need a wider comparison with practical constraints:

valyu deepresearch create \
  "Compare RAG and fine-tuning for a developer-support assistant. Cover freshness, citations, maintenance, and evaluation." \
  --mode standard \
  --research-strategy "Prioritise official documentation and published evaluations. Separate evidence from recommendations." \
  --report-format "Write an engineering brief with a comparison table, recommendations, limitations, and citations." \
  --output-format markdown

The distinction between the two instruction flags is useful:

• --research-strategy guides the investigation: what to examine and which evidence to prioritise.
• --report-format guides the result: its structure, style, and length.

The typical runtime is 10 to 20 minutes. A well-scoped question matters more than asking for a long report.

3. Heavy mode: investigate a question with more moving parts

Use heavy when the work involves conflicting evidence, multiple approaches, or a detailed research review:

valyu deepresearch create \
  "Evaluate RAG, fine-tuning, and hybrid approaches for developer support. Compare published evaluations, failure cases, and operational trade-offs." \
  --mode heavy \
  --research-strategy "Compare evaluation methods and their limitations. Flag results that are not directly comparable." \
  --output-format markdown

It takes approximately 90 minutes** for heavy mode.

There 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.

Mode comparison

Mode	Listed base price per task	Runtime listed on the pricing page	Useful starting point
fast	$0.10	About 5 minutes	A focused lookup or lightweight comparison
standard	$0.50	About 10 to 20 minutes	A balanced research brief
heavy	$2.50	Up to about 90 minutes	Complex analysis with competing evidence
max	$15.00	Up to about 180 minutes	An exhaustive investigation

4. PDF output: make the report easy to share

The API defaults to Markdown. Request both formats explicitly when you want text for your app and a PDF for readers:

valyu deepresearch create \
  "Compare RAG and fine-tuning for developer support. Write an executive summary with an evidence table and citations." \
  --mode standard \
  --output-format markdown \
  --output-format pdf

After the task completes, its response includes the report in output and, when generated successfully, the PDF link in pdf_url.

PDF 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.

Example of a deepresearch report with PDF output

5. Structured output: return data your application can consume

Use a JSON schema when your next step is a dashboard, database, or another agent. This avoids an extra prose-to-data extraction step.

This example runs DeepResearch, not the separate Answer API:

valyu deepresearch create \
  "Compare RAG and fine-tuning for developer support. Return each approach, its best fit, its limitations, and supporting source URLs." \
  --mode standard \
  --structured '{
  "type": "object",
  "properties": {
    "approaches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "best_fit": { "type": "string" },
          "limitations": { "type": "string" },
          "source_urls": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["name", "best_fit", "limitations", "source_urls"]
      }
    }
  },
  "required": ["approaches"]
}'

For larger schemas, save the JSON to a file and use --structured-file schema.json.

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.

DeepResearch also supports TOON, a token-oriented structured representation. It requires a schema.

In 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.

Deliverables: generate the files your team needs

A report format controls the main response. Deliverables are additional files generated from the research, each with its own type, description, status, and download URL.

You can specify all five of these file types:

Deliverable type	File format	Example use
csv	CSV (.csv)	A research table to import into another system
xlsx	Excel workbook (.xlsx)	A comparison workbook with evidence columns
docx	Word document (.docx)	An editable research brief
pptx	PowerPoint presentation (.pptx)	A slide deck for a team review
pdf	PDF document (.pdf)	A separately specified formatted document

The 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.

Generate an Excel workbook and a PowerPoint deck with Python

from valyu import Valyu

client = Valyu()
task = client.deepresearch.create(
    query="Compare RAG and fine-tuning for a developer-support assistant. "
          "Cover freshness, citations, maintenance, and evaluation.",
    mode="heavy",
    output_formats=["markdown"],
    tools={"code_execution": True, "charts": True},
    deliverables=[
        {
            "type": "xlsx",
            "description": "Comparison workbook with an evidence URL for each row.",
            "columns": ["Approach", "Best fit", "Limitations", "Source URL"],
        },
        {
            "type": "pptx",
            "description": "Six-slide engineering review with recommendations "
                           "and a sources slide.",
            "slides": 6,
        },
    ],
)

if not task.success or not task.deepresearch_id:
    raise RuntimeError("Could not create the research task.")

print("Save this task ID:", task.deepresearch_id, flush=True)
result = client.deepresearch.wait(
    task.deepresearch_id,
    poll_interval=20,
    max_wait_time=7200,
)

if not result.success or result.status != "completed":
    raise RuntimeError("Research did not complete successfully. Check the task status.")

print(result.output)
print("Reported total cost:", result.cost)
for item in result.deliverables or []:
    if item.status == "completed":
        print(item.type, item.title, item.url)
    else:
        print(item.type, "deliverable status:", item.status)

The 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.

Check each file's status, not only the report status. Deliverable download URLs are signed and expire; download files you need to keep.

Tools: let the agent calculate, inspect pages, and create charts

The optional tools are off by default for a freeform task. Enabling a tool makes it available; the agent decides whether to use it.

Tool	What it enables	Important detail
code_execution	Run Python calculations and generate files in a sandbox	No network access; required for XLSX, DOCX, and PPTX deliverables
screenshots	Capture web pages, including charts and dashboards	Captures appear in the task's images; usage is chargeable
browser_use	Navigate pages through autonomous browser sessions	Enable it when the investigation needs browser interaction
charts	Generate charts for the report	Generated charts appear in images; no chart surcharge

For a terminal-based run with code execution, screenshots, and browser use:

valyu deepresearch create \
  "Compare publicly listed pricing for developer-support tools. Capture relevant pricing pages and distinguish monthly from annual billing." \
  --mode standard \
  --code-execution \
  --screenshots \
  --browser-use \
  --output-format markdown

The 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.

A 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.

A deepresearch report showing research activity

Human in the loop: review the work before the final report

Human-in-the-loop, or HITL, adds optional checkpoints. You can enable any combination of four:

Checkpoint	What the reviewer does
planning_questions	Answer clarifying questions before research begins
plan_review	Approve the research plan or request changes
source_review	Include or exclude source domains after research
outline_review	Review the report outline before writing

The CLI uses hyphenated checkpoint names. Start an interactive session with plan and source review:

valyu deepresearch create \
  "Compare RAG and fine-tuning for developer support, focusing on evidence quality and deployment constraints." \
  --mode heavy \
  --hitl plan-review,source-review \
  --output-format markdown \
  --watch

Run 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.

At 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.

HITL 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.

Workflows: reuse a research process instead of rebuilding the prompt

If you produce the same kind of brief repeatedly, a workflow gives you a reusable, versioned starting point.

A 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.

Valyu provides curated 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.

The workflow runs through the normal DeepResearch lifecycle. It is not a separate synchronous API.

Curated workflows on the platform

Discover, inspect, and preview a workflow in code

Using the Python environment above, save this as preview_workflow.py and run python preview_workflow.py:

from valyu import Valyu

client = Valyu()
listing = client.workflows.list(scope="valyu", vertical="investment-banking")
if not listing.success:
    raise RuntimeError("Could not list workflows.")

for workflow in listing.workflows or []:
    print(workflow.slug, workflow.title)

profile = client.workflows.get("ib-company-profile")
if not profile.success or not profile.workflow or profile.workflow.version is None:
    raise RuntimeError("Could not inspect the workflow.")

print("Workflow inputs:", profile.workflow.variables)
preview = client.workflows.preview(
    "ib-company-profile",
    workflow_params={"company": "NVIDIA (NVDA)"},
    workflow_version=profile.workflow.version,
)
if not preview.success or not preview.resolved:
    raise RuntimeError("Could not preview the workflow.")

print("Resolved research request:", preview.resolved.input)
print("Mode:", preview.resolved.mode)
print("Deliverables:", preview.resolved.deliverables)
print("Estimated credits:", preview.estimated_credits)

A preview resolves the template without starting research or spending research credits. Inspect the workflow's variables: a different template can require different parameter names.

When you are ready to start the billed task, add this to the same file:

task = client.deepresearch.create(
    workflow_id="ib-company-profile",
    workflow_params={"company": "NVIDIA (NVDA)"},
    workflow_version=profile.workflow.version,
)
if not task.success or not task.deepresearch_id:
    raise RuntimeError("Could not start the workflow.")

print("Workflow task ID:", task.deepresearch_id)

Watch that ID with valyu deepresearch watch using the same account, or wait through the SDK.

Do 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.

You 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.

Workflow preview with filled variables in the platform UI

Other features worth knowing about

• Source and date filters: constrain the search by dataset, source preset, domain, and date range. A natural-language request to prefer a source is different from an enforced search filter.
• Files and URLs: add up to 10 files and 10 seed URLs for research context. File size and type limits still apply.
• Previous reports: use up to three earlier task IDs as context for a follow-up investigation.
• Webhooks: receive completion or failure notifications instead of keeping a polling process open. Verify the webhook signature; store the secret returned at creation.
• Batch research: run multiple tasks with shared configuration. HITL checkpoints are not available in batches.

Note: Give your agents DeepResearch access with a key from platform.valyu.ai. $20 in free credits; check the current offer before signing up.

FAQ

Can I request Markdown and a PDF together?

Yes. 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.

Which deliverable formats can I specify?

CSV (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.

Can the agent run code and browse pages?

Yes, 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.

Can I approve the plan before research starts?

Yes. 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.

Are workflows the same as a saved report?

No. 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.

Does a deeper mode guarantee a correct result?

No. A larger research budget can support a broader investigation. It does not replace checking citations, comparing sources, and reviewing the assumptions behind calculations.