Using Arcade tools with Mastra

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


pnpm add @arcadeai/arcadejs

npm


npm install @arcadeai/arcadejs

yarn


yarn install @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 toolkit
// Toolkit names can be found in the Arcade dashboard via Tools > view > Toolkit or via the CLI `arcade workers list`
const gmailToolkit = await arcade.tools.list({ toolkit: "Gmail", limit: 30 });
 
// Get Gmail tools
export const gmailTools = toZodToolSet({
	tools: gmailToolkit.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 gmailAgent = new Agent({
  name: "gmailAgent",
    instructions: `You are a Gmail assistant that helps users manage their inbox.
 
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
 
Use the gmailTools to interact with various Gmail services and perform related tasks.`,
  model: anthropic("claude-3-7-sonnet-20250219"),
  tools: gmailTools,
});

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 gmailAgent 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 gmailAgent.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 gmailAgent.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);
}

When running your agent for the first time with tools that require user consent (like Google or Github), the agent will return an authorization reponse (e.g., { 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.