DEV Community

Cover image for How to Build Your Own DeepResearch Workflow
Valyu AI profile image Prosper Otemuyiwa
Prosper Otemuyiwa for Valyu AI

Posted on

How to Build Your Own DeepResearch Workflow

#ai #hacktoberfest #search #typescript

Day 13 of 30 Days of Search.

TL;DR

  • A custom DeepResearch workflow saves a research brief your team can reuse. The prompt, research strategy, report structure and requested files stay in the template; the supplier, company or other inputs change for each assignment.
  • This walkthrough builds a real Supplier Onboarding Brief in the Valyu platform. It takes four inputs and requests a cited procurement report plus a Word document.
  • Use {variable} placeholders in the prompt. The platform detects them and creates input rows. Check their types and required flags before saving.
  • Applying a workflow prepares the research request; clicking Run starts the investigation. The API also has a preview endpoint that resolves the template without starting research or spending research credits.
  • Versions preserve the instructions, not the answers. We create version 1, launch a run, then save a changed report format as version 2. The TypeScript example pins version 1 explicitly.

Start with a research job your team repeats

A new supplier reaches your shortlist. Procurement needs to establish which entity it would buy from, whether the supplier makes the required product, and which reported issues deserve further investigation. Finance, legal and engineering may each need to answer a different question before the purchase proceeds.

The supplier changes, but the brief often does not. You still want the company identity, product fit, operating footprint, supporting evidence and outstanding questions in a familiar format.

We will turn that brief into Supplier Onboarding Brief, a private workflow belonging to our organisation. For the first run, our inputs are:

Input Example value
Supplier Schneider Electric
Country France
Product Industrial automation components
Review date 2026-10-13

The output should help the team prepare its procurement review and request missing information from the supplier. It should separate reported facts from analysis and make the supporting sources easy to inspect.

In Day 11, we ran ten prebuilt research workflows. Today we will build one around our own questions, then run the saved template from TypeScript.

What is a DeepResearch workflow?

A Valyu DeepResearch workflow is a saved, versioned research template with inputs you fill in at run time. It can contain a prompt, research strategy, report instructions, typed variables, deliverables, tools and a recommended research mode. Running it creates a normal asynchronous DeepResearch task.

Here is how the pieces apply to our supplier review:

Piece What it does in this example
Prompt Asks for the supplier's identity, product fit, relevant issues and unanswered procurement questions
Variables Supply the supplier name, country, product and review date
Research strategy Directs the investigation toward company disclosures, product pages, regulator publications and dated reporting
Report format Defines five sections, including an evidence table and questions for the supplier
Deliverable Requests a Word procurement brief
Tools Enables code execution for the Word file
Version Identifies the stored instructions used for a run

Valyu-curated workflows are read-only. Custom workflows are private to your organisation, and you can create and version them. See the Workflows guide for the current API reference and limits.

Step 1: Open Workflows and create a new template

Sign in to the Valyu platform and open Workflows from the sidebar. Click New workflow at the top-right.

The page separates Your org's workflows from Valyu workflows. We will create an organisation workflow so we can edit our research instructions.

Valyu Workflows page showing the New workflow button and an overview of typed parameters, deliverables, versioning and API execution

Open the workflow library and choose New workflow. The remaining steps use the actual creation form.

Step 2: Name the workflow after its output

Under Identity, enter:

Field Value
Title Supplier Onboarding Brief
Description A cited supplier review with evidence and open procurement questions.

The form shows the generated URL slug beside the title. In this walkthrough it is supplier-onboarding-brief. That slug is also the workflow ID we will use in the API example.

New workflow form with Supplier Onboarding Brief as the title, its generated supplier-onboarding-brief slug and a short description of the output

Use a name colleagues can recognise when choosing a workflow. Check the generated slug before wiring it into code.

Step 3: Write the research brief, strategy and report instructions

The Template section contains three fields. Keep their jobs distinct: the prompt states the assignment, the strategy describes how to investigate it, and the report instructions describe what the team should receive.

Prompt: what the researcher needs to find out

Paste this into Prompt:

Prepare an onboarding research brief for {supplier}, based in {country}, as a potential supplier of {product}. Use {review_date} as the review cut-off: separate facts published by that date from any later information. Establish the correct legal entity and product fit. Identify publicly reported operational, financial, regulatory and supply-chain issues relevant to the proposed purchase. Cite the evidence for each finding, distinguish reported facts from analysis, and list what procurement must confirm directly with the supplier.
Enter fullscreen mode Exit fullscreen mode

Notice the four placeholders: {supplier}, {country}, {product} and {review_date}. Those are the values we want to change between reviews.

