Installation

Installation

This page explains how to install and configure tsai-registry in your project.

Prerequisites

Before installing tsai-registry, make sure you have:

  • Node.js 18+ installed
  • A package manager (npm, pnpm, or yarn)
  • An existing Mastra project

Installation with CLI

The easiest way to get started is using the tsai-registry CLI tool. Make sure you are in the root directory of your project before running these commands.

Initialize configuration

Create a settings-registry.json file to define where components will be stored locally. The init command asks for the folder path (default src/mastra/registry) and whether to overwrite the file if it already exists.

npx tsai-registry init

List available components

# List all available components
npx tsai-registry list

# List specific component types
npx tsai-registry list agents

Add components to your project

# Add a specific agent to your project
npx tsai-registry add weather-agent

# Add multiple agents
npx tsai-registry add exa-agent
npx tsai-registry add firecrawl-agent

By default, configuration files will be downloaded to ./src/mastra/registry/ in your project.

When you add an agent that requires API keys, the CLI will automatically show you which environment variables to add:

$ npx tsai-registry add firecrawl-agent
Downloaded file: /home/your-project/src/mastra/registry/agents/firecrawl-agent/web-agent.ts
Downloaded file: /home/your-project/src/mastra/registry/agents/firecrawl-agent/index.ts
Installing dependencies: @mastra/core, @ai-sdk/openai, @mastra/memory, @mastra/libsql, @mastra/mcp

Environment variables to add to your .env:
FIRECRAWL_API_KEY=
'firecrawl-agent' added successfully.

Configuration

After adding components, you need to configure them in your Mastra instance. Here’s a complete example based on our test project:

1. Environment Variables

Create a .env file with the API keys shown by the CLI during installation:

# Web Search (if using exa-agent)
EXA_API_KEY=your_exa_api_key

# Web Scraping (if using firecrawl-agent)
FIRECRAWL_API_KEY=your_firecrawl_api_key

Note: The weather agent doesn’t require any API keys.

2. Mastra Configuration

Configure your Mastra instance to use the downloaded agents:

// src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { weatherAgent } from "./registry/agents/weather-agent";

export const mastra = new Mastra({
  agents: { weatherAgent },
});

3. Agent Structure

Each agent comes with its complete configuration. For example, the weather agent includes:

src/mastra/registry/agents/weather-agent/
├── index.ts              # Export file
├── weather-agent.ts      # Main agent configuration
└── weather-tool.ts       # Associated tool

The weather agent is pre-configured with:

  • OpenAI GPT-4o-mini model
  • Weather tool for fetching data
  • Memory storage with LibSQL
  • Detailed instructions for weather assistance

Directory Structure

After installation, your project structure will look like this:

your-project/
├── .env
├── src/
│   └── mastra/
│       ├── index.ts
│       └── registry/
│           └── agents/
│               ├── weather-agent/
│               ├── exa-agent/
│               └── firecrawl-agent/
└── ...

Next Steps

Once installed, you can:

  1. Customize the agents to fit your specific needs
  2. Add additional tools or modify existing ones
  3. Integrate the agents into your application workflows
  4. Contribute back to the community by sharing your improvements