Mastra Client SDK - Hướng dẫn sử dụng và API Reference

Trust: ★★★☆☆ (0.90) · 0 validations · factual

Published: 2026-05-09 · Source: crawler_authoritative

Tình huống

Tài liệu kỹ thuật về Mastra Client SDK - một thư viện TypeScript/JavaScript để tương tác với Mastra Server cho việc xây dựng ứng dụng AI agent.

Insight

Mastra Client SDK cung cấp interface type-safe để tương tác với Mastra Server từ môi trường client. SDK hỗ trợ nhiều API core: Agents (generate responses và stream conversations), Memory (quản lý conversation threads và message history), Tools (execute và manage tools), Workflows (trigger và track execution), Vectors (semantic search), Responses API, Conversations API (experimental), Logs, và Telemetry. Điểm quan trọng: SDK sử dụng native fetch API cho browser environments. Khi UI và Mastra API không cùng origin (khác host, subdomain, hoặc port), cần thêm credentials: ‘include’ để mang cookies theo mỗi request - nếu không sẽ nhận 401 responses dù đăng nhập thành công. Server cần có Access-Control-Allow-Origin cụ thể (không phải ’*’) và Access-Control-Allow-Credentials: true. Client tools cho phép agents trigger browser-side functionality như DOM manipulation, local storage access thông qua createTool() function.

Hành động

Bước 1: Cài đặt package với npm install @mastra/client-js@latest (hoặc pnpm/yarn/bun). Bước 2: Khởi tạo MastraClient với baseUrl (default localhost:4111). Bước 3: Với cross-origin requests, thêm credentials: ‘include’ và cấu hình CORS headers trên server. Bước 4: Sử dụng agent.generate() hoặc agent.stream() với string prompt hoặc message array có role và content. Bước 5: Với client tools, dùng createTool() với id, description, inputSchema (zod), outputSchema, và execute function. Bước 6: Để cancel requests, truyền AbortSignal vào constructor và gọi controller.abort(). Optional parameters: retries, backoffMs, maxBackoffMs, headers. Prerequisites: Node.js v22.13.0+, TypeScript v4.7+ nếu dùng TS.

Điều kiện áp dụng

Technical SDK documentation cho developers xây dựng AI agent applications. Không liên quan trực tiếp đến e-commerce platform operations.

---

Nội dung gốc (Original)

Mastra client SDK

The Mastra Client SDK provides a concise and type-safe interface for interacting with your 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:

npm install @mastra/client-js@latest

pnpm:

pnpm add @mastra/client-js@latest

Yarn:

yarn add @mastra/client-js@latest

Bun:

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.

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: Generate responses and stream conversations.
• Memory: Manage conversation threads and message history.
• Tools: Executed and managed tools.
• Workflows: Trigger workflows and track their execution.
• Vectors: Use vector embeddings for semantic search.
• Responses: Use Mastra Agents as a Responses API with an OpenAI-compatible, agent-backed interface. This API is currently experimental.
• Conversations: Work with the stored conversation threads and item history behind Mastra Agents as a Responses API. This API is currently experimental.
• Logs: View logs and debug system behavior.
• Telemetry: View app performance and trace activity.

Generating responses

Call .generate() with a string prompt:

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 for more information.

Streaming responses

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

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 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.

import { MastraClient } from '@mastra/client-js'
 
export const mastraClient = new MastraClient({
  retries: 3,
  backoffMs: 300,
  maxBackoffMs: 5000,
  headers: {
    'X-Development': 'true',
  },
})

Info: Visit MastraClient 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.

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. 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.

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.

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.

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 configured to return hex color codes, intended to work with the browser-based client tool defined above.

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.4',
})

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:

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 for development scenarios.
2. Environment Variables: Use environment variables for configuration.
3. Debugging: Enable detailed logging when needed.
4. Performance: Track application performance, telemetry, and traces.

Liên kết

• Nền tảng: Chung
• Nguồn: https://mastra.ai/docs/server/mastra-client

Xem thêm:

• Mastra Framework: Cấu trúc dự án mặc định và tổ chức thư mục
• Composite Auth - Kết Hợp Nhiều Nhà Cung Cấp Xác Thực Trong Mastra
• Mastra Skills - Cài đặt và sử dụng cho AI Agent
• Hướng Dẫn Chạy Experiments Trên Mastra.ai Để Đánh Giá Agent, Workflow và Scorer
• Hướng Dẫn Viết Skill Cho Claude Agent