Add Mastra Integration Example (#397)

examples/mastra/.env.example

@@ -0,0 +1,2 @@
+OPENAI_API_KEY=sk-proj-1234567890
+ARCADE_API_KEY=arc_1234567890

examples/mastra/.gitignore

@@ -0,0 +1,8 @@
+output.txt
+node_modules
+dist
+.mastra
+.env.development
+.env
+*.db
+*.db-*

examples/mastra/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025, Arcade AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/mastra/README.md

@@ -0,0 +1,97 @@
+<h3 align="center">
+  <a name="readme-top"></a>
+  <img
+    src="https://docs.arcade.dev/images/logo/arcade-logo.png"
+  >
+</h3>
+<div align="center">
+  <h3>Arcade - Mastra Example</h3>
+    <a href="https://github.com/your-organization/agents-arcade/blob/main/LICENSE">
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
+</a>
+<p align="center">
+    <a href="https://docs.arcade.dev" target="_blank">Arcade Documentation</a> •
+    <a href="https://docs.arcade.dev/toolkits" target="_blank">Integrations</a> •
+    <a href="https://github.com/ArcadeAI/arcade-js" target="_blank">Arcade JS Client</a> •
+    <a href="https://github.com/mastra-ai/mastra" target="_blank">Mastra</a>
+</p>
+</div>
+
+# Arcade - Mastra Integration
+
+This example demonstrates how to integrate [Arcade](https://docs.arcade.dev) with [Mastra](https://mastra.ai/en/docs) to create powerful AI agents. Arcade provides access to a wide range of tools including Gmail, Slack, LinkedIn, and more, while Mastra provides a robust framework for building AI agents with TypeScript.
+
+For a list of all available tools and authentication options, see the [Arcade Integrations](https://docs.arcade.dev/toolkits) documentation. You can also build custom tools with the [Tool SDK](https://github.com/ArcadeAI/arcade-ai) as described in our [documentation](https://docs.arcade.dev/home/build-tools/create-a-toolkit).
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download/) (v20.0 or higher)
+- [pnpm](https://pnpm.io/installation) (v9.15.9 or higher)
+- [OpenAI API key](https://platform.openai.com/account/api-keys)
+- [Arcade API key](https://docs.arcade.dev/home/api-keys)
+
+## Installation
+
+1. Install dependencies:
+
+```bash
+pnpm install
+```
+
+2. Set up environment variables:
+   - Copy `.env.example` to `.env`
+   - Fill in your API keys:
+
+     ```
+     OPENAI_API_KEY=your_openai_api_key
+     ARCADE_API_KEY=your_arcade_api_key
+     ```
+
+## Basic Usage
+
+This example demonstrates how to use Arcade's Google toolkit with Mastra to create an AI agent that can help users manage their Google services (Gmail, Calendar, Sheets, Drive, and Contacts). The agent will access your Google account (after authorization) and perform various tasks based on user requests.
+
+To get started:
+
+1. Start the Mastra playground:
+
+```bash
+pnpm dev
+```
+
+2. Open your browser and navigate to <http://localhost:4111/>
+
+The Mastra playground provides an interactive interface where you can:
+
+- Chat with your agent
+- Execute specific tools
+
+## Authorization
+
+When using tools that require authorization, the agent will provide an authorization URL. You'll need to:
+
+1. Click on the authorization URL provided in the chat/execution interface
+2. Complete the authorization flow in your browser
+3. Return to the Mastra playground to continue your interaction
+
+This authorization process is handled by the `executeOrAuthorizeZodTool` helper function, which checks if a tool requires authorization and returns the appropriate URL when needed. Once authorized, the tool will execute normally in subsequent requests without requiring re-authorization.
+
+## Development
+
+To modify or extend the functionality:
+
+1. Update the `userId` in `agents/google.ts` with your application's user identification
+2. Modify the `toolkit` parameter in `arcade.tools.list()` to access different tools. Available toolkits include:
+   - `"google"` - Gmail, Google Calendar, Google Drive
+   - `"slack"` - Slack messaging and channels
+   - `"github"` - GitHub repositories and issues
+   - And more in [Arcade Integrations](https://docs.arcade.dev/toolkits) documentation
+
+## Security
+
+- Never commit your `.env` file
+- Use appropriate user identification in production
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

examples/mastra/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "mastra",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "mastra dev",
+    "build": "mastra build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@ai-sdk/openai": "^1.3.22",
+    "@arcadeai/arcadejs": "^1.5.0",
+    "@mastra/core": "0.9.4-alpha.1",
+    "@mastra/libsql": "0.0.4-alpha.1",
+    "@mastra/memory": "0.3.4-alpha.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.17",
+    "mastra": "0.6.3-alpha.1",
+    "typescript": "^5.8.3"
+  }
+}

examples/mastra/src/mastra/agents/google.ts

@@ -0,0 +1,54 @@
+import { openai } from "@ai-sdk/openai";
+import { Arcade } from "@arcadeai/arcadejs";
+import {
+	executeOrAuthorizeZodTool,
+	toZodToolSet,
+} from "@arcadeai/arcadejs/lib";
+import { Agent } from "@mastra/core/agent";
+
+// Initialize Arcade
+const arcade = new Arcade();
+
+// Get Google tools
+const googleToolkit = await arcade.tools.list({ toolkit: "google", limit: 30 });
+
+/**
+ * Mastra requires tools to be defined using Zod, a TypeScript-first schema validation library
+ * that has become the standard for runtime type checking. Zod is particularly valuable because it:
+ * - Provides runtime type safety and validation
+ * - Offers excellent TypeScript integration with automatic type inference
+ * - Has a simple, declarative API for defining schemas
+ * - Is widely adopted in the TypeScript ecosystem
+ *
+ * Arcade provides `toZodToolSet` to convert our tools into Zod format, making them compatible
+ * with Mastra.
+ *
+ * The `executeOrAuthorizeZodTool` helper function simplifies authorization.
+ * It checks if the tool requires authorization: if so, it returns an authorization URL,
+ * otherwise, it runs the tool directly without extra boilerplate.
+ *
+ * Learn more: https://docs.arcade.dev/home/use-tools/get-tool-definitions#get-zod-tool-definitions
+ */
+export const googleTools = toZodToolSet({
+	tools: googleToolkit.items,
+	client: arcade,
+	userId: "<YOUR_USER_ID>", // Your app's internal ID for the user (an email, UUID, etc). It's used internally to identify your user in Arcade
+	executeFactory: executeOrAuthorizeZodTool, // Checks if tool is authorized and executes it, or returns authorization URL if needed
+});
+
+// Create an agent with Google tools
+export const googleAgent = new Agent({
+	name: "googleAgent",
+	instructions: `You are a Google assistant that helps users manage their Google services (Gmail, Calendar, Sheets, Drive, and Contacts).
+
+When helping users:
+- Always verify their intent before performing actions
+- Keep responses clear and concise
+- Confirm important actions before executing them
+- Respect user privacy and data security
+- Specify which Google service you're working with
+
+Use the googleTools to interact with various Google services and perform related tasks.`,
+	model: openai("gpt-4o-mini"),
+	tools: googleTools,
+});

examples/mastra/src/mastra/index.ts

@@ -0,0 +1,10 @@
+import { Mastra } from "@mastra/core";
+import { LibSQLStore } from "@mastra/libsql";
+import { googleAgent } from "./agents/google";
+
+export const mastra = new Mastra({
+	agents: { googleAgent },
+	storage: new LibSQLStore({
+		url: "file:../mastra.db",
+	}),
+});

examples/mastra/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "outDir": "dist"
+  },
+  "include": [
+    "src/**/*"
+  ]
+}