Using Mastra Integrations

Integrations in Mastra are auto-generated, type-safe API clients for third-party services. They can be used as tools for agents or as steps in workflows.

Installing an Integration

Mastra’s default integrations are packaged as individually installable npm modules. You can add an integration to your project by installing it via npm and importing it into your Mastra configuration.

Example: Adding the GitHub Integration

1. Install the Integration Package

To install the GitHub integration, run:

npm install @mastra/github

2. Add the Integration to Your Project

Create a new file for your integrations (e.g., src/mastra/integrations/index.ts) and import the integration:

import { GithubIntegration } from "@mastra/github";
 
export const github = new GithubIntegration({
  config: {
    PERSONAL_ACCESS_TOKEN: process.env.GITHUB_PAT!,
  },
});

Make sure to replace process.env.GITHUB_PAT! with your actual GitHub Personal Access Token or ensure that the environment variable is properly set.

3. Use the Integration in Tools or Workflows

You can now use the integration when defining tools for your agents or in workflows.

import { createTool } from "@mastra/core";
import { z } from "zod";
import { github } from "../integrations";
 
export const getMainBranchRef = createTool({
  id: "getMainBranchRef",
  description: "Fetch the main branch reference from a GitHub repository",
  inputSchema: z.object({
    owner: z.string(),
    repo: z.string(),
  }),
  outputSchema: z.object({
    ref: z.string().optional(),
  }),
  execute: async ({ context }) => {
    const client = await github.getApiClient();
 
    const mainRef = await client.gitGetRef({
      path: {
        owner: context.owner,
        repo: context.repo,
        ref: "heads/main",
      },
    });
 
    return { ref: mainRef.data?.ref };
  },
});

In the example above:

• We import the github integration.
• We define a tool called getMainBranchRef that uses the GitHub API client to fetch the reference of the main branch of a repository.
• The tool accepts owner and repo as inputs and returns the reference string.

Using Integrations in Agents

Once you’ve defined tools that utilize integrations, you can include these tools in your agents.

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { getMainBranchRef } from "../tools";
 
export const codeReviewAgent = new Agent({
  name: "Code Review Agent",
  instructions:
    "An agent that reviews code repositories and provides feedback.",
  model: openai("gpt-4o-mini"),
  tools: {
    getMainBranchRef,
    // other tools...
  },
});

In this setup:

• We create an agent named Code Review Agent.
• We include the getMainBranchRef tool in the agent’s available tools.
• The agent can now use this tool to interact with GitHub repositories during conversations.

Environment Configuration

Ensure that any required API keys or tokens for your integrations are properly set in your environment variables. For example, with the GitHub integration, you need to set your GitHub Personal Access Token:

GITHUB_PAT=your_personal_access_token

Consider using a .env file or another secure method to manage sensitive credentials.

Example: Adding the Mem0 Integration

In this example you’ll learn how to use the Mem0  platform to add long-term memory capabilities to an agent via tool-use. This memory integration can work alongside Mastra’s own agent memory features . Mem0 enables your agent to memorize and later remember facts per-user across all interactions with that user, while Mastra’s memory works per-thread. Using the two in conjunction will allow Mem0 to store long term memories across conversations/interactions, while Mastra’s memory will maintain linear conversation history in individual conversations.

1. Install the Integration Package

To install the Mem0 integration, run:

npm install @mastra/mem0

2. Add the Integration to Your Project

Create a new file for your integrations (e.g., src/mastra/integrations/index.ts) and import the integration:

import { Mem0Integration } from "@mastra/mem0";
 
export const mem0 = new Mem0Integration({
  config: {
    apiKey: process.env.MEM0_API_KEY!,
    userId: "alice",
  },
});

3. Use the Integration in Tools or Workflows

You can now use the integration when defining tools for your agents or in workflows.

import { createTool } from "@mastra/core";
import { z } from "zod";
import { mem0 } from "../integrations";
 
export const mem0RememberTool = createTool({
  id: "Mem0-remember",
  description:
    "Remember your agent memories that you've previously saved using the Mem0-memorize tool.",
  inputSchema: z.object({
    question: z
      .string()
      .describe("Question used to look up the answer in saved memories."),
  }),
  outputSchema: z.object({
    answer: z.string().describe("Remembered answer"),
  }),
  execute: async ({ context }) => {
    console.log(`Searching memory "${context.question}"`);
    const memory = await mem0.searchMemory(context.question);
    console.log(`\nFound memory "${memory}"\n`);
 
    return {
      answer: memory,
    };
  },
});
 
export const mem0MemorizeTool = createTool({
  id: "Mem0-memorize",
  description:
    "Save information to mem0 so you can remember it later using the Mem0-remember tool.",
  inputSchema: z.object({
    statement: z.string().describe("A statement to save into memory"),
  }),
  execute: async ({ context }) => {
    console.log(`\nCreating memory "${context.statement}"\n`);
    // to reduce latency memories can be saved async without blocking tool execution
    void mem0.createMemory(context.statement).then(() => {
      console.log(`\nMemory "${context.statement}" saved.\n`);
    });
    return { success: true };
  },
});

In the example above:

• We import the @mastra/mem0 integration.
• We define two tools that uses the Mem0 API client to create new memories and recall previously saved memories.
• The tool accepts question as an input and returns the memory as a string.

Available Integrations

Mastra provides several built-in integrations; primarily API-key based integrations that do not require OAuth. Some available integrations including Github, Stripe, Resend, Firecrawl, and more.

Check Mastra’s codebase  or npm packages  for a full list of available integrations.

Conclusion

Integrations in Mastra enable your AI agents and workflows to interact with external services seamlessly. By installing and configuring integrations, you can extend the capabilities of your application to include operations such as fetching data from APIs, sending messages, or managing resources in third-party systems.

Remember to consult the documentation of each integration for specific usage details and to adhere to best practices for security and type safety.