Human-in-the-Loop (HITL)

HITL adds optional checkpoints that pause a DeepResearch task at key decision points so a user can review and steer the research. Enable any combination of four checkpoints; only the ones you enable fire.

HITL is for individual tasks only. It is not available for batch requests.

Checkpoints

Checkpoint	Phase	What happens
`planning_questions`	Pre-research	Agent asks clarifying questions before researching
`plan_review`	Pre-research	User reviews the research plan
`source_review`	Post-research	User filters sources by domain
`outline_review`	Post-research	User reviews the report outline

Each pause sets the task status to awaiting_input. If you don’t respond within 5 minutes it becomes paused (state saved) - you can still respond anytime to resume; the task re-enqueues at highest priority with a brief cold-start delay.

Quick start

The simplest approach: pass an on_interaction callback to wait() and let the SDK handle each checkpoint as it fires.

from valyu import Valyu

client = Valyu()

task = client.deepresearch.create(
    query="Analyze the competitive landscape of AI chip manufacturers",
    mode="heavy",
    hitl={"plan_review": True, "source_review": True},
)

def handle_interaction(interaction):
    if interaction.type in ("plan_review", "outline_review"):
        return {"approved": True}
    if interaction.type == "source_review":
        return {"included_domains": [], "excluded_domains": []}
    if interaction.type == "planning_questions":
        return {
            "answers": [
                {"question": q["question"], "answer": "Use your best judgment"}
                for q in interaction.data["questions"]
            ]
        }
    return None

result = client.deepresearch.wait(
    task.deepresearch_id,
    on_interaction=handle_interaction,
)
print(result.output)

import Valyu from "valyu-js";

const client = new Valyu();

const task = await client.deepresearch.create({
  query: "Analyze the competitive landscape of AI chip manufacturers",
  mode: "heavy",
  hitl: { planReview: true, sourceReview: true },
});

const result = await client.deepresearch.wait(task.deepresearch_id!, {
  onInteraction: async (interaction) => {
    if (interaction.type === "plan_review" || interaction.type === "outline_review") {
      return { approved: true };
    }
    if (interaction.type === "source_review") {
      return { included_domains: [], excluded_domains: [] };
    }
    if (interaction.type === "planning_questions") {
      return {
        answers: interaction.data.questions.map((q: any) => ({
          question: q.question,
          answer: "Use your best judgment",
        })),
      };
    }
    return null;
  },
});

console.log(result.output);

# 1. Create task with HITL
curl -X POST https://api.valyu.ai/v1/deepresearch/tasks \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VALYU_API_KEY" \
  -d '{
    "query": "Analyze the competitive landscape of AI chip manufacturers",
    "mode": "heavy",
    "hitl": { "planning_questions": true, "plan_review": true }
  }'

# 2. Poll status until "awaiting_input"
curl https://api.valyu.ai/v1/deepresearch/tasks/{id}/status \
  -H "x-api-key: $VALYU_API_KEY"

# 3. Respond to the checkpoint
curl -X POST https://api.valyu.ai/v1/deepresearch/tasks/{id}/respond \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VALYU_API_KEY" \
  -d '{
    "interaction_id": "int_abc123",
    "response": {
      "answers": [{"question": "What geographic regions?", "answer": "North America and EU"}]
    }
  }'

Both SDKs also ship type-safe helpers: respond_planning_questions() / respondPlanningQuestions(), approve_plan() / approvePlan(), respond_source_review() / respondSourceReview(), and approve_outline() / approveOutline(). See the Python and TypeScript SDK references.

Where checkpoints fire

Query analysis

The agent analyzes the query.

planning_questions

Pause: clarifying questions before research starts. You answer to set scope.

plan_review

Pause: review the research plan. Approve or request changes.

Research execution

The agent searches and reads sources.

source_review

Pause: review sources grouped by domain. Include or exclude domains.

outline_review

Pause: review the report outline. Approve or request structural changes.

Report writing

The agent writes the final report and the task completes.

Checkpoint response shapes

When status is awaiting_input, status.interaction.data holds the checkpoint payload and you reply with a matching response.

planning_questions

The agent asks questions; you answer them.

// interaction.data
{ "questions": [
  { "question": "What geographic regions should the research focus on?" },
  { "question": "Are there specific competitors you want analyzed?" }
] }

// response
{ "answers": [
  { "question": "What geographic regions?", "answer": "North America and EU" },
  { "question": "Specific competitors?", "answer": "Tesla, BYD, Rivian" }
] }

answers is required: an array of { question, answer } strings.

plan_review and outline_review

Both share the same response shape - approve, or reject with free-text guidance.

// approve
{ "approved": true }

// request modifications
{ "approved": false, "modifications": "Add a regulatory risks section" }

approved (boolean) is required; modifications (string) is optional free-text guidance for the model. interaction.data contains the plan / outline and section breakdown for you to display.

source_review

interaction.data lists sources grouped by domain with a source_count, avg_relevance_score, and an ai_recommendation of include or exclude. You reply with explicit include/exclude lists.

{
  "included_domains": ["sec.gov", "plos.org"],
  "excluded_domains": ["example.com"]
}

Both arrays are required but may be empty. Domains you don’t list fall back to the AI recommendation.

Manual polling and the respond endpoint

If you poll yourself instead of using wait(), watch for awaiting_input (or paused), then POST your response:

POST /v1/deepresearch/tasks/:id/respond
{ "interaction_id": "<must match status.interaction.interaction_id>", "response": { ... } }

Code	Meaning
`200`	Accepted - `{ "success": true, "status": "running" \| "queued" }`
`400`	Validation error (bad response shape)
`409`	Wrong status or `interaction_id` mismatch

Status values and interaction fields

Status	Meaning
`awaiting_input`	Checkpoint active, container held, fast resume on response
`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

When HITL is enabled, the status response also carries hitl_config (mirrors the request), interaction (present while awaiting_input/paused), and hitl_history (one entry per completed checkpoint with interaction_id, type, created_at, responded_at, auto_continued, and response).

Best practices

Poll faster around checkpoints - 2-3s when expecting input, 5-10s during research phases.
Handle both awaiting_input and paused - the UX is identical, only resume speed differs.
Enable selectively - each checkpoint adds latency equal to the user’s response time.
Use heavy or max modes - HITL pays off when the research is substantial enough to benefit from guidance.

Getting Started

Guides & Best Practices

Use Cases

Core Concepts

Compare

Account & Pricing

Other

Checkpoints

Quick start

Where checkpoints fire

Checkpoint response shapes

Manual polling and the respond endpoint

Best practices

​Checkpoints

​Quick start

​Where checkpoints fire

​Checkpoint response shapes

​Manual polling and the respond endpoint

​Best practices

Checkpoints

Quick start

Where checkpoints fire

Checkpoint response shapes

Manual polling and the respond endpoint

Best practices