Human-in-the-Loop (HITL)

Pause deep research at key decision points for user review and guidance

DeepResearch tasks support optional human-in-the-loop checkpoints that pause execution at key decision points, allowing users to review and guide the research process.

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

Available checkpoints

Enable any combination of four checkpoints that fire in order during the research lifecycle:

Checkpoint	Phase	When it fires
planning_questions	Pre-research	Before research begins — the agent asks clarifying questions
plan_review	Pre-research	After planning — user reviews the research plan
source_review	Post-research	After research — user filters sources by domain
outline_review	Post-research	After source filtering — user reviews the report outline

Quick start

Python

from valyu import Valyu

client = Valyu()

# Create a task with HITL checkpoints
task = client.deepresearch.create(
    query="Analyze the competitive landscape of AI chip manufacturers",
    mode="heavy",
    hitl={
        "planning_questions": True,
        "plan_review": True,
        "source_review": True,
        "outline_review": True,
    },
)

task_id = task.deepresearch_id

# Poll until a checkpoint fires or task completes
import time

while True:
    status = client.deepresearch.status(task_id)

    if status.status == "awaiting_input":
        interaction = status.interaction
        print(f"Checkpoint: {interaction.type}")
        print(f"Data: {interaction.data}")

        # Build your response based on the checkpoint type
        if interaction.type == "planning_questions":
            response = {
                "answers": [
                    {"question": q["question"], "answer": "Focus on NVIDIA, AMD, and Intel"}
                    for q in interaction.data["questions"]
                ]
            }
        elif interaction.type in ("plan_review", "outline_review"):
            response = {"approved": True}
        elif interaction.type == "source_review":
            response = {
                "included_domains": ["sec.gov", "plos.org"],
                "excluded_domains": [],
            }

        # Respond to the checkpoint
        client.deepresearch.respond(
            task_id,
            interaction_id=interaction.interaction_id,
            response=response,
        )

    elif status.status in ("completed", "failed", "cancelled"):
        break

    time.sleep(5)

print(status.output)

How HITL fits into the research pipeline

Each checkpoint maps to a stage in the research process. Only enabled checkpoints fire — the rest are skipped automatically.

1. Query analysis

   The agent analyzes the query and prepares to research.

2. planning_questions checkpoint

   Pause: The agent asks clarifying questions before starting research. You provide answers to guide scope and focus.

3. Research planning

   The agent builds a research plan — areas to investigate, estimated steps, and methodology.

4. plan_review checkpoint

   Pause: You review the research plan. Approve it or request modifications (e.g., “focus more on supply chain”).

5. Research execution

   The agent searches, reads sources, and gathers information.

6. source_review checkpoint

   Pause: You review the sources grouped by domain. Include or exclude domains to control what goes into the report.

7. Outline generation

   The agent generates a structured outline for the report.

8. outline_review checkpoint

   Pause: You review the outline. Approve it or request structural changes (e.g., “add a regulatory risks section”).

9. Report writing

   The agent writes the final report using approved sources and outline.

10. Completed

    The report is ready. Retrieve it from the status response.

Each pause sets the task status to awaiting_input. If you don’t respond within 5 minutes, the status transitions to paused — but you can still respond at any time to resume.

Status values

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

Responding to a paused task still works — the task re-enqueues at highest priority. The only difference is a brief cold-start delay as the container restarts.

Checkpoint response shapes

Each checkpoint type expects a specific response format.

Planning questions

The agent asks clarifying questions before starting research.

Interaction data:

{
  "questions": [
    {
      "question": "What geographic regions should the research focus on?",
      "context": "The query mentions global markets — narrowing scope improves depth"
    },
    {
      "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" }
  ]
}

Field	Type	Required
answers	Array<{ question, answer }>	Yes
answers[].question	string	Yes
answers[].answer	string	Yes

Plan review

Review the research plan before execution.

Interaction data:

{
  "plan": "I'll research this topic by first examining...",
  "estimated_steps": 15,
  "research_areas": ["Market size analysis", "Competitive landscape", "Regulatory environment"]
}

Response (approve):

{ "approved": true }

Response (request modifications):

{
  "approved": false,
  "modifications": "Focus more on battery supply chains and less on historical context"
}

Field	Type	Required
approved	boolean	Yes
modifications	string	No — free-text guidance for the model

Source review

Filter sources by domain after the research phase.

Interaction data:

