diff --git a/docs/docs.json b/docs/docs.json index da3a71be78..88b0d12a1d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -10,11 +10,7 @@ }, "favicon": "/images/favicon.png", "contextual": { - "options": [ - "copy", - "view", - "claude" - ] + "options": ["copy", "view", "claude"] }, "navigation": { "dropdowns": [ @@ -39,11 +35,7 @@ "pages": [ { "group": "Tasks", - "pages": [ - "tasks/overview", - "tasks/schemaTask", - "tasks/scheduled" - ] + "pages": ["tasks/overview", "tasks/schemaTask", "tasks/scheduled"] }, "triggering", "runs", @@ -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", @@ -108,9 +95,7 @@ }, { "group": "Development", - "pages": [ - "cli-dev" - ] + "pages": ["cli-dev"] }, { "group": "Deployment", @@ -122,9 +107,7 @@ "deployment/atomic-deployment", { "group": "Deployment integrations", - "pages": [ - "vercel-integration" - ] + "pages": ["vercel-integration"] } ] }, @@ -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", @@ -218,11 +196,7 @@ }, { "group": "Help", - "pages": [ - "community", - "help-slack", - "help-email" - ] + "pages": ["community", "help-slack", "help-email"] } ] }, @@ -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", @@ -292,9 +263,7 @@ "groups": [ { "group": "Introduction", - "pages": [ - "guides/introduction" - ] + "pages": ["guides/introduction"] }, { "group": "Frameworks", @@ -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" ] }, @@ -407,9 +377,7 @@ }, { "group": "Migration guides", - "pages": [ - "migration-mergent" - ] + "pages": ["migration-mergent"] }, { "group": "Community packages", @@ -430,10 +398,7 @@ "href": "https://trigger.dev" }, "api": { - "openapi": [ - "openapi.yml", - "v3-openapi.yaml" - ], + "openapi": ["openapi.yml", "v3-openapi.yaml"], "playground": { "display": "simple" } @@ -608,4 +573,4 @@ "destination": "/management/overview" } ] -} \ No newline at end of file +} diff --git a/docs/guides/example-projects/vercel-ai-sdk-deep-research.mdx b/docs/guides/example-projects/vercel-ai-sdk-deep-research.mdx new file mode 100644 index 0000000000..aa0d54687c --- /dev/null +++ b/docs/guides/example-projects/vercel-ai-sdk-deep-research.mdx @@ -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"; + + + + + 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). + + +## 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. + + + +**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 + + + 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. + + +## 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("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. + + diff --git a/docs/guides/introduction.mdx b/docs/guides/introduction.mdx index 451cca43d2..3fba744586 100644 --- a/docs/guides/introduction.mdx +++ b/docs/guides/introduction.mdx @@ -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