@mastra/core/dist/docs/references/docs-server-mastra-client.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Mastra client SDK

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

## Prerequisites

Before you start local development, 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`)

> **Note:** 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:

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

```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)**: Generate responses and stream conversations.
- **[A2A](https://mastra.ai/docs/agents/a2a)**: Discover agents through agent cards and work with task-based A2A streams.
- **[Memory](https://mastra.ai/reference/client-js/memory)**: Manage conversation threads and message history.
- **[Tools](https://mastra.ai/reference/client-js/tools)**: Executed and managed tools.
- **[Workflows](https://mastra.ai/reference/client-js/workflows)**: Trigger workflows and track their execution.
- **[Vectors](https://mastra.ai/reference/client-js/vectors)**: Use vector embeddings for semantic search.
- **[Responses](https://mastra.ai/reference/client-js/responses)**: Use Mastra Agents as a Responses API with an OpenAI-compatible, agent-backed interface. This API is currently experimental.
- **[Conversations](https://mastra.ai/reference/client-js/conversations)**: Work with the stored conversation threads and item history behind Mastra Agents as a Responses API. This API is currently experimental.
- **[Logs](https://mastra.ai/reference/client-js/logs)**: View logs and debug system behavior.
- **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: View app performance and trace activity.

## Create and run stored workflows

Use `upsertStoredWorkflow()` to create or replace a persisted workflow definition. A successful upsert validates the complete definition, registers it with the running Mastra instance, and makes it available through the standard workflow execution API.

The following example shows the full lifecycle of a mapping workflow, from creation and inspection through execution and deletion:

```typescript
import { MastraClient } from '@mastra/client-js'
import type { UpsertStoredWorkflowParams } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
})

const definition = {
  id: 'greeting-workflow',
  description: 'Returns a greeting for the supplied name',
  inputSchema: {
    type: 'object',
    properties: { name: { type: 'string' } },
    required: ['name'],
  },
  outputSchema: {
    type: 'object',
    properties: { message: { type: 'string' } },
    required: ['message'],
  },
  graph: [
    {
      type: 'mapping',
      id: 'create-greeting',
      mapConfig: JSON.stringify({
        message: { template: 'Hello, ${initData.name}!' },
      }),
    },
  ],
} satisfies UpsertStoredWorkflowParams

await client.upsertStoredWorkflow(definition)

const storedWorkflow = client.getStoredWorkflow(definition.id)
const storedDefinition = await storedWorkflow.details()

const workflow = client.getWorkflow(storedDefinition.id)
const run = await workflow.createRun()
const result = await run.startAsync({ inputData: { name: 'Ada' } })

console.log(result)

await storedWorkflow.delete()
```

Use `listStoredWorkflows()` to list persisted definitions. Calling `upsertStoredWorkflow()` again with the same `id` replaces the stored definition and live workflow registration.

> **Warning:** Durable storage requires a configured storage adapter that supports the `workflowDefinitions` domain. Without that domain, Core can register a workflow in memory, but the server's stored-workflow API can't preserve it across restarts.
>
> Stored definitions support declarative agent, tool, mapping, nested workflow, parallel, foreach, sleep, sleep-until, conditional, and loop entries. They can't contain JavaScript closures. Conditional and loop logic must use the declarative predicate format, and referenced agents, tools, and nested workflows must already be registered.
>
> Authenticated servers require `stored-workflows:read` or `stored-workflows:write` for definition operations and `workflows:execute` to run the workflow.

## 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'
  }
}
```

> **Info:** 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) 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'
  }
}
```

> **Info:** 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) 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) for more configuration options.

## Credentials and session cookies

**Authenticate Mastra API calls with session cookies** when your UI and Mastra API aren't on the same origin, different host, subdomain, or port (for example Mastra Studio on one port and a custom server on another). Add **`credentials: 'include'`** to `MastraClient` so each request carries the cookies the user already has after sign-in. Skip this and you will often get **`401`** responses from Mastra even though login succeeded in the browser.

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

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

**Allow credentialed cross-origin requests on your server**, see [CORS: requests with credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#requests_with_credentials). You need a concrete `Access-Control-Allow-Origin` (not `*`) and `Access-Control-Allow-Credentials: true`, or the browser will block the call before it reaches Mastra.

**Using `@mastra/react`?** Wrap your app with `MastraReactProvider`, set `baseUrl` and `apiPrefix` to match your server, and rely on the default `credentials: 'include'`. Change `credentials` only when you want `same-origin` or `omit` behavior.

## 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 agent

This is a standard Mastra [agent](https://mastra.ai/docs/agents/overview) 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.6-sol',
})
```

## Use MastraClient on the server

You can also use `MastraClient` in server-side environments such as API routes, serverless functions, or actions. The usage remains the same, but you may need to recreate the response for 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**: Use [error handling](https://mastra.ai/reference/client-js/error-handling) for development scenarios.
2. **Environment Variables**: Use environment variables for configuration.
3. **Debugging**: Enable detailed [logging](https://mastra.ai/reference/client-js/logs) when needed.
4. **Performance**: Track application performance, [telemetry](https://mastra.ai/reference/client-js/telemetry), and traces.