Deep research

This pack gives an agent investigation, academic search, scraping, aggregate search, trend discovery and iterative research tools. It uses axios for search and content APIs, DuckDuckGo HTML search, and OpenAI-compatible chat completion endpoints for query decomposition and report synthesis.

Installation

npm install @framers/agentos-ext-deep-research

Peer dependency: @framers/agentos with range >=0.10.40.

Usage

import { AgentOS } from '@framers/agentos';

const agentos = await AgentOS.create({
  extensionManifest: {
    packs: [
      {
        package: '@framers/agentos-ext-deep-research',
        options: {
          serperApiKey: process.env.SERPER_API_KEY,
          braveApiKey: process.env.BRAVE_API_KEY,
          serpApiKey: process.env.SERPAPI_API_KEY,
          openaiApiKey: process.env.OPENAI_API_KEY,
          openrouterApiKey: process.env.OPENROUTER_API_KEY,
        },
      },
    ],
  },
});

Configuration

Search keys resolve from options, then the selected secret map, then the environment. options.secrets replaces context secrets. The LLM key resolves from openaiApiKey, openai.apiKey, openrouterApiKey, openrouter.apiKey, OPENAI_API_KEY, then OPENROUTER_API_KEY.

primaryProvider selects openai, openrouter or ollama. An OpenRouter option or environment key also selects the OpenRouter endpoint when openaiApiKey is absent. The Ollama endpoint is local. A nonempty DEBUG enables console progress logging unless a per-call progress callback takes precedence.

Tools

researchInvestigate

researchAcademic

researchScrape

researchAggregate

researchTrending

deep_research

Notes

The manifest requires serper.apiKey, but the factory does not reject a missing key. Without it, deep_research uses DuckDuckGo HTML search. With it, the engine uses aggregate search; empty provider results do not trigger DuckDuckGo. Brave and SerpAPI are skipped when their keys are absent. Investigation and aggregate search skip failed sources or engines.

Service-backed tools require activation. deep_research declares capability:web_search and validates that query has at least 3 characters. Its sources input is passed to the search method but does not filter searches. Without an LLM key, the engine searches the original query; when it collects content and has LLM budget remaining, its no-op synthesis returns an empty summary. Configured LLM calls send research prompts and source evidence to the selected endpoint.

YouTube scraping returns oEmbed metadata, not transcripts. Wikipedia scraping uses the English summary endpoint. Investigation cross-references match shared title words. Trend category affects Reddit; the other providers ignore it.

Service HTTP requests use a 30000 ms timeout; generic scraping and engine page extraction use 15000 ms. Generic scraping truncates text to 10000 characters. The engine tracks search, extraction, LLM and elapsed-time budgets, with default iteration limits of 1 for quick, 3 for moderate and 6 for deep. These checks do not cancel an in-flight search or LLM request.

Firecrawl support exists in the engine, but the pack factory does not pass Firecrawl settings to it.

License

Apache-2.0