Skip to content

Added deep research example #2166

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 11, 2025
+168 −59
Merged

Added deep research example #2166

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b0ce123
Added docs
D-K-P Jun 10, 2025
7eef085
Improved docs and added video
D-K-P Jun 10, 2025
cda4beb
Added upgrade badge
D-K-P Jun 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 13 additions & 48 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,7 @@
},
"favicon": "/images/favicon.png",
"contextual": {
"options": [
"copy",
"view",
"claude"
]
"options": ["copy", "view", "claude"]
},
"navigation": {
"dropdowns": [
Expand All @@ -39,11 +35,7 @@
"pages": [
{
"group": "Tasks",
"pages": [
"tasks/overview",
"tasks/schemaTask",
"tasks/scheduled"
]
"pages": ["tasks/overview", "tasks/schemaTask", "tasks/scheduled"]
},
"triggering",
"runs",
Expand All @@ -58,12 +50,7 @@
"errors-retrying",
{
"group": "Wait",
"pages": [
"wait",
"wait-for",
"wait-until",
"wait-for-token"
]
"pages": ["wait", "wait-for", "wait-until", "wait-for-token"]
},
"queue-concurrency",
"versioning",
Expand Down Expand Up @@ -108,9 +95,7 @@
},
{
"group": "Development",
"pages": [
"cli-dev"
]
"pages": ["cli-dev"]
},
{
"group": "Deployment",
Expand All @@ -122,9 +107,7 @@
"deployment/atomic-deployment",
{
"group": "Deployment integrations",
"pages": [
"vercel-integration"
]
"pages": ["vercel-integration"]
}
]
},
Expand Down Expand Up @@ -177,12 +160,7 @@
},
{
"group": "Using the Dashboard",
"pages": [
"run-tests",
"troubleshooting-alerts",
"replaying",
"bulk-actions"
]
"pages": ["run-tests", "troubleshooting-alerts", "replaying", "bulk-actions"]
},
{
"group": "Troubleshooting",
Expand Down Expand Up @@ -218,11 +196,7 @@
},
{
"group": "Help",
"pages": [
"community",
"help-slack",
"help-email"
]
"pages": ["community", "help-slack", "help-email"]
}
]
},
Expand All @@ -243,10 +217,7 @@
},
{
"group": "Tasks API",
"pages": [
"management/tasks/trigger",
"management/tasks/batch-trigger"
]
"pages": ["management/tasks/trigger", "management/tasks/batch-trigger"]
},
{
"group": "Runs API",
Expand Down Expand Up @@ -292,9 +263,7 @@
"groups": [
{
"group": "Introduction",
"pages": [
"guides/introduction"
]
"pages": ["guides/introduction"]
},
{
"group": "Frameworks",
Expand Down Expand Up @@ -376,6 +345,7 @@
"guides/example-projects/realtime-csv-importer",
"guides/example-projects/realtime-fal-ai",
"guides/example-projects/turborepo-monorepo-prisma",
"guides/example-projects/vercel-ai-sdk-deep-research",
"guides/example-projects/vercel-ai-sdk-image-generator"
]
},
Expand Down Expand Up @@ -407,9 +377,7 @@
},
{
"group": "Migration guides",
"pages": [
"migration-mergent"
]
"pages": ["migration-mergent"]
},
{
"group": "Community packages",
Expand All @@ -430,10 +398,7 @@
"href": "https://trigger.dev"
},
"api": {
"openapi": [
"openapi.yml",
"v3-openapi.yaml"
],
"openapi": ["openapi.yml", "v3-openapi.yaml"],
"playground": {
"display": "simple"
}
Expand Down Expand Up @@ -608,4 +573,4 @@
"destination": "/management/overview"
}
]
}
}
143 changes: 143 additions & 0 deletions docs/guides/example-projects/vercel-ai-sdk-deep-research.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
---
title: "Deep research agent using Vercel's AI SDK"
sidebarTitle: "Deep research agent"
description: "Deep research agent which generates comprehensive PDF reports using Vercel's AI SDK."
tag: "v4"
---

