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

# Session

> **Beta:** `AgentController` 功能目前處於 beta 階段，在脫離 beta 狀態前，次要版本可能會有破壞性變更。

`Session` 是一個資源及可選作用域的隔離執行環境。它擁有自己的事件匯流排、執行緒綁定、狀態、模式及模型選擇、執行控制、核准、暫停、後續訊息和顯示狀態。[`AgentController`](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/agent-controller-class) 提供共用 Agent、配置、儲存空間、Workspace 和服務。

請透過 `controller.createSession()` 建立 Session。直接建構及控制器接線方法並非應用程式 API。

如需概念介紹，請參閱 [AgentController 概覽](https://mastra.zisheng.pro/zh-HK/docs/harness/agent-controller)。

## 使用範例

以下範例使用受支援的控制器至 Session 流程。

```typescript
await controller.init()

const session = await controller.createSession({ resourceId: 'project-42' })
const unsubscribe = session.subscribe(event => {
  if (event.type === 'display_state_changed') {
    render(event.displayState)
  }
})

await session.sendMessage({ content: 'Review the current project.' })
unsubscribe()
```

## 屬性

Session 由多個子物件組成，每個子物件各自擁有一個每次對話狀態領域。

**identity** (`SessionIdentity`): 對話的穩定 Session、擁有者及資源身分。請參閱下方的身分方法。

**thread** (`SessionThread`): 使用中的執行緒綁定，以及執行緒／訊息讀取操作。請參閱下方的執行緒方法。

**mode** (`SessionMode`): 使用中的模式選擇。請參閱下方的模式方法。

**model** (`SessionModel`): 使用中的模型選擇，包括按模式持久保存。請參閱下方的模型方法。

**om** (`SessionOM`): 觀察式記憶的觀察者及反思者模型設定。

**permissions** (`SessionPermissions`): 在 Session 狀態中表示的 Tool 及類別權限政策。

**subagents** (`SessionSubagents`): 全域及按 Agent 類型的子 Agent 模型選擇。

**run** (`SessionRun`): 進行中執行的執行及 Trace 身分，以及中止狀態。請參閱下方的執行方法。

**stream** (`SessionStream`): Agent 執行緒串流的即時訂閱。請參閱下方的串流方法。

**suspensions** (`SessionSuspensions`): 已停放並等待恢復的互動式 Tool 呼叫。請參閱下方的暫停方法。

**followUps** (`SessionFollowUps`): 執行進行期間提交的訊息佇列。請參閱下方的後續訊息方法。

**approval** (`SessionApproval`): 待處理的 Tool 核准關卡。請參閱下方的核准方法。

**displayState** (`SessionDisplayState`): UI 用於呈現畫面的標準 AgentControllerDisplayState 快照。請參閱下方的顯示狀態方法。

**state** (`AgentControllerRequestState<TState>`): 經結構描述驗證、由 Session 擁有的 AgentController 狀態。請參閱下方的狀態方法。

**browser** (`MastraBrowser | undefined`): 此 Session 的瀏覽器自動化執行個體。在建立時透過 createSession 設定，或取自 AgentController 配置的預設值。未配置瀏覽器時為 undefined。

## 方法

### 身分及事件

#### `getTags()`

傳回建立 Session 時所提供標籤的副本。

```typescript
const tags = session.getTags()
```

傳回：`Record<string, string>`

#### `subscribe(listener)`

訂閱此 Session 的隔離事件匯流排。此方法會傳回取消訂閱函數。

```typescript
const unsubscribe = session.subscribe(event => {
  console.log(event.type)
})

unsubscribe()
```

傳回：`() => void`

### 訊息及執行控制

#### `sendMessage({ content, files?, requestContext? })`

傳送使用者訊息。如沒有使用中的執行緒，Session 會先建立一個。

```typescript
await session.sendMessage({
  content: 'Summarize this file.',
  files: [{ data: fileContents, mediaType: 'text/plain', filename: 'notes.txt' }],
})
```

#### `steer({ content, requestContext? })`

將引導內容排入使用中執行的佇列。

```typescript
await session.steer({ content: 'Focus on the failing tests.' })
```

#### `followUp({ content, requestContext? })`

在執行進行時將後續訊息排入佇列，或在閒置時立即傳送。

```typescript
await session.followUp({ content: 'Then propose a fix.' })
```

#### `getCurrentRunId()`

傳回使用中的串流執行識別碼、追蹤中的執行識別碼，或在閒置時傳回 `null`。

```typescript
const runId = session.getCurrentRunId()
```

傳回：`string | null`

#### `abort()`

中止使用中的執行，並清除待處理的暫停顯示狀態。

```typescript
session.abort()
```

### Workspace

#### `getWorkspace()`

傳回為此 Session 解析的 Workspace。這會保留 Session 層級覆寫，以及從 Session 作用域選取的 Workspace。

```typescript
const workspace = session.getWorkspace()
const skill = await workspace.skills?.get('code-review')
```

傳回：`Workspace`

### Session 授權

Session 作用域的授權會自動核准 Tool，而不作提示。授權是暫時性的：Session 重新啟動時便會重設，而且永不持久保存。

#### `grantCategory(category)`

為目前 Session 授予一個 Tool 類別。此類別中的 Tool 將獲自動核准。

```typescript
session.grantCategory('edit')
```

#### `grantTool(toolName)`

為目前 Session 授予特定 Tool。

```typescript
session.grantTool('mastra_workspace_execute_command')
```

#### `getGrants()`

傳回目前已授予的類別及 Tool。

```typescript
const grants = session.getGrants()
// { categories: string[], tools: string[] }
```

#### `hasCategoryGrant(category)`

傳回某類別是否有記憶體內的 Session 授權。

```typescript
const allowed = session.hasCategoryGrant('edit')
```

傳回：`boolean`

#### `hasToolGrant(toolName)`

傳回某 Tool 是否有記憶體內的 Session 授權。

```typescript
const allowed = session.hasToolGrant('write_file')
```

傳回：`boolean`

### Tool 核准

#### `resolveToolApproval(toolName)`

在套用明確的 Tool 規則、Session 授權及類別規則後，傳回有效政策。

```typescript
const policy = session.resolveToolApproval('execute_command')
```

傳回：`PermissionPolicy`

#### `respondToToolApproval({ decision, toolCallId?, requestContext?, declineContext? })`

回應由 `tool_approval_required` 事件引發的待處理 Tool 核准要求。傳入 `always_allow_category`，亦會授予該 Tool 的整個類別，直至 Session 結束。

```typescript
session.respondToToolApproval({ decision: 'approve' })
session.respondToToolApproval({ decision: 'decline' })
session.respondToToolApproval({ decision: 'always_allow_category' })
```

#### `respondToToolSuspension({ resumeData, toolCallId?, requestContext? })`

使用應用程式提供的資料恢復已暫停的 Tool。如有多個 Tool 呼叫暫停，請提供 `toolCallId`。

```typescript
await session.respondToToolSuspension({
  toolCallId: event.toolCallId,
  resumeData: ['src'],
})
```

對於 `submit_plan`，請傳入 `{ action: 'approved' }` 或 `{ action: 'rejected', feedback }`。在 Tool 恢復前，核准可切換至由 `transitionsTo` 配置的模式。

### Token 使用量

#### `getTokenUsage()`

傳回使用中執行緒的累計 token 使用量副本。

```typescript
const usage = session.getTokenUsage()
// { promptTokens, completionTokens, totalTokens, ... }
```

## 身分

`session.identity` 擁有對話的穩定識別碼：資源 ID、Session `id` 及 `ownerId`。`id` 和 `ownerId` 在 Session 的生命週期內保持不變，切換資源 ID 時亦不會變更。它們對應儲存空間中 `SessionRecord` 的 `id` 及 `ownerId` 欄位。

### `session.identity.getId()`

傳回穩定的 Session 識別碼。

```typescript
const sessionId = session.identity.getId()
```

### `session.identity.getOwnerId()`

傳回 Session 的穩定擁有者識別碼。

```typescript
const ownerId = session.identity.getOwnerId()
```

### `session.identity.getResourceId()`

傳回目前資源 ID。

```typescript
const resourceId = session.identity.getResourceId()
```

### `session.identity.getDefaultResourceId()`

傳回建立 Session 時所使用的資源 ID。

```typescript
const defaultResourceId = session.identity.getDefaultResourceId()
```

如要變更資源 ID，請使用 [`controller.setResourceId()`](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/agent-controller-class)；此方法亦會清除使用中的執行緒。切換資源不會影響 Session `id` 和 `ownerId`。

## 執行緒

`session.thread` 擁有使用中的執行緒綁定及資源作用域的執行緒操作。如已配置儲存空間，已儲存的執行緒及訊息可在重新建立控制器後繼續保留；即時 Session 及其事件匯流排則不能。

### `session.thread.create({ title?, id? })`

建立執行緒、將 Session 綁定至該執行緒，並開啟其事件串流。

```typescript
const thread = await session.thread.create({
  id: 'thread-7',
  title: 'Investigate login failure',
})
```

傳回：`Promise<AgentControllerThread>`

### `session.thread.rename({ title })`

重新命名使用中的已儲存執行緒。

```typescript
await session.thread.rename({ title: 'Fix login failure' })
```

### `session.thread.clone({ sourceThreadId?, title?, resourceId? })`

複製自己擁有的執行緒及其訊息，然後將 Session 綁定至副本。

```typescript
const clone = await session.thread.clone({
  sourceThreadId: 'thread-7',
  title: 'Alternative approach',
})
```

傳回：`Promise<AgentControllerThread>`

### `session.thread.switch({ threadId, emitEvent? })`

切換至自己擁有的已儲存執行緒，並載入其模式、模型及觀察式記憶設定。

```typescript
await session.thread.switch({ threadId: 'thread-8' })
```

### `session.thread.delete({ threadId })`

刪除自己擁有的執行緒。刪除使用中的執行緒亦會清除目前綁定。

```typescript
await session.thread.delete({ threadId: 'thread-8' })
```

### `session.thread.getId()`

傳回使用中的執行緒 ID；如沒有綁定執行緒，則傳回 `null`。

```typescript
const threadId = session.thread.getId()
```

### `session.thread.list(options?)`

列出儲存空間中的執行緒。預設只會傳回目前資源的執行緒，並隱藏暫時分叉的子 Agent 執行緒。

```typescript
const threads = await session.thread.list()
const allThreads = await session.thread.list({ allResources: true })
const everything = await session.thread.list({ includeForkedSubagents: true })
```

### `session.thread.getById({ threadId })`

傳回指定 ID 的單一執行緒；如不存在，則傳回 `null`。

```typescript
const thread = await session.thread.getById({ threadId: 'thread-abc123' })
```

### `session.thread.listActiveMessages(options?)`

擷取使用中執行緒的訊息。如沒有綁定執行緒，則傳回空陣列。

```typescript
const messages = await session.thread.listActiveMessages({ limit: 50 })
```

### `session.thread.listMessages({ threadId, limit? })`

擷取指定執行緒的訊息。

```typescript
const messages = await session.thread.listMessages({ threadId: 'thread-abc123' })
```

訊息讀取方法 `listActiveMessages`、`listMessages` 和 `firstUserMessage` 會傳回 `MastraDBMessage` 物件，而 `firstUserMessages` 則傳回以執行緒 ID 為鍵的 `Map<string, MastraDBMessage>`。每則訊息都有 `role`、`id`、`createdAt`，以及包含 `content.format` 和 `content.parts` 陣列的 `content` 物件。從 `content.parts` 讀取文字、推理、Tool 呼叫及附件。系統提示和通知等訊號會以 `role: 'signal'` 的獨立訊息傳回。

### `session.thread.firstUserMessage({ threadId })`

擷取執行緒的第一則使用者訊息；如沒有，則傳回 `null`。

```typescript
const firstMsg = await session.thread.firstUserMessage({
  threadId: 'thread-abc123',
})
```

### `session.thread.firstUserMessages({ threadIds })`

一次擷取多個執行緒的第一則使用者訊息，並以 map 傳回。

```typescript
const firstByThread = await session.thread.firstUserMessages({
  threadIds: ['thread-a', 'thread-b'],
})
```

### `session.thread.getSetting({ key })`

從使用中執行緒的中繼資料讀取設定。

```typescript
const value = await session.thread.getSetting({ key: 'omThreshold' })
```

### `session.thread.setSetting({ key, value })`

將設定寫入使用中執行緒的中繼資料。

```typescript
await session.thread.setSetting({ key: 'omThreshold', value: 0.8 })
```

### `session.thread.deleteSetting({ key })`

從使用中執行緒的中繼資料移除設定。

```typescript
await session.thread.deleteSetting({ key: 'omThreshold' })
```

## 模式

`session.mode` 擁有使用中的模式選擇。

### `session.mode.get()`

傳回使用中的模式 ID。

```typescript
const modeId = session.mode.get()
```

### `session.mode.resolve()`

傳回使用中模式的完整 `AgentControllerMode` 物件，並根據控制器所配置的模式進行解析。

```typescript
const mode = session.mode.resolve()
```

### `session.mode.switch({ modeId })`

切換至另一個模式。Session 會先儲存即將離開模式的模型，然後在使用中執行緒持久保存新模式。接着，它會還原新模式已選取或預設的模型。Session 會立即發出 `mode_changed`，並在模型解析後發出 `model_changed`。

```typescript
await session.mode.switch({ modeId: 'build' })
```

## 模型

`session.model` 擁有使用中的模型選擇，包括按模式保存的模型記憶。

### `session.model.get()`

傳回使用中的模型 ID。

```typescript
const modelId = session.model.get()
```

### `session.model.displayName()`

傳回使用中模型 ID 的最後一段，作為簡短顯示名稱。如未選取模型，則傳回 `'unknown'`。

```typescript
const name = session.model.displayName()
```

### `session.model.hasSelection()`

檢查目前是否已選取模型。

```typescript
if (session.model.hasSelection()) {
  // Ready to send messages
}
```

### `session.model.switch({ modelId, scope?, modeId? })`

切換使用中的模型。當 `scope` 為 `'thread'`（預設值）時，模型 ID 會持久保存為該模式的模型，以便切換回來時還原。此方法會向控制器的 `modelUseCountTracker` 報告選擇，並發出 `model_changed` 事件。

```typescript
// Set for the current session only
await session.model.switch({
  modelId: 'anthropic/claude-sonnet-4-6',
  scope: 'global',
})

// Persist to the current thread (default)
await session.model.switch({ modelId: 'anthropic/claude-sonnet-4-6' })
```

## 觀察式記憶

觀察式記憶的模型選擇按角色分組於 `session.om.observer` 和 `session.om.reflector` 下。兩個角色均公開相同方法。讀取時，如 Session 狀態已有設定，便傳回該值；否則回退至控制器的 `omConfig` 預設值。

### `session.om.observer.modelId()` / `session.om.reflector.modelId()`

傳回角色的模型 ID；如 Session 狀態及 `omConfig` 均未提供，則傳回 `undefined`。

```typescript
const observer = session.om.observer.modelId()
const reflector = session.om.reflector.modelId()
```

### `session.om.observer.threshold()` / `session.om.reflector.threshold()`

傳回角色以 token 計算的閾值（觀察者的觀察閾值，或反思者的反思閾值）；如未設定，則傳回 `undefined`。

```typescript
const observationThreshold = session.om.observer.threshold()
const reflectionThreshold = session.om.reflector.threshold()
```

### `session.om.observer.switchModel({ modelId })` / `session.om.reflector.switchModel({ modelId })`

切換角色的模型。此設定會持久保存至執行緒中繼資料，並發出 `om_model_changed` 事件。

```typescript
await session.om.observer.switchModel({
  modelId: 'anthropic/claude-haiku-4-5',
})
await session.om.reflector.switchModel({
  modelId: 'anthropic/claude-haiku-4-5',
})
```

### `session.om.observer.resolvedModel()` / `session.om.reflector.resolvedModel()`

透過已配置的模型閘道，將角色的模型 ID 解析為模型執行個體；如未設定模型 ID 或未配置解析器，則傳回 `undefined`。

```typescript
const observerModel = session.om.observer.resolvedModel()
const reflectorModel = session.om.reflector.resolvedModel()
```

## 權限

`session.permissions` 擁有 `session.state` 中表示的 Tool 核准政策：核准解析期間所查詢的各類別及各 Tool 規則。這些規則與 [Session 授權](#session-grants)所述的記憶體內授權不同。授權會隨即時 Session 重設。除非主機還原相應的 Session 狀態，否則權限規則不會持久保存。

### `session.permissions.getRules()`

傳回目前權限規則；如未設定，則傳回空規則（`{ categories: {}, tools: {} }`）。

```typescript
const rules = session.permissions.getRules()
// { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }
```

### `session.permissions.setForCategory({ category, policy })`

設定 Tool 類別的核准政策（`'allow' | 'ask' | 'deny'`）。變更持久保存至 Session 狀態後，Promise 便會解析。

```typescript
await session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
```

### `session.permissions.setForTool({ toolName, policy })`

設定特定 Tool 的核准政策。各 Tool 政策的優先級高於類別政策。持久保存後，Promise 便會解析。

```typescript
await session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
```

## 子 Agent

`session.subagents` 擁有子 Agent 配置。目前它在 `session.subagents.model` 下公開子 Agent 模型選擇。

### `session.subagents.model.get({ agentType? })`

傳回子 Agent 模型 ID。如有提供 `agentType`，會優先使用該類型的值，然後使用全域子 Agent 模型；如兩者均未設定，則傳回 `null`。

```typescript
const modelId = session.subagents.model.get({ agentType: 'explore' })
```

### `session.subagents.model.set({ modelId, agentType? })`

設定子 Agent 模型 ID。傳入 `agentType` 可設定按類型的覆寫值，省略則設定全域預設值。此設定會持久保存至執行緒設定，並發出 `subagent_model_changed` 事件。

```typescript
// Set the global subagent model
await session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })

// Set a per-type override
await session.subagents.model.set({
  modelId: 'anthropic/claude-haiku-4-5',
  agentType: 'explore',
})
```

## 執行

`session.run` 擁有進行中執行的執行及 Trace 身分，以及中止狀態。

### `session.run.getRunId()` / `getTraceId()`

傳回目前執行已儲存的執行 ID 及 Trace ID；閒置時傳回 `null`。

```typescript
const runId = session.run.getRunId()
const traceId = session.run.getTraceId()
```

### `session.run.isRunning()`

傳回目前是否有執行正在進行。

```typescript
if (session.run.isRunning()) {
  // A run is active
}
```

## 串流

`session.stream` 擁有 Agent 執行緒串流的即時訂閱及其去重鍵。

### `session.stream.activeRunId()`

傳回即時串流上使用中的執行 ID；如沒有開啟串流，則傳回 `null`。

```typescript
const runId = session.stream.activeRunId()
```

### `session.stream.isActive()`

傳回串流目前是否有使用中的執行。

```typescript
if (session.stream.isActive()) {
  // The current thread's stream is producing output
}
```

## 暫停

`session.suspensions` 擁有已停放並等待恢復的互動式 Tool 呼叫（例如 `ask_user` 和 `request_access`）。

### `session.suspensions.hasPending()`

傳回目前是否有任何 Tool 處於暫停狀態。

```typescript
if (session.suspensions.hasPending()) {
  // At least one interactive tool is waiting for a response
}
```

### `session.suspensions.has({ toolCallId })`

傳回特定 Tool 呼叫是否處於暫停狀態。

```typescript
const waiting = session.suspensions.has({ toolCallId: event.toolCallId })
```

使用 [`session.respondToToolSuspension()`](#tool-approvals) 恢復已暫停的 Tool。

## 後續訊息

`session.followUps` 擁有執行進行期間所提交訊息的 FIFO 佇列。

### `session.followUps.count()`

傳回已排入佇列的後續訊息數目。

```typescript
const queued = session.followUps.count()
```

### `session.followUps.isEmpty()`

傳回後續訊息佇列是否為空。

```typescript
if (!session.followUps.isEmpty()) {
  // Messages are waiting to be processed
}
```

## 核准

`session.approval` 擁有待處理的 Tool 核准關卡。

### `session.approval.isArmed()`

傳回目前是否有 Tool 正等待核准決定。

```typescript
if (session.approval.isArmed()) {
  // Show the approval prompt
}
```

使用 [`session.respondToToolApproval()`](#tool-approvals) 回應。

## 顯示狀態

`session.displayState` 擁有 UI 用於呈現畫面的標準 `AgentControllerDisplayState` 快照，以及讓它與每個 Session 事件保持同步的 reducer。

### `session.displayState.get()`

傳回目前的 `AgentControllerDisplayState` 快照，供 UI 呈現畫面。

```typescript
const displayState = session.displayState.get()
```

### `session.displayState.restoreTasks(tasks)`

在 UI 重播已持久保存的任務 Tool 歷程記錄後，還原快照中的任務部分。這是快照的純更新，不會發出事件，因此呼叫後請明確重新呈現畫面。

```typescript
session.displayState.restoreTasks(replayedTasks)
```

每個事件發生後，Session 都會連同最新快照發出 `display_state_changed`。請使用 [`session.subscribe()`](#identity-and-events) 訂閱，或從 `session.displayState.get()` 讀取目前值。

## 狀態

`session.state` 擁有對話中經結構描述驗證的 AgentController 狀態。它保存目前快照，並根據傳給 AgentController 的 `stateSchema` 驗證更新。更新會按序處理，而每項變更都會發出 `state_changed` 事件。

### `session.state.get()`

傳回目前狀態快照的唯讀副本。

```typescript
const state = session.state.get()
```

### `session.state.set(updates)`

將部分更新合併至狀態。更新會排入佇列，讓並行呼叫按順序套用、根據結構描述驗證，並透過 `state_changed` 發出已變更的鍵。

```typescript
await session.state.set({ yolo: true })
```

### `session.state.update(updater)`

針對目前快照執行 updater，並在寫入佇列中以不可分割方式套用其結果。必須讀取最新狀態的「讀取—修改—寫入」變更，應使用此方法。updater 會傳回要合併的 `updates`、要發出的可選 `events`，以及 `update()` 所解析為的 `result` 值。

```typescript
const added = await session.state.update(current => ({
  updates: { count: (current.count ?? 0) + 1 },
  result: (current.count ?? 0) + 1,
}))
```

## 持久保存界線

`Session` 是即時執行環境物件。它的事件匯流排、任意 `session.state`、權限規則、權限授權、待處理核准、暫停、後續訊息、執行狀態及串流狀態，不會在重新建立控制器或程序後自動保留。重新建立 Session 時，主機必須還原任何此類狀態。

配置儲存空間後，執行緒、訊息及 token 使用量會持久保存。執行緒設定會還原模式及模型選擇，亦可還原觀察式記憶設定和子 Agent 模型選擇，包括按 Agent 類型的覆寫值。聊天頻道可以重新對應至已儲存的執行緒，但 `AgentControllerChannels` 所保存的頻道至 Session 及自動核准狀態仍會留在記憶體中。

## 相關內容

- [AgentController 類別](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/agent-controller-class)
- [AgentController 概覽](https://mastra.zisheng.pro/zh-HK/docs/harness/agent-controller)
- [執行緒及狀態](https://mastra.zisheng.pro/zh-HK/docs/harness/agent-controller)
- [Tool 核准](https://mastra.zisheng.pro/zh-HK/docs/harness/agent-controller)