跳至主要內容

Memory.summarizeThread()

.summarizeThread() 方法會一次摘要執行緒對話。它會從儲存空間載入執行緒訊息，並使用支援 Observational Memory 的相同 Observer 管線加以濃縮：作為獨立呼叫，不必將 Observational Memory 附加至 Agent。

訊息會從最新一則開始逐頁載入，並受 lastMessages 與 maxInputTokens 限制，因此摘要長執行緒時不會從儲存空間讀取整個歷程記錄。

系統不會將任何內容寫回 Memory。摘要及擷取的值會回傳給你（以及每個 extractor 的 onExtracted hook），由你決定儲存位置，例如自己的資料庫。

若想在工作階段結束時取得整段對話的摘要或結構化擷取，例如語音通話掛斷時，請使用此方法。若你已經取得訊息（不必從執行緒載入），請改用獨立的 summarizeConversation() 函式。它接受相同選項，但以 messages 取代 threadId。

使用範例
「使用範例」的直接連結

const result = await memory.summarizeThread({
  model: 'openai/gpt-5-mini',
  threadId: 'thread-123',
  instructions: 'Summarize this voicemail call for the business owner.',
})

參數
「參數」的直接連結

threadId:

string
要摘要之執行緒的唯一識別碼。

model:

string | LanguageModel | DynamicModel
執行摘要的模型，例如 '__GATEWAY_OPENAI_MODEL_MINI__' 這類 router 字串。

resourceId?:

string
擁有此執行緒的資源 ID。若有提供，會驗證執行緒擁有權，並傳給 extractor context。

lastMessages?:

number
只摘要執行緒的最後 N 則訊息。預設會載入整個執行緒，但受 maxInputTokens 限制。

maxInputTokens?:

number
= 1000000
收集的訊息超過此估計 token 數量後，停止載入更舊的訊息。一律會包含最新的訊息。

instructions?:

string
附加到摘要器 system prompt 的額外指引，例如應著重的內容或摘要的閱讀對象。

extract?:

Extractor[]
要在對話上執行的 extractor。具有 Zod schema 的 extractor 會以後續結構化輸出呼叫執行；不含 schema 的 extractor 則會行內擷取。每個 extractor 的 onExtracted hook 都會收到擷取的值。

requestContext?:

RequestContext
轉送至摘要模型與 extractor hook 的 request context。

abortSignal?:

AbortSignal
取消摘要呼叫的訊號。

回傳值
「回傳值」的直接連結

summary:

string
從對話產生、以密集項目符號呈現的濃縮 observation。

extracted:

Record<string, unknown>
extract extractor 產生的值，以 extractor slug 作為 key。

extractionFailures:

{ slug: string; error: string }[]
未能產生有效值的 extractor 及其原因。只有至少一個 extractor 失敗時才會存在。

usage:

{ inputTokens?: number; outputTokens?: number; totalTokens?: number }
摘要呼叫的 token 使用量。

延伸使用範例
「延伸使用範例」的直接連結

下列範例會摘要已結束的語音通話，並將結構化記錄儲存在應用程式自己的資料庫：

src/call-summary.ts
import { Extractor } from '@mastra/memory'
import { z } from 'zod'
import { memory } from './mastra/memory'
import { callRecords } from './db'

const callSummary = new Extractor({
  name: 'call-summary',
  instructions: 'Return a concise summary of the call.',
  schema: z.object({
    summary: z.string(),
    sentiment: z.enum(['positive', 'neutral', 'negative']),
    requestedServices: z.array(z.string()),
  }),
  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
  onExtracted: async ({ current, threadId, resourceId }) => {
    await callRecords.upsert({ callId: threadId, callerId: resourceId, record: current })
  },
})

export async function onCallEnd(threadId: string, resourceId: string) {
  await memory.summarizeThread({
    model: 'openai/gpt-5-mini',
    threadId,
    resourceId,
    instructions: 'Summarize this voicemail call for the business owner.',
    extract: [callSummary],
  })
}
On this page