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 { Agent } from '@mastra/core';
import { getMainBranchRef } from '../tools';
 
export const codeReviewAgent = new Agent({
  name: 'Code Review Agent',
  instructions: 'An agent that reviews code repositories and provides feedback.',
  model: {
    provider: 'OPEN_AI',
    name: 'gpt-4',
  },
  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.

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.