# Required - at least one LLM provider
OPENAI_API_KEY=sk-...
# Or: ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, OPENROUTER_API_KEY

# Optional
POSTGRES_CONNECTION_STRING=postgresql://...   # for pgvector RAG/memory
PINECONE_API_KEY=...                          # for Pinecone vector store

# New project
npm create mastra@latest

# Existing project
npx mastra init --components agents,tools,workflows --llm openai

import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'
import { createTool } from '@mastra/core/tool'
import { z } from 'zod'

const myAgent = new Agent({
  id: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-4.1',
  tools: {},
})

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

import { Agent } from '@mastra/core/agent'
import { createTool } from '@mastra/core/tool'
import { z } from 'zod'

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Fetches current weather for a city',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ temp: z.number(), condition: z.string() }),
  execute: async ({ city }) => {
    const res = await fetch(`https://wttr.in/${city}?format=j1`)
    const data = await res.json()
    return { temp: Number(data.current_condition[0].temp_F), condition: data.current_condition[0].weatherDesc[0].value }
  },
})

const agent = new Agent({
  id: 'weather-agent',
  instructions: 'Help users check weather. Use the get-weather tool.',
  model: 'openai/gpt-4.1',
  tools: { [weatherTool.id]: weatherTool },
})

const stream = await agent.stream('What is the weather in Tokyo?')
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}

import { createWorkflow, createStep } from '@mastra/core/workflow'
import { z } from 'zod'

const summarize = createStep({
  id: 'summarize',
  inputSchema: z.object({ text: z.string() }),
  outputSchema: z.object({ summary: z.string() }),
  execute: async ({ inputData, mastra }) => {
    const agent = mastra.getAgent('summarizer')
    const res = await agent.generate(`Summarize: ${inputData.text}`)
    return { summary: res.text }
  },
})

const workflow = createWorkflow({
  id: 'summarize-workflow',
  inputSchema: z.object({ text: z.string() }),
  outputSchema: z.object({ summary: z.string() }),
}).then(summarize).commit()  // .commit() is required!

const run = workflow.createRun()
const result = await run.start({ inputData: { text: 'Long article...' } })
if (result.status === 'success') console.log(result.result)

import { Memory } from '@mastra/memory'
import { LibSQLStore, LibSQLVector } from '@mastra/libsql'

const memory = new Memory({
  storage: new LibSQLStore({ id: 'mem', url: 'file:./local.db' }),
  vector: new LibSQLVector({ id: 'vec', url: 'file:./local.db' }),
  options: {
    lastMessages: 20,
    semanticRecall: { topK: 3, messageRange: 2 },
    workingMemory: { enabled: true, template: '# User\n- Name:\n- Preferences:' },
  },
})

const agent = new Agent({ id: 'mem-agent', model: 'openai/gpt-4.1', memory })

// Use with thread context
await agent.generate('Remember my name is Alice', {
  memory: { thread: { id: 'thread-1' }, resource: 'user-123' },
})

import { MCPClient } from '@mastra/mcp'

const mcp = new MCPClient({
  id: 'my-mcp',
  servers: {
    github: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
    custom: { url: new URL('https://my-mcp-server.com/sse') },
  },
})

const agent = new Agent({
  id: 'mcp-agent',
  model: 'openai/gpt-4.1',
  tools: await mcp.listTools(),  // static - fixed at init
})

// For multi-user (dynamic credentials per request):
const res = await agent.generate(prompt, {
  toolsets: await mcp.listToolsets(),
})
await mcp.disconnect()

mastra dev              # Dev server + Studio at localhost:4111
mastra build            # Bundle to .mastra/output/
mastra build --studio   # Include Studio UI in build
mastra start            # Serve production build
mastra lint             # Validate project structure
mastra migrate          # Run DB migrations