A small, open-source research loop for AI agents. It uses the OpenAI Responses API with web search to gather evidence across multiple bounded rounds, identify gaps, and produce a cited Markdown report.
中文说明 | Roadmap | Contributing
One-shot research prompts often stop too early, repeat weak sources, or hide uncertainty. This project explores a reproducible loop:
- Search broadly and prioritize primary or authoritative sources.
- Feed prior notes into the next round.
- Ask specifically for gaps, disagreements, and missing evidence.
- Stop at a configured round limit.
- Synthesize the collected notes into a structured report.
The current version is an early-stage Node.js reference implementation. It is intentionally small and explicit so that its prompts, limits, and evaluation methods can be inspected and improved.
- OpenAI Responses API integration
- Built-in web search for research rounds
- Configurable model, round limit, output-token limit, and report directory
- Cumulative token-usage reporting
- Markdown report generation
- Dependency-injected research core for offline automated tests
- The project is experimental and does not guarantee factual accuracy.
- Source links and claims still require human review.
- The current stopping rule is a fixed round limit, not semantic convergence detection.
- Token limits are applied per API request; a total monetary budget is not yet enforced.
- The test suite validates orchestration and safeguards, not the factual quality of live model output.
These limitations are tracked in the public roadmap.
- Node.js 20 or newer
- An OpenAI API key with access to the Responses API
git clone https://github.com/xxzzzzy/deep-research-skill.git
cd deep-research-skill
npm installSet your API key in the shell. Never commit it to the repository.
macOS or Linux:
export OPENAI_API_KEY="your-api-key"PowerShell:
$env:OPENAI_API_KEY = "your-api-key"npm run research -- "Compare PostgreSQL and MySQL for a small SaaS product"The generated Markdown report is written to reports/ by default. The command also prints the number of research rounds and the API-reported token usage.
| Environment variable | Default | Purpose |
|---|---|---|
RESEARCH_MODEL |
gpt-5-mini |
Model used for research and synthesis |
RESEARCH_MAX_ITER |
3 |
Research rounds, bounded to 1-5 |
RESEARCH_MAX_TOKENS |
2500 |
Maximum output tokens per API request |
RESEARCH_OUTPUT_DIR |
reports |
Directory for generated reports |
Example:
RESEARCH_MAX_ITER=2 RESEARCH_MAX_TOKENS=1500 npm run research -- "Research question"The automated tests do not call the OpenAI API and do not require an API key.
npm test
npm run checkThe project will publish reproducible evaluation cases covering:
- source authority and diversity;
- citation support for important claims;
- factual disagreements and uncertainty;
- repeated information across rounds;
- report completeness;
- token use and stopping behavior.
The initial engineering plan is documented in ROADMAP.md. Evaluation data and results will be added under evals/ as the methodology stabilizes.
The broader structured-research approach is also being explored in lian-ai, an open-source experiment based on the analysis of 333 public video transcripts. It is a separate project and is not evidence that the current research loop is already production-ready.
- Review generated claims and sources before relying on a report.
- Do not include private, confidential, or personal data in research prompts.
- Use strict round and output limits to control API consumption.
- Do not use the tool to generate deceptive citations or impersonate authoritative research.
MIT