Research strategy: where to look and what to check

Paste this into Research strategy:

Start with the supplier's official company and product pages, annual reports and regulatory disclosures. Use relevant government and regulator publications for specific issues, then dated reputable reporting for recent developments. Check entity names, reporting dates and geography before connecting a finding to this supplier. Preserve conflicting evidence and missing information. A missing search result is not confirmation that a risk does not exist.
Enter fullscreen mode Exit fullscreen mode

This gives the investigator concrete work to do. A news item about a subsidiary in another country needs an entity and relevance check before it belongs in the procurement brief.

Source priorities are research instructions, not an enforced allowlist. If your application must restrict searches to particular datasets or domains, use request-level search configuration. Likewise, a review date in the prompt does not create a historical snapshot of the underlying data. The DeepResearch search configuration guide explains the available filters.

Report format: what the team needs for its next action

Paste this into Report format instructions:

Return a concise procurement brief with five sections: 1. Supplier identity and product fit. 2. Operating footprint and reported supply dependencies. 3. Evidence table with finding, source URL, source date, relevance to the purchase and next verification action. 4. Conflicting or missing information. 5. Questions to send to the supplier before the procurement review. Keep recommendations separate from cited facts.
Enter fullscreen mode Exit fullscreen mode

An evidence table is useful because the next person can open the source, check the claim and decide what still needs a direct answer from the supplier.

Valyu workflow template filled with a supplier-research prompt, its four variable placeholders, a research strategy and procurement-report instructions

The prompt defines the assignment; the strategy guides the investigation; the report instructions make the result useful at the procurement meeting.

Step 4: Check the automatically detected variables

Scroll to Variables. In the session shown here, the platform created four rows from the placeholders in our prompt. Leave the first three as text and change review_date to date. Keep all four marked required.

Key Type Required Why it belongs in the brief
supplier text Yes Identifies the company being reviewed
country text Yes Helps distinguish the intended entity and operating context
product text Yes Connects the findings to the proposed purchase
review_date date Yes Supplies the review cut-off requested in the prompt

The keys must match the placeholders exactly. {review_date} needs a variable named review_date, not date or reviewDate.

The form also has Add variable. For this example, the four detected rows are enough.

Variables section showing supplier, country and product as required text inputs, and review_date as a required date input

Check the keys and types before saving. These rows become the input fields people complete when they use the workflow.

Step 5: Choose the mode and requested files

Under Settings, keep Recommended mode as Standard and Output format as Markdown report. This gives us a report to review in the platform.

We also want an editable document for the procurement team:

  1. Under Deliverables, click Add deliverable.
  2. Select DOCX.
  3. Enter the description below.
  4. Under Tools, enable Code execution. 
A Word procurement brief for {supplier} with the five report sections, cited source links, an evidence table and questions for the supplier.
Enter fullscreen mode Exit fullscreen mode

Word, Excel and PowerPoint generation require code execution. The Markdown research report and the requested Word file are separate outputs; check both when the task finishes.

For this example, leave Charts, Screenshots and Browser use off. Under Vertical, select Supply Chain. Enter Initial supplier-onboarding template. in the changelog field, then click Create workflow.

Workflow form configured with a DOCX procurement brief, code execution enabled, Supply Chain as the vertical and an initial-version changelog

Ask for the document the team needs, and enable the tool required to generate it. The vertical helps organise the template in the workflow library.

Step 6: Confirm that version 1 was saved

Back in the library, find Supplier Onboarding Brief under Your org's workflows. The saved row in our session shows:

  • Slug: supplier-onboarding-brief
  • Vertical: supply-chain
  • Version: v1
  • Mode: STANDARD

The row provides Slug, Run, an edit control and a delete control. We will use Run next.

Saved Supplier Onboarding Brief workflow in the organisation library, showing its slug, supply-chain vertical, version 1, Standard mode and Run action

Saving creates the reusable template. It does not start the supplier investigation.

Step 7: Fill the inputs and inspect what will be applied

Click Run beside the saved workflow. The platform opens the DeepResearch playground with a Research workflows dialog.

Fill in:

Supplier: Schneider Electric
Country: France
Product: Industrial automation components
Review date: 2026-10-13
Enter fullscreen mode Exit fullscreen mode

The dialog shows What will get pre-filled, including the research mode, strategy, report format and Word deliverable. Review those settings, then click Use workflow.

Research workflows dialog with Schneider Electric, France, industrial automation components and the review date entered, ready to use the Supplier Onboarding Brief

The changing values are now separate from the stored brief. For the next supplier, fill different values into these same fields.

Step 8: Check the resolved brief and start research

