Deep Researcher Research

Deep Researcher Agent Research Skill

When to Use This Skill

Use this skill to call a locally running NVIDIA Deep Researcher Agent Blueprint server through the helper script at scripts/deep_researcher.py.

Use this skill for research-shaped requests, including:

• "deep research on ..."
• "Deep Researcher Agent research ..."
• "research ..."
• "use Deep Researcher Agent to answer ..."
• "ask Deep Researcher Agent about ..."

Do not use this skill for install, deploy, start, stop, UI, CLI, Docker, Helm, or troubleshooting requests. Those belong to deep-researcher-deploy.

Prerequisites

Users need:

• Python 3.11+ available as python3.
• A reachable local or self-hosted Deep Researcher Agent Blueprint backend.
• DEEP_RESEARCHER_SERVER_URL set when the backend is not running at http://localhost:8000; non-local values must be trusted by the user before any query is sent.
• A backend configured with authentication disabled for this public helper, or a separate authenticated Deep Researcher Agent skill for authenticated environments.
• Network access from the local machine to the Deep Researcher Agent backend URL.
• Credentials configured in the backend environment, not in this skill. This public helper does not collect or manage API keys.

The helper script has no third-party Python package dependencies; it uses Python standard-library HTTP modules.

Workflow

1. Resolve the target backend URL.
2. Run health before sending research requests.
3. If no backend is reachable, ask for a backend URL or hand off to deep-researcher-deploy.
4. Before sending any user query, state the exact Deep Researcher Agent backend URL that will receive it. For non-local URLs, continue only if the user has explicitly confirmed that URL is trusted in the current conversation.
5. Poll asynchronous deep research jobs when Deep Researcher Agent returns a job ID.
6. Present returned reports with citations and source URLs intact.
7. Stop on failed jobs and show the returned error; do not retry automatically.
8. After presenting a report, support follow-up: answer questions about it (ask) or run a refined research pass (redo) using the same commands.

Step 1 - Resolve the backend

Use DEEP_RESEARCHER_SERVER_URL when set. Otherwise try the default local backend:

python3 $SKILL_DIR/scripts/deep_researcher.py health

Expected output: JSON from a reachable Deep Researcher Agent health endpoint.

If health fails and no explicit DEEP_RESEARCHER_SERVER_URL was set, ask:

I do not see a reachable local Deep Researcher Agent backend. Do you already have an Deep Researcher Agent backend URL you want to use, or should I deploy a local Skill backend?

• If the user provides a URL, set DEEP_RESEARCHER_SERVER_URL for subsequent helper calls and rerun health.
• If the user wants local deployment, hand off to deep-researcher-deploy and preserve the original research request.
• If a reachable backend returns 401 or 403, stop and explain that this public skill does not manage authentication. Ask the user to use an authenticated Deep Researcher Agent skill or configure authentication for their environment.
• If health succeeds but /chat or /v1/jobs/async/agents fails, report that the backend is reachable but not compatible with this public research flow, then offer to run deep-researcher-deploy validation.

Step 2 - Send the routed research request

Before sending the request, state the resolved endpoint:

I will send this query to <DEEP_RESEARCHER_SERVER_URL>. Make sure this endpoint is trusted before sending sensitive information.

Do not send credentials, cookies, bearer tokens, or secret values through the query text.

Run:

python3 $SKILL_DIR/scripts/deep_researcher.py chat "<USER_QUESTION>"

Expected output:

• A normal JSON response for shallow or direct answers.
• Or structured JSON containing {"status": "deep_research_running", "job_id": "<JOB_ID>"} for asynchronous deep research.

If the response is normal JSON, present the result immediately. Do not force polling when there is no job_id.

Step 3 - Poll asynchronous jobs

If the response includes deep_research_running, extract the job_id and poll with the same absolute script path:

python3 $SKILL_DIR/scripts/deep_researcher.py research_poll <JOB_ID>

Expected output: the final report JSON when the job completes successfully.

Use the runtime's non-blocking or background execution mechanism when available. If the chosen execution method requires escalated permissions, request explicit user approval first and explain why. Tell the user that deep research is running in the background.

