Deep Research Assistant with Cedar-OS + Mastra

An advanced AI deep research assistant with an interactive Cedar-OS frontend and powerful Mastra backend. Features human-in-the-loop workflows that allow users to explore topics, evaluate results, and generate comprehensive reports.

Architecture

This project combines two powerful frameworks:

• Cedar-OS Frontend: Modern Next.js app with AI-native chat interface
• Mastra Backend: Workflow-based agent system with research capabilities

├── src/
│   ├── app/              # Next.js app directory (Cedar-OS frontend)
│   ├── backend/          # Mastra backend with agents and workflows
│   │   └── src/mastra/   # Agents, tools, and workflows
│   ├── cedar/            # Cedar-OS message renderers
│   └── lib/              # Shared utilities

Features

Frontend (Cedar-OS)

• Interactive Chat Interface: Floating chat with beautiful UI
• Custom Message Renderers: Visual feedback for tool calls and results
• Real-time Updates: See research progress as it happens

Backend (Mastra)

• Workflow-Based Architecture: Structured research process with human-in-the-loop
• Research Agent: Autonomous web search and evaluation
• Custom Tools:
  • webSearchTool: Searches the web using Exa API
  • evaluateResultTool: Assesses result relevance
  • extractLearningsTool: Identifies key learnings and generates follow-ups
• Report Generation: Transforms findings into comprehensive markdown reports

Quick Start

1. Install Dependencies

# Install frontend dependencies
npm install

# Install backend dependencies
npm run backend:install

2. Set Up Environment Variables

Copy .env.example to .env in both root and backend:

# Root .env
cp .env.example .env

# Backend .env
cp src/backend/.env.example src/backend/.env

Edit both .env files with your API keys:

# Backend API Keys
OPENAI_API_KEY="your-openai-api-key"
EXA_API_KEY="your-exa-api-key"

# Frontend
NEXT_PUBLIC_MASTRA_BASE_URL="http://localhost:4111"

3. Start the Application

You'll need two terminal windows:

Terminal 1 - Start Backend (Mastra):

npm run backend:dev

Terminal 2 - Start Frontend (Next.js):

npm run dev

4. Use the Research Assistant

1. Open http://localhost:3000
2. Click the chat icon to open the Cedar-OS interface
3. Ask the assistant to research a topic:
   • "Research quantum computing applications"
   • "Research the latest developments in AI safety"
4. Review the research findings as they stream in
5. Approve or request more research
6. Receive a comprehensive markdown report

How It Works

Research Workflow

1. User Request: You ask for research on a topic via the Cedar-OS chat
2. Web Search: The research agent uses Exa to find relevant information
3. Evaluation: Each result is evaluated for relevance
4. Learning Extraction: Key learnings and follow-up questions are identified
5. Human Approval: You review and approve or iterate
6. Report Generation: A comprehensive report is generated

Key Technologies

• Cedar-OS: AI-native React framework for building copilot interfaces
• Mastra: Agent orchestration framework with workflows
• Next.js 15: React framework with App Router
• Tailwind CSS: Utility-first CSS framework
• Exa API: Advanced web search for AI agents
• OpenAI: GPT-4 for research and analysis

Available Scripts

# Frontend
npm run dev          # Start Next.js dev server (port 3000)
npm run build        # Build Next.js app
npm run start        # Start production server
npm run lint         # Run ESLint

# Backend
npm run backend:dev      # Start Mastra dev server (port 4111)
npm run backend:install  # Install backend dependencies

Project Structure

agentic-web-deep-research/
├── src/
│   ├── app/                    # Next.js app directory
│   │   ├── layout.tsx         # Root layout with CedarCopilot
│   │   ├── page.tsx           # Home page with FloatingCedarChat
│   │   └── globals.css        # Global styles
│   ├── backend/               # Mastra backend
│   │   ├── src/mastra/        # Agents, tools, workflows
│   │   ├── package.json       # Backend dependencies
│   │   └── mastra.config.yaml # Mastra configuration
│   ├── cedar/                 # Cedar-OS customizations
│   │   └── messageRenderers.tsx
│   └── lib/                   # Shared utilities
├── package.json               # Frontend dependencies
└── README.md                  # This file

Troubleshooting

Backend won't start

• Ensure .env file exists in src/backend/ with valid API keys
• Check that port 4111 is available
• Run npm run backend:install to ensure dependencies are installed

Frontend shows connection error

• Make sure backend is running on port 4111
• Verify NEXT_PUBLIC_MASTRA_BASE_URL in root .env
• Check browser console for detailed error messages

Research not working

• Verify OPENAI_API_KEY and EXA_API_KEY are set in backend .env
• Check backend terminal for error messages
• Ensure Exa API key is valid and has credits

License

Apache-2.0