# Mastra Client SDK

The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/server/mastra-server/llms.txt) from your client environment.

## Prerequisites

To ensure smooth local development, make sure you have:

- Node.js `v22.13.0` or later
- TypeScript `v4.7` or higher (if using TypeScript)
- Your local Mastra server running (typically on port `4111`)

## Usage

The Mastra Client SDK is designed for browser environments and uses the native `fetch` API for making HTTP requests to your Mastra server.

## Installation

To use the Mastra Client SDK, install the required dependencies:

```bash
npm install @mastra/client-js@latest
```

```bash
pnpm add @mastra/client-js@latest
```

```bash
yarn add @mastra/client-js@latest
```

```bash
bun add @mastra/client-js@latest
```

### Initialize the `MastraClient`

Once initialized with a `baseUrl`, `MastraClient` exposes a type-safe interface for calling agents, tools, and workflows.

```typescript
import { MastraClient } from "@mastra/client-js";

export const mastraClient = new MastraClient({
  baseUrl: process.env.MASTRA_API_URL || "http://localhost:4111",
});
```

## Core APIs

The Mastra Client SDK exposes all resources served by the Mastra Server

- **[Agents](https://mastra.ai/reference/client-js/agents/llms.txt)**: Generate responses and stream conversations.
- **[Memory](https://mastra.ai/reference/client-js/memory/llms.txt)**: Manage conversation threads and message history.
- **[Tools](https://mastra.ai/reference/client-js/tools/llms.txt)**: Executed and managed tools.
- **[Workflows](https://mastra.ai/reference/client-js/workflows/llms.txt)**: Trigger workflows and track their execution.
- **[Vectors](https://mastra.ai/reference/client-js/vectors/llms.txt)**: Use vector embeddings for semantic search.
- **[Logs](https://mastra.ai/reference/client-js/logs/llms.txt)**: View logs and debug system behavior.
- **[Telemetry](https://mastra.ai/reference/client-js/telemetry/llms.txt)**: Monitor app performance and trace activity.

## Generating responses

Call `.generate()` with a string prompt:

```typescript
import { mastraClient } from "lib/mastra-client";

const testAgent = async () => {
  try {
    const agent = mastraClient.getAgent("testAgent");

    const response = await agent.generate("Hello");

    console.log(response.text);
  } catch (error) {
    return "Error occurred while generating response";
  }
};
```

You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents/llms.txt) for more information.

## Streaming responses

Use `.stream()` for real-time responses with a string prompt:

```typescript
import { mastraClient } from "lib/mastra-client";

const testAgent = async () => {
  try {
    const agent = mastraClient.getAgent("testAgent");

    const stream = await agent.stream("Hello");

    stream.processDataStream({
      onTextPart: (text) => {
        console.log(text);
      },
    });
  } catch (error) {
    return "Error occurred while generating response";
  }
};
```

You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents/llms.txt) for more information.

## Configuration options

`MastraClient` accepts optional parameters like `retries`, `backoffMs`, and `headers` to control request behavior. These parameters are useful for controlling retry behavior and including diagnostic metadata.

```typescript
import { MastraClient } from "@mastra/client-js";

export const mastraClient = new MastraClient({
  retries: 3,
  backoffMs: 300,
  maxBackoffMs: 5000,
  headers: {
    "X-Development": "true",
  },
});
```

Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client/llms.txt) for more configuration options.

## Adding request cancelling

`MastraClient` supports request cancellation using the standard Node.js `AbortSignal` API. Useful for canceling in-flight requests, such as when users abort an operation or to clean up stale network calls.

Pass an `AbortSignal` to the client constructor to enable cancellation across all requests.

```typescript
import { MastraClient } from "@mastra/client-js";

export const controller = new AbortController();

export const mastraClient = new MastraClient({
  baseUrl: process.env.MASTRA_API_URL || "http://localhost:4111",
  abortSignal: controller.signal,
});
```

### Using the `AbortController`

Calling `.abort()` will cancel any ongoing requests tied to that signal.

```typescript
import { mastraClient, controller } from "lib/mastra-client";

const handleAbort = () => {
  controller.abort();
};
```

## Client tools

Define tools directly in client-side applications using the `createTool()` function. Pass them to agents via the `clientTools` parameter in `.generate()` or `.stream()` calls.

This lets agents trigger browser-side functionality such as DOM manipulation, local storage access, or other Web APIs, enabling tool execution in the user's environment rather than on the server.

```typescript
import { createTool } from "@mastra/client-js";
import { z } from "zod";

const handleClientTool = async () => {
  try {
    const agent = mastraClient.getAgent("colorAgent");

    const colorChangeTool = createTool({
      id: "color-change-tool",
      description: "Changes the HTML background color",
      inputSchema: z.object({
        color: z.string(),
      }),
      outputSchema: z.object({
        success: z.boolean(),
      }),
      execute: async (inputData) => {
        const { color } = inputData;

        document.body.style.backgroundColor = color;
        return { success: true };
      },
    });

    const response = await agent.generate("Change the background to blue", {
      clientTools: { colorChangeTool },
    });

    console.log(response);
  } catch (error) {
    console.error(error);
  }
};
```

### Client tool's agent

This is a standard Mastra [agent](https://mastra.ai/docs/agents/overview/llms.txt) configured to return hex color codes, intended to work with the browser-based client tool defined above.

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

export const colorAgent = new Agent({
  id: "color-agent",
  name: "Color Agent",
  instructions: `You are a helpful CSS assistant.
  You can change the background color of web pages.
  Respond with a hex reference for the color requested by the user`,
  model: "openai/gpt-5.1",
});
```

## Server-side environments

You can also use `MastraClient` in server-side environments such as API routes, serverless functions or actions. The usage will broadly remain the same but you may need to recreate the response to your client:

```typescript
export async function action() {
  const agent = mastraClient.getAgent("testAgent");

  const stream = await agent.stream("Hello");

  return new Response(stream.body);
}
```

## Best practices

1. **Error Handling**: Implement proper [error handling](https://mastra.ai/reference/client-js/error-handling/llms.txt) for development scenarios.
2. **Environment Variables**: Use environment variables for configuration.
3. **Debugging**: Enable detailed [logging](https://mastra.ai/reference/client-js/logs/llms.txt) when needed.
4. **Performance**: Monitor application performance, [telemetry](https://mastra.ai/reference/client-js/telemetry/llms.txt) and traces.