diff --git a/docs/docs.json b/docs/docs.json index 7e1c0dec51..b88d903a93 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -333,6 +333,7 @@ "guides/example-projects/batch-llm-evaluator", "guides/example-projects/claude-thinking-chatbot", "guides/example-projects/human-in-the-loop-workflow", + "guides/example-projects/mastra-agents-with-memory", "guides/example-projects/meme-generator-human-in-the-loop", "guides/example-projects/openai-agent-sdk-guardrails", "guides/example-projects/openai-agents-sdk-typescript-playground", diff --git a/docs/guides/ai-agents/overview.mdx b/docs/guides/ai-agents/overview.mdx index de734ccf59..db694fa055 100644 --- a/docs/guides/ai-agents/overview.mdx +++ b/docs/guides/ai-agents/overview.mdx @@ -6,12 +6,80 @@ description: "Real world AI agent example tasks using Trigger.dev" ## Overview -This guide will show you how to set up different types of AI agent workflows with Trigger.dev. The examples take inspiration from Athropic's blog post on [building effective agents](https://www.anthropic.com/research/building-effective-agents). +These guides will show you how to set up different types of AI agent workflows with Trigger.dev. The examples take inspiration from Anthropic's blog post on [building effective agents](https://www.anthropic.com/research/building-effective-agents). - Chain prompts together to generate and translate marketing copy automatically - Send questions to different AI models based on complexity analysis - Simultaneously check for inappropriate content while responding to customer inquiries - Coordinate multiple AI workers to verify news article accuracy - Translate text and automatically improve quality through feedback loops + + Chain prompts together to generate and translate marketing copy automatically + + + Send questions to different AI models based on complexity analysis + + + Simultaneously check for inappropriate content while responding to customer inquiries + + + Coordinate multiple AI workers to verify news article accuracy + + + Translate text and automatically improve quality through feedback loops + + + +## Example projects using AI agents + + + + Create audio summaries of newspaper articles using a human-in-the-loop workflow built with + ReactFlow and Trigger.dev waitpoint tokens. + + + Use Mastra to create a weather agent that can collect live weather data and generate clothing + recommendations. + + + Use the OpenAI Agent SDK to create a guardrails system for your AI agents. + + + A playground containing 7 AI agents using the OpenAI Agent SDK for TypeScript with Trigger.dev. + + + Use the Vercel AI SDK to generate comprehensive PDF reports using a deep research agent. + diff --git a/docs/guides/example-projects/mastra-agents-with-memory.mdx b/docs/guides/example-projects/mastra-agents-with-memory.mdx new file mode 100644 index 0000000000..b900d6df57 --- /dev/null +++ b/docs/guides/example-projects/mastra-agents-with-memory.mdx @@ -0,0 +1,97 @@ +--- +title: "Mastra agents with memory sharing + Trigger.dev task orchestration" +sidebarTitle: "Mastra agents with memory" +description: "Multi-agent workflow with persistent memory sharing using Mastra and Trigger.dev for clothing recommendations based on weather data." +tag: "v4" +--- + +import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx"; + + + +## Overview + +Enter a city and an activity, and get a clothing recommendation generated for you based on today's weather. + +![Generated clothing recommendations](https://github.com/user-attachments/assets/edfca304-6b22-4fa8-9362-71ecb3fe4903) + +By combining Mastra's persistent memory system and agent orchestration with Trigger.dev's durable task execution, retries and observability, you get production-ready AI workflows that survive failures, scale automatically, and maintain context across long-running operations. + +## Tech stack + +- **[Node.js](https://nodejs.org)** runtime environment +- **[Mastra](https://mastra.ai)** for AI agent orchestration and memory management (Mastra is a Typescript framework for building AI agents, and uses Vercel's AI Agent SDK under the hood.) +- **[PostgreSQL](https://postgresql.org)** for persistent storage and memory sharing +- **[Trigger.dev](https://trigger.dev)** for task orchestration, batching, and observability +- **[OpenAI GPT-4](https://openai.com)** for natural language processing +- **[Open-Meteo API](https://open-meteo.com)** for weather data (no API key required) +- **[Zod](https://zod.dev)** for schema validation and type safety + +## 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. + + +## Featured patterns + +- **[Agent Memory Sharing](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/trigger/weather-task.ts)**: Efficient data sharing between agents using Mastra's working memory system +- **[Task Orchestration](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/trigger/weather-task.ts)**: Multi-step workflows with `triggerAndWait` for sequential agent execution +- **[Centralized Storage](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/index.ts)**: Single PostgreSQL storage instance shared across all agents to prevent connection duplication +- **[Custom Tools](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/tools/weather-tool.ts)**: External API integration with structured output validation +- **[Agent Specialization](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/agents/)**: Purpose-built agents with specific roles and instructions +- **[Schema Optimization](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/schemas/weather-data.ts)**: Lightweight data structures for performance + +## Project Structure + +``` +src/ +├── mastra/ +│ ├── agents/ +│ │ ├── weather-analyst.ts # Weather data collection +│ │ ├── clothing-advisor.ts # Clothing recommendations +│ ├── tools/ +│ │ └── weather-tool.ts # Enhanced weather API tool +│ ├── schemas/ +│ │ └── weather-data.ts # Weather schema +│ └── index.ts # Mastra configuration +├── trigger/ +│ └── weather-task.ts # Trigger.dev tasks +``` + +## Relevant code + +- **[Multi-step task orchestration](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/trigger/weather-task.ts)**: Multi-step task orchestration with `triggerAndWait` for sequential agent execution and shared memory context +- **[Weather analyst agent](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/agents/weather-analyst.ts)**: Specialized agent for weather data collection with external API integration and memory storage +- **[Clothing advisor agent](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/agents/clothing-advisor.ts)**: Purpose-built agent that reads from working memory and generates natural language responses +- **[Weather tool](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/tools/weather-tool.ts)**: Custom Mastra tool with Zod validation for external API calls and error handling +- **[Weather data schema](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/schemas/weather-data.ts)**: Optimized Zod schema for efficient memory storage and type safety +- **[Mastra configuration](https://github.com/triggerdotdev/examples/blob/main/mastra-agents/src/mastra/index.ts)**: Mastra configuration with PostgreSQL storage and agent registration + +## Storage Architecture + +This project uses a **centralized PostgreSQL storage** approach where a single database connection is shared across all Mastra agents. This prevents duplicate database connections and ensures efficient memory sharing between the weather analyst and clothing advisor agents. + +### Storage Configuration + +The storage is configured once in the main Mastra instance (`src/mastra/index.ts`) and automatically inherited by all agent Memory instances. This eliminates the "duplicate database object" warning that can occur with multiple PostgreSQL connections. + +The PostgreSQL storage works seamlessly in both local development and serverless environments with any PostgreSQL provider, such as: + +- [Local PostgreSQL instance](https://postgresql.org) +- [Supabase](https://supabase.com) - Serverless PostgreSQL +- [Neon](https://neon.tech) - Serverless PostgreSQL +- [Railway](https://railway.app) - Simple PostgreSQL hosting +- [AWS RDS](https://aws.amazon.com/rds/postgresql/) - Managed PostgreSQL + +## Learn More + +To learn more about the technologies used in this project, check out the following resources: + +- [Mastra docs](https://mastra.ai/en/docs) - learn about AI agent orchestration and memory management +- [Mastra working memory](https://mastra.ai/en/docs/memory/overview) - learn about efficient data sharing between agents diff --git a/docs/guides/introduction.mdx b/docs/guides/introduction.mdx index c692521216..12fc3e0faa 100644 --- a/docs/guides/introduction.mdx +++ b/docs/guides/introduction.mdx @@ -48,6 +48,7 @@ Example projects are full projects with example repos you can fork and use. Thes | [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) | +| [Mastra agents with memory](/guides/example-projects/mastra-agents-with-memory) | Use Mastra to create a weather agent that can collect live weather data and generate clothing recommendations. | — | [View the repo](https://github.com/triggerdotdev/examples/tree/main/mastra-agents) | | [OpenAI Agents SDK for Python guardrails](/guides/example-projects/openai-agent-sdk-guardrails) | Use the OpenAI Agents SDK for Python to create a guardrails system for your AI agents. | — | [View the repo](https://github.com/triggerdotdev/examples/tree/main/openai-agent-sdk-guardrails-examples) | | [OpenAI Agents SDK for TypeScript playground](/guides/example-projects/openai-agents-sdk-typescript-playground) | A playground containing 7 AI agents using the OpenAI Agents SDK for TypeScript with Trigger.dev. | — | [View the repo](https://github.com/triggerdotdev/examples/tree/main/openai-agents-sdk-with-trigger-playground) | | [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) |