Step 4 - Resume after interruptions

If polling is interrupted, the job continues server-side. Resume with:

python3 $SKILL_DIR/scripts/deep_researcher.py status <JOB_ID>
python3 $SKILL_DIR/scripts/deep_researcher.py report <JOB_ID>
python3 $SKILL_DIR/scripts/deep_researcher.py research_poll <JOB_ID>

Use status to inspect job status and saved artifacts. Use report when the job has already finished and you only need the final output. Use research_poll to keep waiting for completion.

The final report may reference generated artifacts (charts, CSVs) as artifact://<id> links. To materialize them as local files, run python3 $SKILL_DIR/scripts/deep_researcher.py artifacts <JOB_ID> --download-dir ./deep-researcher-artifacts; it downloads each artifact and prints the local path. Do not expect base64 image data in the report itself.

For a self-contained, shareable report, run python3 $SKILL_DIR/scripts/deep_researcher.py report <JOB_ID> --out-dir ./my-report. It writes report.md plus an artifacts/ folder and rewrites each artifact://<id> link to the matching local file, so the report renders (charts and all) in any markdown viewer without a running backend.

Step 5 - Present the report

When research_poll completes successfully, fetch and present the full report. Keep citations and source URLs intact. If the job status is failed, failure, or cancelled, show the error from the status response and ask whether the user wants to retry with a narrower query or different approach.

Step 6 - Follow up: ask about, edit, or redo a report

After a report is presented, the user often wants to go deeper or adjust scope. Reuse the existing backend flow — the same auth boundary, polling, and report retrieval from Steps 1-5 apply; there is no separate follow-up endpoint.

Ask — a follow-up question about a report already in hand:

• For a question answerable from the report you already have, answer directly from its content and citations; do not call the backend again.

• For a question that needs new investigation, send a fresh request that carries the needed context from the prior question and report into the new query text, then present the new result:

  python3 $SKILL_DIR/scripts/deep_researcher.py chat "<FOLLOW_UP_QUESTION> (context: <PRIOR_TOPIC>)"

  If this returns a deep_research_running job ID, poll it with research_poll exactly as in Step 3.

Edit — rewrite a report with cosmetic changes. This skill only has access to the data used to generate the initial report. No tools are available:

python3 $SKILL_DIR/scripts/deep_researcher.py report_edit <JOB_ID> "<EDIT_INSTRUCTIONS>"

Redo — re-run research with adjusted scope (a narrower query, a corrected question, or a different depth):

python3 $SKILL_DIR/scripts/deep_researcher.py research "<REFINED_QUERY>" [agent_type]

• Choose agent_type to match the desired depth (for example a deep agent for a thorough pass, or shallow_researcher for a quick one); list options with agents if unsure.
• Treat a redo as a new job: state the target endpoint again before sending (Step 2), then poll and present as in Steps 3-5.

Do not send credentials or secret values in follow-up query text, and keep citations and source URLs intact in every follow-up answer.

Version Compatibility

IMPORTANT: This skill is designed for NVIDIA Deep Researcher Agent Blueprint version 2.2.0.

Semantic Versioning Compatibility Rules:

Skill version: X.Y.Z
Blueprint or endpoint version: A.B.C

Compatible IF:
1. A == X (Major versions MUST match)
2. B >= Y (Minor version must be equal or greater)
3. C can be anything (Patch version does not affect compatibility)

Examples:

• Skill version 2.2.0 is compatible with Blueprint version 2.2.0.
• Skill version 2.2.0 is compatible with Blueprint version 2.3.0.
• Skill version 2.2.0 is compatible with Blueprint version 2.2.5.
• Skill version 2.2.0 is not compatible with Blueprint version 3.0.0.
• Skill version 2.2.0 is not compatible with Blueprint version 2.1.0.

If your Blueprint version is not compatible:

1. Check for an updated skill version matching your Blueprint version.
2. Use a Blueprint version compatible with this skill.
3. Proceed with caution only when the user accepts the compatibility risk; API routes or response shapes may have changed.