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

# Mastra client SDK

Mastra Client SDK 提供类型安全的接口，用于从客户端环境与 [Mastra Server](https://mastra.zisheng.pro/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。