> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Mastra client SDK

Mastra Client SDK 提供型別安全的介面，讓你的客戶端環境可與 [Mastra Server](https://mastra.zisheng.pro/zh-HK/docs/deployment/mastra-server) 互動。

## 使用範例

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

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111/',
})
```

## `RequestContext`

在客戶端 SDK 使用 `RequestContext` 時，請從 `@mastra/client-js` 匯入。

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

const client = new MastraClient({
  baseUrl: 'http://localhost:4111/',
})

const requestContext = new RequestContext()
requestContext.set('userId', 'user-123')

const agent = client.getAgent('support-agent')

const response = await agent.generate('Summarize this ticket', {
  requestContext,
})
```

你亦可將 `requestContext` 以 `Record<string, any>` 傳入。

## 參數

**baseUrl** (`string`): Mastra API 的基礎 URL。所有請求均會相對於此 URL 傳送。

**retries** (`number`): 請求失敗後，在擲回錯誤前重試的次數。 (Default: `3`)

**backoffMs** (`number`): 重試失敗請求前的初始延遲（毫秒）。每次重試都會將此值加倍（指數退避）。 (Default: `300`)

**maxBackoffMs** (`number`): 最長退避時間（毫秒），防止兩次重試之間等候過久。 (Default: `5000`)

**headers** (`Record<string, string>`): 包含每次請求都要加入的自訂 HTTP 標頭之物件。

**credentials** (`"omit" | "same-origin" | "include"`): 請求的憑證模式。詳情請參閱 https\://developer.mozilla.org/en-US/docs/Web/API/Request/credentials。

## 方法

**listAgents()** (`Promise<Record<string, GetAgentResponse>>`): 傳回所有可用的 Agent 實例。

**getAgent(agentId)** (`Agent`): 按 ID 取得指定 Agent 實例。

**listMemoryThreads(params)** (`Promise<StorageThreadType[]>`): 取得指定資源及 Agent 的記憶執行緒。必須提供 resourceId 及 agentId。

**createMemoryThread(params)** (`Promise<MemoryThread>`): 使用指定參數建立新的記憶執行緒。

**getMemoryThread({ threadId, agentId })** (`MemoryThread`): 按 ID 取得指定記憶執行緒。

**saveMessageToMemory(params)** (`Promise<{ messages: (MastraMessageV1 | MastraDBMessage)[] }>`): 將一則或多則訊息儲存至記憶系統，並傳回已儲存的訊息。

**getMemoryStatus()** (`Promise<MemoryStatus>`): 傳回記憶系統目前的狀態。

**listTools()** (`Record<string, Tool>`): 傳回所有可用的 Tool。

**getTool(toolId)** (`Tool`): 按 ID 取得指定 Tool 實例。

**listWorkflows()** (`Record<string, Workflow>`): 傳回所有可用的 Workflow 實例。

**getWorkflow(workflowId)** (`Workflow`): 按 ID 取得指定 Workflow 實例。

**getAgentBuilderActions()** (`Promise<Record<string, WorkflowInfo>>`): 傳回所有可用的 Agent Builder 動作。請參閱 Agent Builder API。

**getAgentBuilderAction(actionId)** (`AgentBuilder`): 按 ID 取得 Agent Builder 動作。請參閱 Agent Builder API。

**responses** (`Responses`): 提供 OpenAI 形式的 Responses API 輔助函數，包括 create()、retrieve()、stream() 及 delete()。

**conversations** (`Conversations`): 提供對話輔助函數，包括 create()、retrieve()、delete() 及 items.list()。

**getVector(vectorName)** (`MastraVector`): 按名稱傳回向量儲存庫實例。

**listLogs(params)** (`Promise<LogEntry[]>`): 取得符合指定篩選條件的系統日誌。

**getLog(params)** (`Promise<LogEntry>`): 按 ID 或篩選條件取得指定日誌項目。

**listLogTransports()** (`string[]`): 傳回已設定的日誌傳輸類型清單。

**getTrace(traceId)** (`Promise<TraceRecord>`): 按 ID 取得指定 Trace，包括其所有 span 及詳情。

**getTraces(params)** (`Promise<GetTracesResponse>`): 取得可選擇篩選的 Trace 根 span 分頁清單。使用 getTrace() 取得包含所有 span 的完整 Trace。