|
| 1 | +--- |
| 2 | +title: "Deep research agent using Vercel's AI SDK" |
| 3 | +sidebarTitle: "Deep research agent" |
| 4 | +description: "Deep research agent which generates comprehensive PDF reports using Vercel's AI SDK." |
| 5 | +tag: "v4" |
| 6 | +--- |
| 7 | + |
| 8 | +import RealtimeLearnMore from "/snippets/realtime-learn-more.mdx"; |
| 9 | + |
| 10 | +<Info title="Acknowledgements"> |
| 11 | + Acknowledgements: This example project is derived from the brilliant [deep research |
| 12 | + guide](https://aie-feb-25.vercel.app/docs/deep-research) by [Nico |
| 13 | + Albanese](https://x.com/nicoalbanese10). |
| 14 | +</Info> |
| 15 | + |
| 16 | +## Overview |
| 17 | + |
| 18 | +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. |
| 19 | + |
| 20 | +**Tech stack:** |
| 21 | + |
| 22 | +- **[Next.js](https://nextjs.org/)** for the web app |
| 23 | +- **[Vercel's AI SDK](https://sdk.vercel.ai/)** for AI model integration and structured generation |
| 24 | +- **[Trigger.dev](https://trigger.dev)** for task orchestration, execution and real-time progress updates |
| 25 | +- **[OpenAI's GPT-4o model](https://openai.com/gpt-4)** for intelligent query generation, content analysis, and report creation |
| 26 | +- **[Exa API](https://exa.ai/)** for semantic web search with live crawling |
| 27 | +- **[LibreOffice](https://www.libreoffice.org/)** for PDF generation |
| 28 | +- **[Cloudflare R2](https://developers.cloudflare.com/r2/)** to store the generated reports |
| 29 | + |
| 30 | +**Features:** |
| 31 | + |
| 32 | +- **Recursive research**: AI generates search queries, evaluates their relevance, asks follow-up questions and searches deeper based on initial findings. |
| 33 | +- **Real-time progress**: Live updates are shown on the frontend using Trigger.dev Realtime as research progresses. |
| 34 | +- **Intelligent source evaluation**: AI evaluates search result relevance before processing. |
| 35 | +- **Research report generation**: The completed research is converted to a structured HTML report using a detailed system prompt. |
| 36 | +- **PDF creation and uploading to Cloud storage**: The completed reports are then converted to PDF using LibreOffice and uploaded to Cloudflare R2. |
| 37 | + |
| 38 | +## GitHub repo |
| 39 | + |
| 40 | +<Card |
| 41 | + title="View the Vercel AI SDK deep research agent repo" |
| 42 | + icon="GitHub" |
| 43 | + href="https://github.com/triggerdotdev/examples/tree/main/vercel-ai-sdk-deep-research-agent" |
| 44 | +> |
| 45 | + Click here to view the full code for this project in our examples repository on GitHub. You can |
| 46 | + fork it and use it as a starting point for your own project. |
| 47 | +</Card> |
| 48 | + |
| 49 | +## How the deep research agent works |
| 50 | + |
| 51 | +### Trigger.dev orchestration |
| 52 | + |
| 53 | +The research process is orchestrated through three connected Trigger.dev tasks: |
| 54 | + |
| 55 | +1. `deepResearchOrchestrator` - Main task that coordinates the entire research workflow. |
| 56 | +2. `generateReport` - Processes research data into a structured HTML report using OpenAI's GPT-4o model |
| 57 | +3. `generatePdfAndUpload` - Converts HTML to PDF using LibreOffice and uploads to R2 cloud storage |
| 58 | + |
| 59 | +Each task uses `triggerAndWait()` to create a dependency chain, ensuring proper sequencing while maintaining isolation and error handling. |
| 60 | + |
| 61 | +### The deep research recursive function |
| 62 | + |
| 63 | +The core research logic uses a recursive depth-first search approach. A query is recursively expanded and the results are collected. |
| 64 | + |
| 65 | +**Key parameters:** |
| 66 | + |
| 67 | +- `depth`: Controls recursion levels (default: 2) |
| 68 | +- `breadth`: Number of queries per level (default: 2, halved each recursion) |
| 69 | + |
| 70 | +``` |
| 71 | +Level 0 (Initial Query): "AI safety in autonomous vehicles" |
| 72 | +│ |
| 73 | +├── Level 1 (depth = 1, breadth = 2): |
| 74 | +│ ├── Sub-query 1: "Machine learning safety protocols in self-driving cars" |
| 75 | +│ │ ├── → Search Web → Evaluate Relevance → Extract Learnings |
| 76 | +│ │ └── → Follow-up: "How do neural networks handle edge cases?" |
| 77 | +│ │ |
| 78 | +│ └── Sub-query 2: "Regulatory frameworks for autonomous vehicle testing" |
| 79 | +│ ├── → Search Web → Evaluate Relevance → Extract Learnings |
| 80 | +│ └── → Follow-up: "What are current safety certification requirements?" |
| 81 | +│ |
| 82 | +└── Level 2 (depth = 2, breadth = 1): |
| 83 | + ├── From Sub-query 1 follow-up: |
| 84 | + │ └── "Neural network edge case handling in autonomous systems" |
| 85 | + │ └── → Search Web → Evaluate → Extract → DEPTH LIMIT REACHED |
| 86 | + │ |
| 87 | + └── From Sub-query 2 follow-up: |
| 88 | + └── "Safety certification requirements for self-driving vehicles" |
| 89 | + └── → Search Web → Evaluate → Extract → DEPTH LIMIT REACHED |
| 90 | +``` |
| 91 | + |
| 92 | +**Process flow:** |
| 93 | + |
| 94 | +1. **Query generation**: OpenAI's GPT-4o generates multiple search queries from the input |
| 95 | +2. **Web search**: Each query searches the web via the Exa API with live crawling |
| 96 | +3. **Relevance evaluation**: OpenAI's GPT-4o evaluates if results help answer the query |
| 97 | +4. **Learning extraction**: Relevant results are analyzed for key insights and follow-up questions |
| 98 | +5. **Recursive deepening**: Follow-up questions become new queries for the next depth level |
| 99 | +6. **Accumulation**: All learnings, sources, and queries are accumulated across recursion levels |
| 100 | + |
| 101 | +### Trigger.dev Realtime progress updates |
| 102 | + |
| 103 | +As each task is completed, the metadata is set and the frontend is updated: |
| 104 | + |
| 105 | +**Task metadata**: |
| 106 | + |
| 107 | +```typescript |
| 108 | +metadata.set("status", { |
| 109 | + progress: 25, |
| 110 | + label: `Searching the web for: "${query}"`, |
| 111 | +}); |
| 112 | +``` |
| 113 | + |
| 114 | +**Frontend (React hook)**: |
| 115 | + |
| 116 | +We use the [`useRealtimeTaskTrigger`](https://trigger.dev/docs/frontend/react-hooks/triggering#userealtimetasktrigger) hook to get the task metadata and update the frontend in real-time. |
| 117 | + |
| 118 | +```typescript |
| 119 | +const triggerInstance = useRealtimeTaskTrigger<typeof deepResearchOrchestrator>("deep-research", { |
| 120 | + accessToken: triggerToken, |
| 121 | +}); |
| 122 | +const { progress, label } = parseStatus(triggerInstance.run?.metadata); |
| 123 | +``` |
| 124 | + |
| 125 | +## Relevant code |
| 126 | + |
| 127 | +- **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. |
| 128 | +- **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. |
| 129 | +- **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. |
| 130 | +- **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. |
| 131 | +- **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. |
| 132 | + |
| 133 | +<RealtimeLearnMore /> |
0 commit comments