跳至主要內容

summarizeConversation()

獨立的 summarizeConversation() function 會一次過總結對話。它使用支援 Observational Memory 的相同 Observer 流程，精簡你傳入的訊息；過程毋須將 Observational Memory 附加至 agent，亦不會讀取或寫入 storage。

系統不會將任何內容寫回 memory。summary 及擷取出的值會傳回給你（以及每個 extractor 的 onExtracted hook），因此你可自行決定儲存位置，例如你自己的 database。

當你已有訊息並希望明確控制要總結的內容時，便可使用此 function。若要處理由 ID 識別的已儲存 thread，請使用 Memory.summarizeThread()，它會替你載入訊息。

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

import { summarizeConversation } from '@mastra/memory'

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

參數
參數 的直接連結

model:

string | LanguageModel | DynamicModel
執行總結的 model，例如像 '__GATEWAY_OPENAI_MODEL_MINI__' 這類 router string。

messages:

MastraDBMessage[]
要總結的對話。若為空，function 會傳回空結果，而不會呼叫 model。

instructions?:

string
附加至 summarizer system prompt 的額外指引，例如要聚焦的內容或 summary 的對象。

extract?:

Extractor[]
要在對話上執行的 extractors。具有 Zod schema 的 extractor 會透過後續 structured output call 執行；沒有 schema 的 extractor 則會 inline 擷取。每個 extractor 的 onExtracted hook 都會收到擷取出的值。

threadId?:

string
對話所屬的 thread。預設為 messages 中找到的首個 threadId。此值會傳遞至 extractor context。

resourceId?:

string
對話所屬的 resource（使用者）。預設為 messages 中找到的首個 resourceId。此值會傳遞至 extractor context。

memory?:

Memory
轉傳至 extractor context 的 Memory instance。透過 Memory.summarizeThread() 呼叫時會自動設定。

mastra?:

Mastra
用於解析自訂 gateway model 的 Mastra instance。透過 Memory.summarizeThread() 呼叫時會自動設定。

requestContext?:

RequestContext
轉傳至 summarizer model 及 extractor hook 的 request context。

abortSignal?:

AbortSignal
用於取消總結 call 的 signal。

傳回值
傳回值 的直接連結

summary:

string
由對話產生的精簡 observations，以資訊密集的項目符號形式呈現。

extracted:

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

extractionFailures:

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

usage:

{ inputTokens?: number; outputTokens?: number; totalTokens?: number }
總結 call 的 token 用量。

進階使用範例
進階使用範例 的直接連結

以下範例會根據應用程式已持有的訊息，總結進行中的語音 session，並擷取一筆結構化記錄：

src/session-summary.ts
import { summarizeConversation, Extractor } from '@mastra/memory'
import type { MastraDBMessage } from '@mastra/core/agent'
import { z } from 'zod'
import { sessionRecords } from './db'

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

export async function onSessionEnd(messages: MastraDBMessage[]) {
  const { summary, extracted, extractionFailures } = await summarizeConversation({
    model: 'openai/gpt-5-mini',
    messages,
    instructions: 'Summarize this support session for the account manager.',
    extract: [sessionSummary],
  })

  if (extractionFailures?.length) {
    console.warn('Some extractors failed', extractionFailures)
  }

  return { summary, extracted }
}
On this page