my-pi/packages/research-agent/README.md

Pi Research Agent

Autonomous research agent that searches the web, analyzes sources, and synthesizes findings into structured reports. Built on Pi agent core. Available as a CLI, programmatic API, and MCP server.

Features

• Autonomous Research: Breaks down topics into sub-questions and searches systematically
• Web Search: Uses Tavily API for comprehensive web search
• Source Analysis: Fetches and extracts content from web pages with retry logic
• Note Taking: Saves findings with confidence levels (high/medium/low) and source attribution
• Report Synthesis: Generates structured reports in markdown, JSON, or bullet format
• Skills System: Extensible via markdown skills in ~/.pi/skills/research/
• Multiple Output Modes: Interactive TUI or simple print mode
• Automatic Reports: Saves to ./research-output/<timestamp>-<topic>/
• MCP Server: Expose research capabilities as MCP tools for other agents
• CLI + Programmatic API: Use from terminal or embed in your own code

Installation

npm install @earendil-works/pi-research-agent

Quick Start

1. Get API Keys

• Tavily (web search): https://tavily.com/ — free tier: 1,000 searches/month
• OpenRouter (LLM): https://openrouter.ai/ — pay-per-use pricing

2. Configure

Create a .env file in your project root:

TAVILY_API_KEY=your-tavily-key
OPENROUTER_API_KEY=your-openrouter-key
LLM_MODEL=minimax/minimax-m3

3. Use

CLI:

# Basic research
pi-research "quantum computing breakthroughs 2026"

# Print mode (no TUI)
pi-research --print "AI safety research"

# Custom max turns
pi-research --max-turns 15 "climate change solutions"

# Custom model
pi-research -m openai/gpt-4o "renewable energy trends"

Programmatic:

import { ResearchAgent } from "@earendil-works/pi-research-agent";

const agent = new ResearchAgent({
  maxTurns: 10,
  saveResults: true,
  outputDir: "./research-output",
});

const result = await agent.research("machine learning in healthcare 2026");

console.log(`Turns: ${result.turnsUsed}, Notes: ${result.notes.length}`);
console.log(result.report);

As MCP Server:

# Run as MCP server
pi-research-mcp

Then configure in your MCP client (Claude Desktop, OpenCode, Cursor, etc.):

{
  "mcp": {
    "research-agent": {
      "type": "local",
      "command": ["node", "node_modules/@earendil-works/pi-research-agent/dist/mcp-cli.js"],
      "enabled": true
    }
  }
}

Available Tools

CLI / Programmatic

Tool	Description
web_search	Search the web using Tavily API
read_url	Fetch and extract content from a URL
save_note	Save a research finding with confidence level
synthesize_report	Generate final report from collected notes

MCP Server

Tool	Description
research	Full autonomous research with report generation
quick_search	Fast web search without full research flow
read_url	Extract content from a URL

Architecture

ResearchAgent
  └─> Agent (Pi core)
       ├─> web_search (Tavily API)
       ├─> read_url (URL fetcher + content extraction)
       ├─> save_note (in-memory store)
       └─> synthesize_report (terminates agent)

The agent autonomously decides when to search, read, and save findings. After collecting sufficient information, it calls synthesize_report to generate a comprehensive markdown report with executive summary, key findings, source citations, and confidence assessment.

Configuration

Environment Variables

Variable	Required	Default	Description
TAVILY_API_KEY	Yes	—	Tavily API key for web search
OPENROUTER_API_KEY	Yes	—	OpenRouter API key for LLM
LLM_MODEL	No	minimax/minimax-m3	LLM model to use

CLI Options

pi-research [options] <topic>

Options:
  -h, --help           Show help
  -v, --version        Show version
  -p, --print          Print mode (no TUI)
  -t, --max-turns <n>  Max research turns (default: 15)
  -m, --model <model>  Model (default: minimax/minimax-m3)
  -o, --output-dir <p> Output directory (default: ./research-output)
  --no-save            Don't save to disk

Programmatic Options

interface ResearchAgentOptions {
  model?: Model;                  // LLM model
  thinkingLevel?: ThinkingLevel;  // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
  maxTurns?: number;              // Max research turns (default: 15)
  tavilyApiKey?: string;          // Tavily API key
  llmApiKey?: string;             // LLM provider API key
  skills?: ResearchSkill[];       // Custom research skills
  outputDir?: string;             // Output directory (default: "./research-output")
  saveResults?: boolean;          // Save to disk (default: true)
}

Output Structure

Results are automatically saved to ./research-output/<timestamp>-<topic>/:

research-output/
  2026-06-04T14-30-45-quantum-computing-2026/
    report.md      # Final research report (markdown)
    report.json    # Full results (report + notes + metadata)
    notes.json     # Collected research notes

Research Skills

Create custom skills in ~/.pi/skills/research/:

---
name: deep-dive
description: Perform deep-dive research on technical topics
max_turns: 15
---

When researching technical topics:
1. Start with official documentation
2. Look for academic papers and whitepapers
3. Check recent blog posts from industry experts
4. Verify claims with multiple sources

Skills are automatically loaded and appended to the system prompt.

Examples

See examples/ for working code:

• basic.ts — Basic programmatic usage
• custom-model.ts — Using a different LLM model
• custom-skills.ts — Custom research skills
• with-env.ts — Environment variable configuration
• mcp-client.ts — MCP client example
• mcp-config-claude.json — Claude Desktop MCP config
• mcp-config-cursor.json — Cursor MCP config

Documentation

• MCP Server Guide — Detailed MCP setup instructions
• MCP Architecture — Architecture and flow diagrams
• Environment Setup — Detailed env var configuration
• Changelog — Version history

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Watch mode
npm run dev

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

MIT © Pi Research Team

Related

• Pi — The AI agent framework this is built on
• Model Context Protocol — Standard for AI tool integration
• Tavily — Web search API for AI applications
• OpenRouter — Unified API for LLMs