The playground now contains the prompt with the placeholders replaced. Its controls show Standard and Deliverables 1 in our example.

Check the supplier, country, product and date before clicking Run. This is the point at which we start a research task.

DeepResearch playground with the supplier inputs inserted into the research question, Standard mode selected, one deliverable configured and the Run button

Use workflow loads the brief into the playground. Run starts the investigation.

In the actual session, the task entered Running — Standard and displayed an activity feed. It began researching official company reports, product pages and relevant regulatory reporting. DeepResearch is asynchronous, so the creation response or the running screen is not the finished report.

The actual supplier research task running in Standard mode, with its query and activity feed visible

The activity feed lets you follow the investigation while it runs. Wait for completion before treating the report as ready.

What the actual run returned

The task completed with a cited report and a completed DOCX deliverable. The report included the five requested sections: supplier identity and product fit, operating footprint, an evidence table, conflicting or missing information, and questions for the supplier.

Completed Standard research task showing the generated supplier-onboarding report, source citation chips, section navigation and the requested DOCX deliverable

Actual output from the workflow run. Use the citation chips and section navigation to inspect the report, and open the DOCX deliverable for its download controls.

One useful part of the result was an unanswered contracting question: the brief left the entity that would sign and invoice the purchase unconfirmed. That gives procurement a specific next action—request the contracting entity's legal name and registration details directly, rather than assume the listed parent company is the counterparty.

Note: This is the DeepResearch Report it produced. You can check it out and examine it yourself.

Before using this report at the procurement meeting, check:

  • Does each source refer to the intended supplier entity and relevant product?
  • Is the source date compatible with the review cut-off?
  • Does the cited passage support the finding, or only mention a related topic?
  • Are missing information and conflicting reports visible?
  • Which questions should go to the supplier, finance, legal or engineering before the purchasing review?

The useful outcome is a research brief and a focused list of verification questions the team can act on.

Step 9: Improve the template and save a new version

Suppose procurement likes the brief but wants each outstanding question assigned to an internal team. Return to Workflows and click the edit control beside Supplier Onboarding Brief.

Append this sentence to Report format instructions:

For each verification question, name the internal team that should answer it: procurement, finance, legal or engineering.
Enter fullscreen mode Exit fullscreen mode

In Changelog, enter:

Added an internal owner for each supplier-verification question.
Enter fullscreen mode Exit fullscreen mode

Click Save changes. In our session, this created version 2. We made the edit after launching the first run from version 1.

Edit workflow form with a changelog explaining that an internal owner was added for each supplier-verification question, ready to save changes

Supplier Onboarding Brief in the organisation library after the edit, now showing version 2

A new version records the changed research instructions. The API lets you request a specific version when your application needs to keep using an earlier brief.

According to the versioning documentation, template versions are immutable, and publishing a new version requires a changelog. Pinning a version preserves the configuration. Live sources, findings and generated wording can still change between runs.

Run the saved workflow from TypeScript

The same organisation workflow can be used from your application. You need a Valyu API key belonging to the organisation that owns it.

In a Node.js project using Node 22 or later, install:

npm install valyu-js@2.10.1
npm install --save-dev tsx
Enter fullscreen mode Exit fullscreen mode

Set VALYU_API_KEY privately in your environment. Save the following as run-workflow.mts.

This example loads and previews version 1. By default, it stops after the preview. Add --run to start a new research task.

import { writeFile } from 'node:fs/promises';
import { pathToFileURL } from 'node:url';
import { Valyu } from 'valyu-js';

export async function runWorkflow(client: Valyu, execute = false) {
  const slug = 'supplier-onboarding-brief';
  const version = 1;
  const workflowParams = {
    supplier: 'Schneider Electric',
    country: 'France',
    product: 'Industrial automation components',
    review_date: '2026-10-13',
  };
  const detail = await client.workflows.get(slug, version);
  if (!detail.success || detail.workflow?.version !== version) {
    throw new Error('Could not load version 1. Check the workflow slug and API key organisation.');
  }
  const preview = await client.workflows.preview(slug, {
    workflowParams, workflowVersion: version,
  });
  if (!preview.success || !preview.resolved?.input ||
      preview.workflow?.slug !== slug || preview.workflow.version !== version) {
    throw new Error('Preview failed or resolved a different version. Check the required inputs.');
  }
  console.log(JSON.stringify({ workflow: preview.workflow, resolved: preview.resolved }, null, 2));
  if (!execute) return { preview };
  const task = await client.deepresearch.create({
    workflowId: slug, workflowParams, workflowVersion: version,
    mode: 'standard',
  });
  if (!task.success || !task.deepresearch_id) {
    throw new Error('Could not create a research task. Check credits and source access.');
  }
  console.log(`Task ID: ${task.deepresearch_id}`);
  const result = await client.deepresearch.wait(task.deepresearch_id, {
    pollInterval: 10_000, maxWaitTime: 30 * 60 * 1000,
  });
  if (!result.success || result.status !== 'completed' || typeof result.output !== 'string') {
    throw new Error(`Report not completed. Inspect task ${task.deepresearch_id} before starting another run.`);
  }
  return { preview, taskId: task.deepresearch_id, result };
}

