Get started

Build AI agents your users actually depend on. Mastra is a TypeScript framework that gives you everything you need to prototype fast and ship with confidence. Create your first agent with a single command and start building.

For AI agents: If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. Important for later: Define model as a string in provider/model format, for example openai/gpt-5.5. For OpenAI, use openai/<model>, not openai:<model>, and don't import or pass a provider object.

Create a package.json file with { "type": "module" }. Install the required dependencies: npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest

Create a tsconfig.json file:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

If you need to add a tool to the agent, create a new file and use import { createTool } from "@mastra/core/tools". Plain object tool definitions silently fail to execute; tools MUST be defined via createTool() with id, description, inputSchema (zod), execute(). execute() receives two parameters: the validated input data based on inputSchema (first parameter) and an optional execution context object (second parameter) containing requestContext, tracingContext, abortSignal, and other execution metadata.

Example:

// src/mastra/tools/weather-tool.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name'),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})

If you need to create an agent, create a new file and use import { Agent } from "@mastra/core/agent". The constructor takes { id, name, instructions, model }. The model property is a string in Mastra's model router format. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.

By defining the model using provider/model format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: OPENAI_API_KEY. Anthropic: ANTHROPIC_API_KEY. Google: GOOGLE_API_KEY. Example: Any openai/<model> requires the OPENAI_API_KEY environment variable. Go to https://mastra.ai/models/environment-variables for a full list of supported providers and their environment variable names.

Short list of known model IDs are:

openai/gpt-5.5, openai/gpt-5-mini
anthropic/claude-sonnet-4-6, anthropic/claude-opus-4-7, anthropic/claude-haiku-4-5
google/gemini-2.5-flash

Go to https://mastra.ai/models for a full list of supported models.

Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.

Example:

// src/mastra/agents/weather-agent.ts
import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool.ts'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.

      Your primary function is to help users get weather details for specific locations. When responding:
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  // Use a string in provider/model format, not provider:model or a provider object.
  model: 'openai/gpt-5.5',
  tools: { weatherTool },
})

Create a Mastra entry point at src/mastra/index.ts and register the agent:

import { Mastra } from '@mastra/core'
import { weatherAgent } from './agents/weather-agent.ts'

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

You're now able to run the agent directly. For this, import the Mastra instance and call the agent.generate() after retrieving the agent by its id. Node.js 22.18.0 and later are able to run TypeScript files directly. Make sure to add file extensions when importing local files. Example:

// run.mjs
import { mastra } from './src/mastra/index.ts'

const agent = mastra.getAgentById('weather-agent')
const response = await agent.generate('Weather in SF')
console.log(response.text)