Mastra client SDK

Mastra Client SDK 提供型別安全的介面，讓你的客戶端環境可與 Mastra Server 互動。

使用範例

lib/mastra/mastra-client.ts

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

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

RequestContext

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

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

= 3

請求失敗後，在擲回錯誤前重試的次數。

backoffMs?:

number

= 300

重試失敗請求前的初始延遲（毫秒）。每次重試都會將此值加倍（指數退避）。

maxBackoffMs?:

number

= 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。