This guide shows you how to integrate and use Arcade tools within a Mastra agent. For the complete working example, check out our GitHub repository.
Prerequisites
- Obtain an Arcade API key
- Basic familiarity with TypeScript and Mastra concepts
Create a Mastra project
Start by creating a new Mastra project using the official CLI:
# Create a new Mastra project
npx create-mastra@latest my-arcade-agent
# Navigate to the project
cd my-arcade-agent
For more details on setting up a Mastra project, refer to the Mastra documentation.
Install Arcade client
Install the Arcade client:
pnpm add @arcadeai/arcadejs
Configure API keys
Set up your environment with the required API keys:
// Set your API keys in your environment variables or .env file
process.env.ARCADE_API_KEY = "your_arcade_api_key";
process.env.ANTHROPIC_API_KEY = "your_anthropic_api_key"; // or another supported model provider
Convert Arcade tools to Mastra tools
Arcade offers methods to convert tools into Zod schemas, which is essential since Mastra defines tools using Zod. The toZodToolSet
method is particularly useful, as it simplifies this integration and makes it easier to use Arcade’s tools with Mastra. Learn more about Arcade’s Zod integration options here.
import { Arcade } from "@arcadeai/arcadejs";
import {
executeOrAuthorizeZodTool,
toZodToolSet,
} from "@arcadeai/arcadejs/lib";
// Initialize Arcade
const arcade = new Arcade();
// Get Gmail tools
const googleToolkit = await arcade.tools.list({ toolkit: "gmail", limit: 30 });
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 and configure your Mastra agent
Now create a Mastra agent that uses Arcade tools:
import { Agent } from "@mastra/core/agent";
import { anthropic } from "@ai-sdk/anthropic";
// Create the Mastra agent with Arcade 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).
If a tool requires authorization, you will receive an authorization URL.
When that happens, clearly present this URL to the user and ask them to visit it to grant permissions.`,
model: anthropic("claude-3-7-sonnet-20250219"),
tools: googleTools,
});
Interact with your agent
You can interact with your agent in two main ways:
1. Using the Mastra Development Playground:
Start the Mastra development server:
npm run dev
This will launch a local development playground, typically accessible at http://localhost:4111
. Open this URL in your browser, select the googleAgent
from the list of available agents, and start chatting with it directly in the UI.
2. Programmatically:
Alternatively, you can interact with the agent directly in your code:
// Generate a response from the agent
const response = await googleAgent.generate(
"Read my last email and summarize it in a few sentences",
);
console.log(response.text);
// Or stream the response for a more interactive experience
const stream = await googleAgent.stream("Send an email to dev@arcade.dev with the subject 'Hello from Mastra'");
for await (const chunk of stream.textStream) {
process.stdout.write(chunk);
}
{ authorization_required: true, url: '...', message: '...' }
). Your agent’s instructions should guide it to present this URL to the user. After the user visits this URL and grants permissions, the tool can be used successfully. See the Managing user authorization guide for more details on handling authentication flows.