async function main() {
  const key = process.env.VALYU_API_KEY;
  if (!key) throw new Error('Set VALYU_API_KEY for the organisation that owns this workflow.');
  const output = await runWorkflow(new Valyu(key), process.argv.includes('--run'));
  if (output.result) {
    await writeFile('supplier-brief.md', String(output.result.output));
    await writeFile('supplier-result.json', JSON.stringify(output.result, null, 2));
    console.log('Saved supplier-brief.md and supplier-result.json. Check each deliverable status in the result.');
  }
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main().catch(error => { console.error(error instanceof Error ? error.message : 'Workflow request failed.'); process.exitCode = 1; });
}
Enter fullscreen mode Exit fullscreen mode

Preview first:

npx tsx run-workflow.mts
Enter fullscreen mode Exit fullscreen mode

The preview endpoint resolves the template without starting research or spending research credits. Inspect the resolved question, strategy, report instructions and deliverables.

To start a new, billed research task:

npx tsx run-workflow.mts --run
Enter fullscreen mode Exit fullscreen mode

The script prints the task ID before waiting, then saves the completed report and response. If waiting fails or times out, inspect that task rather than immediately launching another one. The Word file has its own deliverable status in the result.

In deepresearch.create(), use workflowId, workflowParams and, when desired, workflowVersion. Do not also send a freeform query, researchStrategy or reportFormat in that request. The workflow supplies those instructions. See the per-run override rules if you need to change supported settings for one run.

Verification: the platform walkthrough created the workflow, completed a Standard task with a DOCX deliverable and saved version 2. The TypeScript example passed strict compilation and seven local SDK/HTTP-fixture tests, including version pinning, preview-only execution and failure paths that do not resubmit a task. The fixture tests did not perform an additional paid research run.

Troubleshooting a custom DeepResearch workflow

Problem What to check
A placeholder is not filled Confirm that its key matches a declared variable and that the run supplies that key
A date or number is rejected Check the variable type and supplied value; use an ISO date such as 2026-10-13 for this example
The API cannot find your private workflow Check the slug and whether the API key belongs to the organisation that owns it
A new version cannot be saved Supply a changelog describing the template change
Word, Excel or PowerPoint generation is unavailable Enable code execution and check the requested deliverable's status
Workflow and freeform fields conflict Remove the freeform query/strategy/report-format fields from the workflow-run request
Results differ between two runs of the same version Compare the sources and their dates; a fixed template does not freeze live evidence
A task is still running after your script stops waiting Keep the task ID and check its status before deciding whether another run is needed

FAQ

Can I create a custom DeepResearch workflow without writing code?

Yes. In the Valyu platform, open Workflows, choose New workflow, enter the research template, check its variables and settings, then save it. This walkthrough shows the creation, launch and version-editing steps through the interface.

What is the difference between a workflow and a one-off research prompt?

A one-off prompt describes one investigation. A workflow stores a reusable research specification with input fields, report instructions and other defaults. Fill in new inputs to run that specification for another assignment.

Are custom workflows public?

Custom workflows belong to your organisation. Valyu-curated workflows are available to organisations as read-only templates. Use an API key from the owning organisation when calling a private workflow.

Does previewing a workflow start research?

The API preview endpoint resolves the template without creating a research task or spending research credits. In the platform walkthrough, Use workflow prepared the playground request; clicking Run launched the task.

Can a workflow produce a Word document or spreadsheet?

Yes. Specify the deliverable and enable code execution for DOCX, XLSX or PPTX generation. Our example requests a Markdown report and an additional Word procurement brief. Check the report and the file's completion status separately.

Does pinning a version guarantee the same answer?

No. A pinned version preserves the template instructions. Source records, available evidence and generated results can change. Save the task ID, inputs and returned evidence when comparing runs.

Build the brief your team already uses

Choose a recurring research assignment with clear inputs and an output someone will review. Write the questions and evidence requirements once, create the variable fields, and run the template on a real example. Use the first result to improve the brief and record the change in a new version.

Start in Valyu Workflows. If your team needs a starting template first, the Day 11 workflow guide covers ten prebuilt options.

Top comments (0)