mastra-helper

What this skill does

# Mastra Helper Agent

## What's New in Mastra v1 (2025)

- **Stable API**: v1 beta signals production-readiness with no breaking changes planned
- **Multi-model support**: OpenAI, Anthropic, Gemini, Llama, and more through AI SDK integration
- **Human-in-the-loop**: Suspend/resume with persistent state across sessions
- **MCP integration**: Model Context Protocol for universal tool sharing
- **Built-in evals**: Automated testing with model-graded and rule-based scoring
- **Enhanced memory**: Working memory, semantic recall, and conversation history

## Installation

```bash
# Create new Mastra project
npm create mastra@latest

# Or add to existing project
npm install @mastra/core
```

## Core Concepts

Mastra provides:

1. **Agents**: Autonomous LLM-powered systems with tools
2. **Tools**: Functions agents can call to interact with external systems
3. **Workflows**: Graph-based orchestration for multi-step processes
4. **Memory**: Context management across conversations
5. **MCP**: Model Context Protocol for tool/resource sharing

## Creating Agents

### Basic Agent

```typescript
import { Agent } from "@mastra/core/agent";

export const myAgent = new Agent({
  name: "my-agent",
  instructions: "You are a helpful assistant that answers questions clearly.",
  model: "openai/gpt-4o-mini",
});
```

### Agent with Tools

```typescript
import { Agent } from "@mastra/core/agent";
import { weatherTool, searchTool } from "./tools";

export const assistantAgent = new Agent({
  name: "assistant",
  instructions: `You are a helpful assistant.
    Use the weather tool to check weather conditions.
    Use the search tool to find information.`,
  model: "anthropic/claude-sonnet-4-20250514",
  tools: { weatherTool, searchTool },
});
```

### Agent Configuration Options

```typescript
export const agent = new Agent({
  name: "configured-agent",
  instructions: "Your system prompt here",
  model: "openai/gpt-4o",

  // Limit sequential LLM calls (default: 5)
  maxSteps: 10,

  // Callback after each step
  onStepFinish: async ({ step, result }) => {
    console.log(`Step ${step} completed:`, result);
  },

  // Callback after completion
  onFinish: async ({ result, usage }) => {
    console.log("Total tokens:", usage.totalTokens);
  },
});
```

### Dynamic Configuration with RuntimeContext

```typescript
import { Agent, RuntimeContext } from "@mastra/core/agent";

export const agent = new Agent({
  name: "dynamic-agent",

  // Dynamic model selection
  model: async ({ runtimeContext }) => {
    const tier = runtimeContext.get("user-tier");
    return tier === "enterprise" ? "openai/gpt-4o" : "openai/gpt-4o-mini";
  },

  // Dynamic instructions
  instructions: async ({ runtimeContext }) => {
    const lang = runtimeContext.get("language");
    return `Respond in ${lang}. Be helpful and concise.`;
  },
});

// Usage
const ctx = new RuntimeContext();
ctx.set("user-tier", "enterprise");
ctx.set("language", "Spanish");

await agent.generate("Hello!", { runtimeContext: ctx });
```

## Using Agents

### Generate Text

```typescript
const result = await agent.generate("What's the weather in Tokyo?");
console.log(result.text);
```

### Stream Response

```typescript
const stream = await agent.stream("Tell me a story");

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}
```

### Structured Output

```typescript
import { z } from "zod";

const WeatherSchema = z.object({
  location: z.string(),
  temperature: z.number(),
  conditions: z.string(),
  humidity: z.number(),
});

const result = await agent.generate("Get weather for NYC", {
  output: WeatherSchema,
});

// result.object is typed: { location, temperature, conditions, humidity }
console.log(result.object.temperature);
```

## Creating Tools

### Basic Tool