import RealtimeLearnMore from "/snippets/realtime-learn-more.mdx";

import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";

<UpgradeToV4Note />

<Info title="Acknowledgements">
Acknowledgements: This example project is derived from the brilliant [deep research
guide](https://aie-feb-25.vercel.app/docs/deep-research) by [Nico
Albanese](https://x.com/nicoalbanese10).
</Info>

## Overview

This full-stack project is an intelligent deep research agent that autonomously conducts multi-layered web research, generating comprehensive reports which are then converted to PDF and uploaded to storage.

<video
controls
className="w-full aspect-video"
src="https://github.com/user-attachments/assets/aa86d2b2-7aa7-4948-82ff-5e1e80cf8e37"
></video>

**Tech stack:**

- **[Next.js](https://nextjs.org/)** for the web app
- **[Vercel's AI SDK](https://sdk.vercel.ai/)** for AI model integration and structured generation
- **[Trigger.dev](https://trigger.dev)** for task orchestration, execution and real-time progress updates
- **[OpenAI's GPT-4o model](https://openai.com/gpt-4)** for intelligent query generation, content analysis, and report creation
- **[Exa API](https://exa.ai/)** for semantic web search with live crawling
- **[LibreOffice](https://www.libreoffice.org/)** for PDF generation
- **[Cloudflare R2](https://developers.cloudflare.com/r2/)** to store the generated reports

**Features:**

- **Recursive research**: AI generates search queries, evaluates their relevance, asks follow-up questions and searches deeper based on initial findings.
- **Real-time progress**: Live updates are shown on the frontend using Trigger.dev Realtime as research progresses.
- **Intelligent source evaluation**: AI evaluates search result relevance before processing.
- **Research report generation**: The completed research is converted to a structured HTML report using a detailed system prompt.
- **PDF creation and uploading to Cloud storage**: The completed reports are then converted to PDF using LibreOffice and uploaded to Cloudflare R2.

## GitHub repo

<Card
title="View the Vercel AI SDK deep research agent repo"
icon="GitHub"
href="https://github.com/triggerdotdev/examples/tree/main/vercel-ai-sdk-deep-research-agent"
>
Click here to view the full code for this project in our examples repository on GitHub. You can
fork it and use it as a starting point for your own project.
</Card>

## How the deep research agent works

### Trigger.dev orchestration

The research process is orchestrated through three connected Trigger.dev tasks:

1. `deepResearchOrchestrator` - Main task that coordinates the entire research workflow.
2. `generateReport` - Processes research data into a structured HTML report using OpenAI's GPT-4o model
3. `generatePdfAndUpload` - Converts HTML to PDF using LibreOffice and uploads to R2 cloud storage

Each task uses `triggerAndWait()` to create a dependency chain, ensuring proper sequencing while maintaining isolation and error handling.

### The deep research recursive function

The core research logic uses a recursive depth-first search approach. A query is recursively expanded and the results are collected.

**Key parameters:**

- `depth`: Controls recursion levels (default: 2)
- `breadth`: Number of queries per level (default: 2, halved each recursion)

```
Level 0 (Initial Query): "AI safety in autonomous vehicles"
│
├── Level 1 (depth = 1, breadth = 2):
│ ├── Sub-query 1: "Machine learning safety protocols in self-driving cars"
│ │ ├── → Search Web → Evaluate Relevance → Extract Learnings
│ │ └── → Follow-up: "How do neural networks handle edge cases?"
│ │
│ └── Sub-query 2: "Regulatory frameworks for autonomous vehicle testing"
│ ├── → Search Web → Evaluate Relevance → Extract Learnings
│ └── → Follow-up: "What are current safety certification requirements?"
│
└── Level 2 (depth = 2, breadth = 1):
├── From Sub-query 1 follow-up:
│ └── "Neural network edge case handling in autonomous systems"
│ └── → Search Web → Evaluate → Extract → DEPTH LIMIT REACHED
│
└── From Sub-query 2 follow-up:
└── "Safety certification requirements for self-driving vehicles"
└── → Search Web → Evaluate → Extract → DEPTH LIMIT REACHED
```

**Process flow:**

1. **Query generation**: OpenAI's GPT-4o generates multiple search queries from the input
2. **Web search**: Each query searches the web via the Exa API with live crawling
3. **Relevance evaluation**: OpenAI's GPT-4o evaluates if results help answer the query
4. **Learning extraction**: Relevant results are analyzed for key insights and follow-up questions
5. **Recursive deepening**: Follow-up questions become new queries for the next depth level
6. **Accumulation**: All learnings, sources, and queries are accumulated across recursion levels

### Using Trigger.dev Realtime to trigger and subscribe to the deep research task

We use the [`useRealtimeTaskTrigger`](/frontend/react-hooks/triggering#userealtimetasktrigger) React hook to trigger the `deep-research` task and subscribe to it's updates.

**Frontend (React Hook)**:

```typescript
const triggerInstance = useRealtimeTaskTrigger<typeof deepResearchOrchestrator>("deep-research", {
accessToken: triggerToken,
});
const { progress, label } = parseStatus(triggerInstance.run?.metadata);
```

As the research progresses, the metadata is set within the tasks and the frontend is kept updated with every new status:

**Task Metadata**:

```typescript
metadata.set("status", {
progress: 25,
label: `Searching the web for: "${query}"`,
});
```

## Relevant code

- **Deep research task**: Core logic in [src/trigger/deepResearch.ts](https://github.com/triggerdotdev/examples/blob/main/vercel-ai-sdk-deep-research-agent/src/trigger/deepResearch.ts) - orchestrates the recursive research process. Here you can change the model, the depth and the breadth of the research.
- **Report generation**: [src/trigger/generateReport.ts](https://github.com/triggerdotdev/examples/blob/main/vercel-ai-sdk-deep-research-agent/src/trigger/generateReport.ts) - creates structured HTML reports from research data. The system prompt is defined in the code - this can be updated to be more or less detailed.
- **PDF generation**: [src/trigger/generatePdfAndUpload.ts](https://github.com/triggerdotdev/examples/blob/main/vercel-ai-sdk-deep-research-agent/src/trigger/generatePdfAndUpload.ts) - converts reports to PDF and uploads to R2. This is a simple example of how to use LibreOffice to convert HTML to PDF.
- **Research agent UI**: [src/components/DeepResearchAgent.tsx](https://github.com/triggerdotdev/examples/blob/main/vercel-ai-sdk-deep-research-agent/src/components/DeepResearchAgent.tsx) - handles form submission and real-time progress display using the `useRealtimeTaskTrigger` hook.
- **Progress component**: [src/components/progress-section.tsx](https://github.com/triggerdotdev/examples/blob/main/deep-research-agent/src/components/progress-section.tsx) - displays live research progress.

<RealtimeLearnMore />
23 changes: 12 additions & 11 deletions docs/guides/introduction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,17 +43,18 @@ Get set up fast using our detailed walk-through guides.

Example projects are full projects with example repos you can fork and use. These are a great way of learning how to encorporate Trigger.dev into your project.

| Example project | Description | Framework | GitHub |
| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------ |
| [Batch LLM Evaluator](/guides/example-projects/batch-llm-evaluator) | Evaluate multiple LLM models and stream the results to the frontend. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/batch-llm-evaluator) |
| [Claude thinking chatbot](/guides/example-projects/claude-thinking-chatbot) | Use Vercel's AI SDK and Anthropic's Claude 3.7 model to create a thinking chatbot. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/claude-thinking-chatbot) |
| [Human-in-the-loop workflow](/guides/example-projects/human-in-the-loop-workflow) | Create audio summaries of newspaper articles using a human-in-the-loop workflow built with ReactFlow and Trigger.dev waitpoint tokens. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/article-summary-workflow) |
| [OpenAI Agent SDK guardrails](/guides/example-projects/openai-agent-sdk-guardrails) | Use the OpenAI Agent SDK to create a guardrails system for your AI agents. | — | [View the repo](https://github.com/triggerdotdev/examples/tree/main/openai-agent-sdk-guardrails-examples) |
| [Python web crawler](/guides/python/python-crawl4ai) | Use Python, Crawl4AI and Playwright to create a headless web crawler with Trigger.dev. | — | [View the repo](https://github.com/triggerdotdev/examples/tree/main/python-crawl4ai) |
| [Realtime CSV Importer](/guides/example-projects/realtime-csv-importer) | Upload a CSV file and see the progress of the task streamed to the frontend. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/realtime-csv-importer) |
| [Realtime Fal.ai image generation](/guides/example-projects/realtime-fal-ai) | Generate an image from a prompt using Fal.ai and show the progress of the task on the frontend using Realtime. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/realtime-fal-ai-image-generation) |
| [Turborepo monorepo with Prisma](/guides/example-projects/turborepo-monorepo-prisma) | Use Prisma in a Turborepo monorepo with Trigger.dev. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/monorepos/turborepo-prisma-tasks-package) |
| [Vercel AI SDK image generator](/guides/example-projects/vercel-ai-sdk-image-generator) | Use the Vercel AI SDK to generate images from a prompt. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/vercel-ai-sdk-image-generator) |
| Example project | Description | Framework | GitHub |
| :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------ |
| [Batch LLM Evaluator](/guides/example-projects/batch-llm-evaluator) | Evaluate multiple LLM models and stream the results to the frontend. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/batch-llm-evaluator) |
| [Claude thinking chatbot](/guides/example-projects/claude-thinking-chatbot) | Use Vercel's AI SDK and Anthropic's Claude 3.7 model to create a thinking chatbot. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/claude-thinking-chatbot) |
| [Human-in-the-loop workflow](/guides/example-projects/human-in-the-loop-workflow) | Create audio summaries of newspaper articles using a human-in-the-loop workflow built with ReactFlow and Trigger.dev waitpoint tokens. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/article-summary-workflow) |
| [OpenAI Agent SDK guardrails](/guides/example-projects/openai-agent-sdk-guardrails) | Use the OpenAI Agent SDK to create a guardrails system for your AI agents. | — | [View the repo](https://github.com/triggerdotdev/examples/tree/main/openai-agent-sdk-guardrails-examples) |
| [Python web crawler](/guides/python/python-crawl4ai) | Use Python, Crawl4AI and Playwright to create a headless web crawler with Trigger.dev. | — | [View the repo](https://github.com/triggerdotdev/examples/tree/main/python-crawl4ai) |
| [Realtime CSV Importer](/guides/example-projects/realtime-csv-importer) | Upload a CSV file and see the progress of the task streamed to the frontend. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/realtime-csv-importer) |
| [Realtime Fal.ai image generation](/guides/example-projects/realtime-fal-ai) | Generate an image from a prompt using Fal.ai and show the progress of the task on the frontend using Realtime. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/realtime-fal-ai-image-generation) |
| [Turborepo monorepo with Prisma](/guides/example-projects/turborepo-monorepo-prisma) | Use Prisma in a Turborepo monorepo with Trigger.dev. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/monorepos/turborepo-prisma-tasks-package) |
| [Vercel AI SDK image generator](/guides/example-projects/vercel-ai-sdk-image-generator) | Use the Vercel AI SDK to generate images from a prompt. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/vercel-ai-sdk-image-generator) |
| [Vercel AI SDK deep research agent](/guides/example-projects/vercel-ai-sdk-deep-research) | Use the Vercel AI SDK to generate comprehensive PDF reports using a deep research agent. | Next.js | [View the repo](https://github.com/triggerdotdev/examples/tree/main/vercel-ai-sdk-deep-research-agent) |

## Example tasks

Expand Down