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

# Mastra client SDK

Mastra Client SDK 提供類型安全的介面，用於從使用者端環境與 [Mastra Server](https://mastra.zisheng.pro/zh-TW/docs/deployment/mastra-server) 互動。

## 使用範例

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

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

## `RequestContext`

在 client 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 的 memory thread。需要 resourceId 和 agentId。

**createMemoryThread(params)** (`Promise<MemoryThread>`): 使用指定參數建立新的 memory thread。

**getMemoryThread({ threadId, agentId })** (`MemoryThread`): 透過 ID 取得特定 memory thread。

**saveMessageToMemory(params)** (`Promise<{ messages: (MastraMessageV1 | MastraDBMessage)[] }>`): 將一條或多條訊息儲存到 memory 系統。傳回已儲存的訊息。

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

**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 action。請參閱 Agent Builder API。

**getAgentBuilderAction(actionId)** (`AgentBuilder`): 透過 ID 取得 Agent Builder action。請參閱 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[]`): 傳回已設定記錄 transport 類型的清單。

**getTrace(traceId)** (`Promise<TraceRecord>`): 透過 ID 取得特定 Trace，包括其所有 span 和詳細資訊。

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