```typescript
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "weather-tool",
  description: "Fetches current weather for a location",

  inputSchema: z.object({
    location: z.string().describe("City name or coordinates"),
  }),

  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
    humidity: z.number(),
  }),

  execute: async ({ context }) => {
    const { location } = context;

    // Fetch weather from API
    const response = await fetch(`https://api.weather.com/${location}`);
    const data = await response.json();

    return {
      temperature: data.temp,
      conditions: data.weather,
      humidity: data.humidity,
    };
  },
});
```

### Tool with Runtime Context

```typescript
export const apiTool = createTool({
  id: "api-tool",
  description: "Makes authenticated API calls",

  inputSchema: z.object({
    endpoint: z.string(),
  }),

  outputSchema: z.object({
    data: z.any(),
  }),

  execute: async ({ context, runtimeContext }) => {
    const apiKey = runtimeContext.get("api-key");

    const response = await fetch(context.endpoint, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    return { data: await response.json() };
  },
});
```

## Workflows

### Creating Steps

```typescript
import { createStep } from "@mastra/core/workflows";
import { z } from "zod";

const fetchDataStep = createStep({
  id: "fetch-data",

  inputSchema: z.object({
    userId: z.string(),
  }),

  outputSchema: z.object({
    user: z.object({
      name: z.string(),
      email: z.string(),
    }),
  }),

  execute: async ({ inputData }) => {
    const user = await db.users.findUnique({ where: { id: inputData.userId } });
    return { user };
  },
});
```

### Creating Workflows

```typescript
import { createWorkflow } from "@mastra/core/workflows";

const userWorkflow = createWorkflow({
  id: "user-workflow",

  inputSchema: z.object({
    userId: z.string(),
  }),

  outputSchema: z.object({
    result: z.string(),
  }),
})
  .then(fetchDataStep)
  .then(processStep)
  .then(notifyStep)
  .commit();
```

### Branching

```typescript
const workflow = createWorkflow({ id: "branching-example", ... })
  .then(validateStep)
  .branch([
    // Condition: user is premium
    [async ({ inputData }) => inputData.isPremium, premiumProcessStep],
    // Condition: user is basic
    [async ({ inputData }) => !inputData.isPremium, basicProcessStep],
  ])
  .then(finalizeStep)
  .commit();
```

### Parallel Execution

```typescript
const workflow = createWorkflow({ id: "parallel-example", ... })
  .then(initialStep)
  .parallel([
    fetchFromApiA,
    fetchFromApiB,
    fetchFromApiC,
  ])
  .then(mergeResultsStep)
  .commit();
```

### Loops

```typescript
const workflow = createWorkflow({ id: "loop-example", ... })
  // Do-until loop
  .dountil(
    retryStep,
    async ({ inputData }) => inputData.success === true,
    { maxIterations: 5 }
  )

  // Do-while loop
  .dowhile(
    processItemStep,
    async ({ inputData }) => inputData.hasMore,
    { maxIterations: 100 }
  )

  // For-each loop
  .foreach(
    processItemStep,
    async ({ inputData }) => inputData.items,
    { concurrency: 3 }
  )
  .commit();
```

### Suspend and Resume (Human-in-the-Loop)

```typescript
const approvalStep = createStep({
  id: "await-approval",

  inputSchema: z.object({ requestId: z.string() }),
  outputSchema: z.object({ approved: z.boolean() }),

  resumeSchema: z.object({
    approved: z.boolean(),
    approverNotes: z.string().optional(),
  }),

  execute: async ({ inputData, suspend, resumeData }) => {
    // If we have resume data, use it
    if (resumeData) {
      return { approved: resumeData.approved };
    }

    // Otherwise, suspend and wait for human input
    await suspend({ requestId: inputData.requestId });
  },
});

// Resume suspended workflow
await workflow.resume({
  runId: "run-123",
  stepId: "await-approval",
  resumeData: { approved: true, approverNotes: "Looks good!" },
});
```

### Running Workflows

```typescript
// Start and wait for completion
const result = await workflow.start({
  inputData: { userId: "use