Skip to Content
DocsDeploymentThe Mastra Client

Mastra Client SDK

The Mastra Client SDK provides a simple and type-safe interface for interacting with your Mastra Server from your client environment.

Development Requirements

To ensure smooth local development, make sure you have:

  • Node.js 18.x or later installed
  • TypeScript 4.7+ (if using TypeScript)
  • A modern browser environment with Fetch API support
  • Your local Mastra server running (typically on port 4111)

Installation

npm install @mastra/client-js

Initialize Mastra Client

To get started you’ll need to initialize your MastraClient with necessary parameters:

import { MastraClient } from "@mastra/client-js";
 
const client = new MastraClient({
  baseUrl: "http://localhost:4111", // Default Mastra development server port
});

Configuration Options

You can customize the client with various options:

const client = new MastraClient({
  // Required
  baseUrl: "http://localhost:4111",
 
  // Optional configurations for development
  retries: 3,           // Number of retry attempts
  backoffMs: 300,       // Initial retry backoff time
  maxBackoffMs: 5000,   // Maximum retry backoff time
  headers: {            // Custom headers for development
    "X-Development": "true"
  }
});

Example

Once your MastraClient is initialized you can start making client calls via the type-safe interface

// Get a reference to your local agent
const agent = client.getAgent("dev-agent-id");
 
// Generate responses
const response = await agent.generate({
  messages: [
    {
      role: "user",
      content: "Hello, I'm testing the local development setup!"
    }
  ]
});

Available Features

Mastra client exposes all resources served by the Mastra Server

  • Agents: Create and manage AI agents, generate responses, and handle streaming interactions
  • Memory: Manage conversation threads and message history
  • Tools: Access and execute tools available to agents
  • Workflows: Create and manage automated workflows
  • Vectors: Handle vector operations for semantic search and similarity matching

Best Practices

  1. Error Handling: Implement proper error handling for development scenarios
  2. Environment Variables: Use environment variables for configuration
  3. Debugging: Enable detailed logging when needed
// Example with error handling and logging
try {
  const agent = client.getAgent("dev-agent-id");
  const response = await agent.generate({
    messages: [{ role: "user", content: "Test message" }]
  });
  console.log("Response:", response);
} catch (error) {
  console.error("Development error:", error);
}
Serverless PlatformsLogging