{
  "domains": [
    {
      "domain": "sec.gov",
      "source_count": 8,
      "avg_relevance_score": 0.87,
      "sources": [
        { "source_id": 1, "title": "SEC Filing: Tesla Annual Report", "url": "https://sec.gov/...", "relevance_score": 0.92 }
      ],
      "ai_recommendation": "include"
    },
    {
      "domain": "example.com",
      "source_count": 2,
      "avg_relevance_score": 0.31,
      "sources": [
        { "source_id": 14, "title": "...", "url": "https://example.com/...", "relevance_score": 0.31 }
      ],
      "ai_recommendation": "exclude"
    }
  ],
  "total_sources": 42
}

Response:

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

Field	Type	Required
included_domains	string[]	Yes (can be empty [] to accept AI recommendations)
excluded_domains	string[]	Yes (can be empty [])

Domains not listed in either array fall back to the AI recommendation.

Outline review

Review the report outline before writing begins.

Interaction data:

{
  "outline": "1. Introduction\n2. Market Analysis\n3. Competitive Landscape\n4. Conclusion",
  "sections": [
    { "title": "Introduction", "description": "Overview of the research topic", "estimated_length": "short" },
    { "title": "Market Analysis", "description": "Market size and growth analysis", "estimated_length": "long" },
    { "title": "Competitive Landscape", "description": "Key players and positioning", "estimated_length": "long" },
    { "title": "Conclusion", "description": "Summary and implications", "estimated_length": "short" }
  ]
}

Response (approve):

{ "approved": true }

Response (request modifications):

{
  "approved": false,
  "modifications": "Add a section on regulatory risks between Market Analysis and Competitive Landscape"
}

Field	Type	Required
approved	boolean	Yes
modifications	string	No — free-text guidance for the model

Respond endpoint

POST /v1/deepresearch/tasks/:id/respond

Headers:

Header	Value
x-api-key	Your API key
Content-Type	application/json

Body:

{
  "interaction_id": "string (must match task.interaction.interaction_id)",
  "response": { }
}

Response codes

Code	Meaning	Example
200	Accepted (hot path)	{ "success": true, "status": "running" }
200	Accepted (cold path)	{ "success": true, "status": "queued" }
400	Validation error	{ "error": "response.answers must be an array" }
409	Wrong status or ID mismatch	{ "error": "Cannot respond to task with status: running" }

Interaction fields on task status

When HITL is enabled, these additional fields appear on the task status response:

Field	Type	Present when
hitl_config	object	Always (mirrors the request hitl param)
interaction	object	Status is awaiting_input or paused
hitl_history	array	After any checkpoint completes

Interaction history entry

Each entry in hitl_history contains:

Field	Type	Description
interaction_id	string	Unique checkpoint ID
type	string	Checkpoint type
created_at	integer	When the checkpoint fired (ms)
responded_at	integer	When the user responded (ms) — absent if timed out
auto_continued	boolean	true if timed out, false if user responded
response	object	The user’s response — absent if timed out

Polling pattern

Standard HITL polling flow:

1. POST /v1/deepresearch/tasks          → { deepresearch_id }
2. GET  .../status                       → status: "running"
3. GET  .../status                       → status: "awaiting_input", interaction: { ... }
4. POST .../respond                      → { status: "running" }
5. GET  .../status                       → status: "running"
   ... (repeats for each enabled checkpoint)
6. GET  .../status                       → status: "completed"

If a checkpoint times out:

3. GET  .../status                       → status: "awaiting_input"
   ... (5 minutes pass)
4. GET  .../status                       → status: "paused"
   ... (user responds later)
5. POST .../respond                      → { status: "queued" }
6. GET  .../status                       → status: "running"

Using wait() with HITL

Instead of manual polling, use the wait() method with a HITL callback to handle checkpoints automatically:

Python

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}
    elif interaction.type == "source_review":
        return {"included_domains": [], "excluded_domains": []}
    elif 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)

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

Best practices

Poll frequently during checkpoints

Use a 2-3 second poll interval when expecting HITL checkpoints. Switch to standard intervals (5-10s) during research phases.

Handle both statuses

Always check for both awaiting_input and paused — the user experience is identical, only resume speed differs.

Enable selectively

Only enable checkpoints that add value for your use case. Each checkpoint adds latency equal to the user’s response time.

Use with heavy or max modes

HITL works best with heavy or max modes where the research is substantial enough to benefit from human guidance.