ContextQMD
Back to Iii

AI Research Agent

frameworks/motia/docs/content/docs/examples/ai-deep-research-agent.mdx

0.13.04.6 KB
Original Source

Workflow Overview

<div className="my-8">![AI Deep Research Agent](./../img/ai-deep-research-agent.png)</div>

Try it yourself:

The Steps

<Folder name="steps" defaultOpen> <File name="analyze-content.step.ts" /> <File name="compile-report.step.ts" /> <File name="extract-content.step.ts" /> <File name="follow-up-research.step.ts" /> <File name="generate-queries.step.ts" /> <File name="report-api.step.ts" /> <File name="research-api.step.ts" /> <File name="search-web.step.ts" /> <File name="status-api.step.ts" /> </Folder> <Callout type="info"> This example uses the `steps/` directory, but you can also use `src/` or both. Motia discovers step files from either location automatically. </Callout>

View the source code for each step in the GitHub repository.

🚀 Features

  • Deep Web Research: Automatically searches the web, extracts content, and synthesizes findings
  • Iterative Research Process: Supports multiple layers of research depth for comprehensive exploration
  • Event-Driven Architecture: Built using Motia Framework's event system for robust workflow management
  • Parallel Processing: Efficiently processes search results and content extraction
  • API Endpoints: REST API access for initiating research and retrieving reports
  • Stateful Processing: Maintains research state throughout the entire process

📋 Prerequisites

  • Node.js v18 or later
  • npm or pnpm
  • API keys for:

🛠️ Installation

  1. Clone the repository:

    bash
    git clone https://github.com/MotiaDev/motia-examples
cd examples/ai-agents/specialized-agents/ai-deep-research-agent

  2. Install dependencies:

    bash
    pnpm install
# or
npm install

  3. Configure environment variables:

    bash
    cp .env.example .env

    Update .env with your API keys:

    bash
    # Required
OPENAI_API_KEY=your-openai-api-key-here
FIRECRAWL_API_KEY=your-firecrawl-api-key-here

# Optional
# OPENAI_MODEL=gpt-4o
# FIRECRAWL_BASE_URL=http://your-firecrawl-instance-url

🏗️ Architecture

🚦 API Endpoints

Start Research

POST /research
Content-Type: application/json

{
  "query": "The research topic or question",
  "breadth": 4,  // Number of search queries to generate (1-10)
  "depth": 2     // Depth of research iterations (1-5)
}

Response:

json
{
  "message": "Research process started",
  "requestId": "unique-trace-id"
}

Check Research Status

GET /research/status?requestId=unique-trace-id

Response:

json
{
  "message": "Research status retrieved successfully",
  "requestId": "unique-trace-id",
  "originalQuery": "The research topic or question",
  "status": "in-progress",
  "progress": {
    "currentDepth": 1,
    "totalDepth": 2,
    "percentComplete": 50
  },
  "reportAvailable": false
}

Get Research Report

GET /research/report?requestId=unique-trace-id

Response:

json
{
  "message": "Research report retrieved successfully",
  "report": {
    "title": "Research Report Title",
    "overview": "Executive summary...",
    "sections": [
      {
        "title": "Section Title",
        "content": "Section content..."
      }
    ],
    "keyTakeaways": [
      "Key takeaway 1",
      "Key takeaway 2"
    ],
    "sources": [
      {
        "title": "Source Title",
        "url": "Source URL"
      }
    ],
    "originalQuery": "The research topic or question",
    "metadata": {
      "depthUsed": 2,
      "completedAt": "2025-03-18T16:45:30Z"
    }
  },
  "requestId": "unique-trace-id"
}

🏃‍♂️ Running the Application

  1. Start the development server:

    bash
    pnpm dev

  2. Make a test request:

    bash
    curl --request POST \
--url http://localhost:3111/research \
--header 'Content-Type: application/json' \
--data '{
   "query": "Advancements in renewable energy storage",
   "depth": 1,
   "breadth": 1
}'

🙏 Acknowledgments