DeepResearch human-in-the-loop in TypeScript

Quick start

Enable a plan-review checkpoint and collect a real response before continuing. This Node.js example approves the plan when the user presses Enter, or submits the requested changes.

import { createInterface } from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { Valyu } from "valyu-js";

const client = new Valyu();
const task = await client.deepresearch.create({
  query: "Compare battery recycling companies operating in Europe",
  mode: "standard",
  hitl: { planReview: true },
});
if (!task.success || !task.deepresearch_id) throw new Error(task.error);

const terminal = createInterface({ input: stdin, output: stdout });
try {
  const result = await client.deepresearch.wait(task.deepresearch_id, {
    onInteraction: async (interaction) => {
      if (interaction.type !== "plan_review") return null;
      console.log(interaction.data);
      const changes = (await terminal.question("Enter changes, or press Enter to approve: ")).trim();
      return changes
        ? { approved: false, modifications: changes }
        : { approved: true };
    },
  });
  if (result.status === "completed") console.log(result.output);
  else console.error(result.status, result.error);
} finally {
  terminal.close();
}

In a web application, persist the task and interaction IDs, show the checkpoint to the user, then call respond() when they submit their decision. Returning null from a callback leaves the checkpoint unanswered; it does not approve or dismiss it.

Checkpoints

Checkpoint	Phase	When it fires
`planningQuestions`	Pre-research	Before research - clarifying questions for the user
`planReview`	Pre-research	After planning - review the research plan
`sourceReview`	Post-research	After research - filter sources by domain
`outlineReview`	Post-research	After source review - review the report outline

Checkpoints fire in order; only enabled ones fire.

Reference

Manual polling and respond()

If you’d rather drive the loop yourself, poll status() and respond when status.status is awaiting_input or paused:

while (true) {
  const status = await client.deepresearch.status(taskId);

  if ((status.status === "awaiting_input" || status.status === "paused") && status.interaction) {
    const { interaction_id } = status.interaction;
    await client.deepresearch.respond(taskId, interaction_id, buildResponse(status.interaction));
  } else if (["completed", "failed", "cancelled"].includes(status.status!)) {
    break;
  }

  await new Promise((r) => setTimeout(r, 5000));
}

Status	Meaning
`"awaiting_input"`	Checkpoint active, container held, fast resume
`"paused"`	Checkpoint timed out (5 min), state saved, respond anytime
`"running"`	Research or writing in progress
`"queued"`	Re-enqueued after responding to a paused task

respond() returns DeepResearchRespondResponse with success, status ("running" or "queued"), deepresearch_id, error.

Checkpoint response shapes

Each checkpoint expects a specific response object:

// planning_questions - interaction.data has { questions: [{ question, context }] }
{ answers: [{ question: "What regions?", answer: "North America and EU" }] }

// plan_review - interaction.data has { plan, estimated_steps, research_areas }
{ approved: true }
{ approved: false, modifications: "Focus more on supply chain analysis" }

// source_review - interaction.data has { domains: [{ domain, ai_recommendation }], total_sources }
{ included_domains: ["sec.gov"], excluded_domains: ["example.com"] }
// Domains not listed fall back to the AI recommendation; pass [] to accept all recommendations.

// outline_review - interaction.data has { outline, sections }
{ approved: true }
{ approved: false, modifications: "Add a regulatory risks section" }

Typed helpers

await client.deepresearch.respondPlanningQuestions(taskId, interactionId, [
  { question: "What regions?", answer: "North America and EU" },
]);
await client.deepresearch.approvePlan(taskId, interactionId, "...");     // omit string to approve
await client.deepresearch.respondSourceReview(taskId, interactionId, {
  includedDomains: ["sec.gov"], excludedDomains: ["example.com"],
});
await client.deepresearch.approveOutline(taskId, interactionId, "...");  // omit to approve

HITL history and types

After checkpoints complete, status.hitl_history records each interaction (type, auto_continued, created_at, responded_at, response):

for (const entry of (await client.deepresearch.status(taskId)).hitl_history ?? []) {
  console.log(entry.type, "auto_continued:", entry.auto_continued);
}

Type	Description
`HitlConfig`	Config with 4 optional boolean fields
`InteractionType`	`"planning_questions"` \| `"plan_review"` \| `"source_review"` \| `"outline_review"`
`Interaction`	Checkpoint payload: `interaction_id`, `type`, `data`, `created_at`, `timeout_ms`
`InteractionHistoryEntry`	Completed checkpoint record
`DeepResearchRespondResponse`	Response from `respond()`

Start here

APIs

Finance workflows

Sciences workflows

Build and connect

Comparisons

TypeScript SDK: DeepResearch human review

Quick start

Checkpoints

Reference

​Quick start

​Checkpoints

​Reference

Quick start

Checkpoints

Reference