執行緒

此頁面顯示具體 Oracle 執行緒處理與開發人員專用訊息協助程式類型。

Oracle 執行緒

類別 oracleagentmemory.core.OracleThread

基本：IThread

由 Oracle 商店支援的執行緒。

此實作會內嵌並儲存執行緒訊息與手動新增的記憶，然後支援所有儲存記錄的相似性搜尋。

備註

• 訊息儲存為個別記錄 (每則訊息一筆記錄)。
• 您可以將搜尋限制在目前的執行緒，或是允許從任何執行緒 (由用戶端控制) 傳回結果。

建立新 OracleThread 執行處理。

• 參數：
  • store OracleMemoryStore – 用來保存內嵌記錄的共用存放區後端。
  • thread_id str – 繫線 ID。若未提供，則會產生 UUID。
  • user_id str – 與執行緒關聯的使用者識別碼。如果在資料庫 SchemaPolicy.NO_CHECK 程式實際執行存放區中省略，則會使用作用中一般使用者安全相關資訊環境的使用者名稱。否則，會產生 UUID。
  • agent_id str – 與繫線關聯的代理程式 ID。如果省略，則會產生 UUID。
  • 中繼資料 dict[str, Any] | None – 與執行緒相關聯的選擇性類似 JSON 的中繼資料。
  • persist_messages_in_config bool – _to_config 是否應包含最近的原始訊息快照。針對使用資料庫存放區的繫線自動設為 False，以避免透過繫線組態匯出訊息表格內容。
  • LLM ILlm | None – 選用的 LLM 轉接器，用於記憶體擷取與環境定義摘要更新。提供時，add_messages 會從每個新增的訊息擷取相關記憶體，並將它們儲存為輸入的記憶體記錄 ("memory"、"guideline"、"fact" 或 "preference")。
  • memory_extraction_config MemoryExtractionConfig – 選擇性執行緒層次記憶體擷取組態。您可以使用它來控制自動擷取設定值，例如擷取模式、摘要行為、擷取限制，以及是否完全啟用自動擷取。傳送此群組組態或不再使用的內嵌擷取參數，但不能同時傳送兩者。省略時，獨立的 OracleThread() 會在擷取欄位中使用 SDK 預設值，並保持啟用相關資訊環境摘要。省略的影像相關資訊環境為 DISABLED。
  • image_input_limit_config ImageInputLimitConfig – 此獨立執行緒的選擇性原始影像和 LLM 影像要求限制。省略的欄位使用 SDK 預設值。無法停用驗證。

  • memory_extraction_window int –

    擷取期間要作為 LLM 內容的最新訊息數目 (包括新新增的訊息)。設為 -1，只會使用新增訊息的完整批次，擷取每個 add_messages 呼叫一次。預設為 -1。

    已棄用

    自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。

  • context_summary_update_frequency int –

    最新的有效摘要之後，自動重新整理訊息的數目。啟用記憶體擷取時，檢查會在每次擷取到期後進行，以便稍後重新整理。每次檢查時小於或等於 0 重新整理的值。預設為 -1。

    已棄用

    自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。

  • memory_extraction_frequency int –

    觸發記憶體擷取的訊息數目。設為 -1，只會使用新增訊息的完整批次，擷取每個 add_messages 呼叫一次。

    已棄用

    自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。

  • memory_extraction_token_limit int –

    用於記憶體擷取和執行摘要更新的 LLM 提示大小上限 (記號)。較長的提示會被截斷。若為負數或 0，則會停用提示截斷。

    已棄用

    自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。

  • context_card_token_limit int – LLM 提示的最大輸入記號預算，用於建立內容卡中所含的摘要和主題清單。預設值為 100_000；小於或等於 0 的值會停用提示截斷。
  • context_card_type_search_concurrency int – 使用 min_relevant_results_by_type 建立內容卡時，要同時執行的記憶體式記錄搜尋次數上限。預設為 5。
  • max_message_token_length int – LLM 備份記憶體擷取和相關資訊環境摘要更新期間所使用之每個訊息的提示時間複本大小上限 (記號)。儲存的訊息內容維持不變。若為負數或 0，則不會執行提示時間縮短。如果提供 LLM，則會彙總過大小的提示複本，而非截斷。
  • message_shortening_input_token_limit int – 縮短過大提示複本時，傳送給 LLM 之訊息摘錄的最大大小 (記號)。預設為 30_000 記號。如果為負數或 0，則在 LLM 型縮短期間不會套用輸出界限。

  • enable_context_summary bool –

    要不要讓執行緒保持簡潔的摘要 。如果啟用且提供 llm，OAM 會根據 context_summary_update_frequency 重新整理，並使用目標訊息之前的摘要作為擷取相關資訊環境。獨立 OracleThread() 的預設值為 True。

    已棄用

    自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。

  • memory_extraction_custom_instructionsstr | None –

    此執行緒附加至自動記憶體擷取系統提示的選擇性自訂指示。

    已棄用

    自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。

  • memory_extraction_inherit_message_metadata bool | Sequence[str] –

    自動擷取的記憶體是否繼承來源訊息的描述資料。傳送 True 以繼承所有訊息描述資料、非字串的最上層訊息描述資料索引鍵順序，僅繼承這些索引鍵，或傳送 False 以停用繼承。預設為 True。如果一個擷取傳送使用多個來源訊息，則選取的描述資料必須符合這些訊息。

    已棄用

    自 26.6.0 版起已不再使用：此參數在 26.6.0 已不再使用，將會在 27.1 中移除。請改用 memory_extraction_config。

  • search_config MemorySearchConfig – 此執行緒的選擇性搜尋組態。省略時，搜尋會使用固定的頂端搜尋組態。
  • 用戶端 OracleAgentMemory | None

範例

from oracleagentmemory.core import MemoryExtractionConfig, OracleAgentMemory
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c4",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

方法 add_image

保留與此執行緒相關聯的影像。

description 會儲存為影像的可搜尋文字。省略此文字或 None 時，附加的 LLM 會產生標題。省略的範圍值會繼承此繫線的對應使用者、代理程式及繫線 ID。

• 參數：
  • image bytes – 要保存的原始影像位元組。
  • description str | None – 選擇性說明或標題。忽略它以產生標題。
  • mime_type ImageMimeType – 用於影像持續性與標題產生的選擇性 MIME 類型。當省略時，SDK 會從影像位元組偵測並驗證類型。支援的偵測類型為 PNG、JPEG 和 WEBP。
  • image_id str – 選擇性 ID。省略時會產生一個。
  • user_id str | None – 選擇性範圍宣告。省略的值會繼承此繫線的範圍；提供的值必須完全符合。
  • agent_id str | None – 選擇性範圍宣告。省略的值會繼承此繫線的範圍；提供的值必須完全符合。
  • thread_id str – 選擇性範圍宣告。省略的值會繼承此繫線的範圍；提供的值必須完全符合。
  • 中繼資料 dict[str, Any] | None – 隨影像儲存的選擇性中繼資料。
  • timestamp str | None – 為此影像儲存的選擇性事件時戳。省略此引數，或傳送 None 以儲存 NULL 事件時戳。讀取影像時，其建立時間會傳回為有效時間戳記。
  • ttl_days int | None – 選擇性到期設定值。
  • ttl_anchor TimeToLiveAnchor – 選擇性到期設定。
  • store_kwargs Any – 額外的商店特定選項。
• 傳回：保留的影像 ID。
• 傳回類型： str

方法 add_image_async (非同步)

以非同步方式保留一個與此執行緒關聯的影像。

description 會儲存為影像的可搜尋文字。省略此文字或 None 時，附加的 LLM 會產生標題。省略的範圍值會繼承此繫線的對應使用者、代理程式及繫線 ID。

• 參數：
  • image bytes – 要保存的原始影像位元組。
  • description str | None – 選擇性說明或標題。忽略它以產生標題。
  • mime_type ImageMimeType – 用於影像持續性與標題產生的選擇性 MIME 類型。當省略時，SDK 會從影像位元組偵測並驗證類型。支援的偵測類型為 PNG、JPEG 和 WEBP。
  • image_id str – 選擇性 ID。省略時會產生一個。
  • user_id str | None – 選擇性範圍宣告。省略的值會繼承此繫線的範圍；提供的值必須完全符合。
  • agent_id str | None – 選擇性範圍宣告。省略的值會繼承此繫線的範圍；提供的值必須完全符合。
  • thread_id str – 選擇性範圍宣告。省略的值會繼承此繫線的範圍；提供的值必須完全符合。
  • 中繼資料 dict[str, Any] | None – 隨影像儲存的選擇性中繼資料。
  • timestamp str | None – 為此影像儲存的選擇性事件時戳。省略此引數，或傳送 None 以儲存 NULL 事件時戳。讀取影像時，其建立時間會傳回為有效時間戳記。
  • ttl_days int | None – 選擇性到期設定值。
  • ttl_anchor TimeToLiveAnchor – 選擇性到期設定。
  • store_kwargs Any – 額外的商店特定選項。
• 傳回：保留的影像 ID。
• 傳回類型： str

方法 add_memory

新增手動記憶體項目並為其編製索引。

• 參數：
  • content str – 要儲存為記憶體的文字內容。
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – 要儲存的記憶體類別。支援的值為 "memory"、"fact"、"guideline" 和 "preference"。省略時，內容會儲存為一般 "memory"。
  • user_id str – 選擇性的使用者 ID 覆寫。
  • agent_id str – 選擇性代理程式 ID 覆寫。
  • thread_id str – 選擇性繫線 ID 覆寫。
  • memory_id str – 此記憶體資料列的選擇性呼叫程式提供穩定 ID。
  • 中繼資料 dict[str, Any] | None – 可選中繼資料以保留儲存的記憶體。
  • timestamp str | None – 為此記憶體儲存的選擇性事件時戳。省略此引數，或傳送 None 以儲存 NULL 事件時戳。讀取記錄時，其建立時間會傳回為有效時間戳記。當 ttl_anchor 為 TimeToLiveAnchor.TIMESTAMP 時，請提供具體的 ISO-8601 時戳值。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • ttl_days int | None – Optional time-to-live duration in days. Omit this argument to use the schema default time-to-live duration. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to store a non-expiring memory when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning.
  • ttl_anchor TimeToLiveAnchor – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為資料庫建立時間，或使用 TimeToLiveAnchor.TIMESTAMP 作為記憶體時戳。時間戳記錨定過期需要此記憶體的具體 ISO-8601 時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • 狀態 RecordStatus – 初始生命週期狀態。省略以儲存 RecordStatus.VALID。
  • autonomous_linking bool – 是否使用執行緒的 LLM，從這個新記憶體建立連結至相關預存記憶體的連結。省略會在 LLM 存在時啟用；傳送 False 以略過。失敗會保留記憶體。
  • memory_id_to_link str – 共同建立從新記憶體至此現有執行緒擁有之記憶體的導向連結。省略的使用者、代理程式以及繫線範圍會繼承自該目標。忽略兩者，不建立明確的連結。
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker – 一起從新記憶體建立導向的連結，以至此現有的執行緒擁有記憶體。省略的使用者、代理程式以及繫線範圍會繼承自該目標。忽略兩者，不建立明確的連結。
  • link_id str – 明確連結的選擇性識別碼、時間戳記及中繼資料。
  • link_timestamp str | None – 明確連結的選擇性識別碼、時間戳記及中繼資料。
  • link_metadata dict[str, Any] | None – 明確連結的選擇性識別碼、時間戳記及中繼資料。
  • **store_kwargs ( 任一 ) – 轉送至備份存放區的存放區特定寫入選項。
• 傳回：插入之記憶體記錄的 ID。
• 傳回類型： str

範例

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

方法 add_memory_async (非同步)

新增手動記憶體項目，並以非同步方式編製索引。

• 參數：
  • content str – 要儲存為記憶體的文字內容。
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – 要儲存的記憶體類別。支援的值為 "memory"、"fact"、"guideline" 和 "preference"。省略時，內容會儲存為一般 "memory"。
  • user_id str – 選擇性的使用者 ID 覆寫。
  • agent_id str – 選擇性代理程式 ID 覆寫。
  • thread_id str – 選擇性繫線 ID 覆寫。
  • memory_id str – 此記憶體資料列的選擇性呼叫程式提供穩定 ID。
  • 中繼資料 dict[str, Any] | None – 可選中繼資料以保留儲存的記憶體。
  • timestamp str | None – 為此記憶體儲存的選擇性事件時戳。省略此引數，或傳送 None 以儲存 NULL 事件時戳。讀取記錄時，其建立時間會傳回為有效時間戳記。當 ttl_anchor 為 TimeToLiveAnchor.TIMESTAMP 時，請提供具體的 ISO-8601 時戳值。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • ttl_days int | None – Optional time-to-live duration in days. Omit this argument to use the schema default time-to-live duration. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to store a non-expiring memory when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning.
  • ttl_anchor TimeToLiveAnchor – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為資料庫建立時間，或使用 TimeToLiveAnchor.TIMESTAMP 作為記憶體時戳。時間戳記錨定過期需要此記憶體的具體 ISO-8601 時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • 狀態 RecordStatus – 初始生命週期狀態。省略以儲存 RecordStatus.VALID。
  • autonomous_linking bool – 是否使用執行緒的 LLM，從這個新記憶體建立連結至相關預存記憶體的連結。省略會在 LLM 存在時啟用；傳送 False 以略過。失敗會保留記憶體。
  • memory_id_to_link str – 共同建立從新記憶體至此現有執行緒擁有之記憶體的導向連結。省略的使用者、代理程式以及繫線範圍會繼承自該目標。忽略兩者，不建立明確的連結。
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker – 一起從新記憶體建立導向的連結，以至此現有的執行緒擁有記憶體。省略的使用者、代理程式以及繫線範圍會繼承自該目標。忽略兩者，不建立明確的連結。
  • link_id str – 明確連結的選擇性識別碼、時間戳記及中繼資料。
  • link_timestamp str | None – 明確連結的選擇性識別碼、時間戳記及中繼資料。
  • link_metadata dict[str, Any] | None – 明確連結的選擇性識別碼、時間戳記及中繼資料。
  • **store_kwargs ( 任一 ) – 轉送至備份存放區的存放區特定寫入選項。
• 傳回：插入之記憶體記錄的 ID。
• 傳回類型： str

範例

import asyncio
asyncio.run(thread.add_memory_async(
    "Remember this preference", memory_id="mem-thread-docs-async"
))
'mem-thread-docs-async'

方法 add_messages

新增訊息到討論串並建立它們索引。

在背景擷取模式中，此方法會在原始訊息插入後傳回，並在背景嘗試到期背景擷取。

原始訊息會在任一模式中都儲存下來自動解壓縮。如果稍後擷取或衍生記憶體儲存失敗，當可能遺漏衍生的記憶體或摘要更新時，原始訊息會維持儲存狀態。

• 參數：
  • messages Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]] – 要附加的訊息清單。訊息可以是 Message 物件或含有 role 和 content 的字典 (以及選擇性的 id)。
  • 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None] – 選擇性共用或每個訊息中繼資料以供保存。省略時，會使用內嵌於每個訊息中的描述資料。
  • ttl_days int | None | list[int | None] – Optional time-to-live duration in days for appended messages. Omit this argument to use the schema default time-to-live duration. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to create non-expiring messages when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Scalar values apply to the full batch.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – 選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為資料庫建立時間，或為每個訊息時戳使用 TimeToLiveAnchor.TIMESTAMP。時間戳記錨定到期需要每個受影響訊息的具體 ISO-8601 時間戳記。省略時，相對於 TimeToLiveAnchor.CREATED_AT 的訊息就會過期。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • **store_kwargs ( 任一 ) – 轉送至備份存放區的存放區特定寫入選項。
• 傳回：插入之訊息記錄的識別碼。在背景擷取模式中，當傳回這些識別碼時，自動擷取工作可能仍在執行中。
• 傳回類型： list[str]

備註

在 MemoryExtractionMode.BACKGROUND 中，原始訊息會在儲存擷取的記憶體之前保留。如果背景擷取沒有佇列，或者如果設定的佇列容量等待達到其逾時，則插入的原始訊息會維持儲存狀態，且呼叫會繼續而沒有擷取的記憶體，或發出 TimeoutError (視 background_extraction_queue_full_behavior 而定)。

範例

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

方法 add_messages_async (非同步)

非同步地新增信件到串列中，並為其建立索引。

在背景擷取模式中，此方法會在原始訊息插入後傳回，並在背景嘗試到期背景擷取。

原始訊息會在任一模式中都儲存下來自動解壓縮。如果稍後擷取或衍生記憶體儲存失敗，當可能遺漏衍生的記憶體或摘要更新時，原始訊息會維持儲存狀態。

在 MemoryExtractionMode.BACKGROUND 中，原始訊息會在儲存擷取的記憶體之前保留。如果背景擷取沒有佇列，或者如果設定的佇列容量等待達到其逾時，則插入的原始訊息會維持儲存狀態，且呼叫會繼續而沒有擷取的記憶體，或發出 TimeoutError (視 background_extraction_queue_full_behavior 而定)。

• 參數：
  • 訊息 Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]]
  • 中繼資料 dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• 傳回類型： list[str]

方法 delete_image

刪除此執行緒擁有的一個影像。

• 參數： image_id str – 要刪除之影像的 ID。
• 傳回：刪除時傳回 1，否則當影像不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數
• 發出：ValueError – 如果影像已附加至訊息。改為刪除或更新上階訊息。

方法 delete_image_async (非同步)

以非同步方式刪除此執行緒所擁有的影像。

• 參數： image_id str – 要刪除之影像的 ID。
• 傳回：刪除時傳回 1，否則當影像不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數
• 發出：ValueError – 如果影像已附加至訊息。改為刪除或更新上階訊息。

方法 delete_memory

依 ID 從這個完全相同的繫線刪除類似記憶體的記錄 (例如記憶體、事實、偏好設定或準則)。

• 參數： memory_id str – 記憶體 ID。只有儲存的 thread_id 完全符合此繫線的類似記憶體記錄 (memory、guideline、fact、preference) 才會被刪除。
• 傳回數：刪除的記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數
• 發出：TimeoutError – 在先前接受的此執行緒背景擷取未在 300 秒內完成時，發出而不刪除記錄。

備註

刪除記錄之前，此方法會等候先前透過附加的代理程式記憶體元件接受此執行緒的背景擷取。它不會等待等待開始後的工作，或是其他元件或處理程序開始的工作。

範例

thread.delete_memory("456")
0

方法 delete_memory_async (非同步)

以非同步方式從這個精確執行緒中刪除類似記憶體的記錄 (例如記憶體、事實、偏好設定或準則)。

• 參數： memory_id str – 記憶體 ID。只有儲存的 thread_id 完全符合此繫線的類似記憶體記錄 (memory、guideline、fact、preference) 才會被刪除。
• 傳回數：刪除的記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數
• 發出：TimeoutError – 在先前接受的此執行緒背景擷取未在 300 秒內完成時，發出而不刪除記錄。

備註

此方法遵循 delete_memory() 所記錄的背景擷取等待與並行行為。

範例

import asyncio
asyncio.run(thread.delete_memory_async("456"))
0

方法 delete_message

依識別碼從此精確執行緒刪除訊息記錄。

• 參數： message_id str – 訊息 ID。只會刪除儲存的 thread_id 完全符合此討論串的訊息。
• 傳回數：刪除的訊息記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數
• 發出：TimeoutError – 在先前接受的此執行緒背景擷取未在 300 秒內完成時，發出而不刪除訊息。

備註

刪除訊息之前，此方法會等候先前透過附加的代理程式記憶體元件接受此繫線的背景擷取。它不會等待等待開始後的工作，或是其他元件或處理程序開始的工作。

刪除訊息只會移除原始訊息記錄。衍生的記憶體並不會被刪除，因為我們尚未追蹤哪個擷取的記憶體來自哪個訊息，所以它們仍然可以搜尋或仍會影響相關資訊環境卡輸出。使用 OracleAgentMemory.delete_thread() 可將繫線與其相關的訊息和記憶體一起刪除。

範例

thread.delete_message("123")
0

方法 delete_message_async (非同步)

以非同步方式從這個精確執行緒中刪除訊息記錄。

• 參數： message_id str – 訊息 ID。只會刪除儲存的 thread_id 完全符合此討論串的訊息。
• 傳回數：刪除的訊息記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數
• 發出：TimeoutError – 在先前接受的此執行緒背景擷取未在 300 秒內完成時，發出而不刪除訊息。

備註

此方法遵循 delete_message() 所記錄的背景擷取等待與並行行為。

刪除訊息只會移除原始訊息記錄。衍生的記憶體並不會被刪除，因為我們尚未追蹤哪個擷取的記憶體來自哪個訊息，所以它們仍然可以搜尋或仍會影響相關資訊環境卡輸出。使用 OracleAgentMemory.delete_thread() 可將繫線與其相關的訊息和記憶體一起刪除。

範例

import asyncio
asyncio.run(thread.delete_message_async("123"))
0

方法 delete_record_link

依 ID 刪除繫線擁有的關係或完整的端點元組。

端點元組選取器必須使用儲存的來源至目標方向。

• 參數：
  • source_record_id str – 端點元組選取器的來源識別碼。
  • source_record_type str – 端點元組選取器的邏輯來源記錄類型。
  • target_record_id str – 端點元組選取器的目標 ID。
  • target_record_type str – 端點元組選取器的邏輯目標記錄類型。
  • relation_type str – 端點元組選取器的來源至目標標籤。
  • relation_id str – 直接選取的關係識別碼。僅提供此引數。
• 傳回：已刪除關係的數目 (0 或 1)。
• 傳回類型：整數

範例

thread.delete_record_link(relation_id="relation-id")
1

方法 delete_record_link_async (非同步)

非同步刪除此執行緒所擁有的關係。

• 參數：
  • source_record_id str
  • source_record_type str
  • target_record_id str
  • target_record_type str
  • relation_typestr
  • relation_id str
• 傳回類型：整數

方法 get_context_card

傳回繫線的相關資訊環境卡物件。

在 LLM 備份的實作可能執行遠端網路 I/O 時，偏好使用 get_context_card_async。

• 參數：
  • fallback_message_count int – 衍生回溯摘要文字以進行擷取和呈現時，所要使用的最近訊息數目。省略時，會解析為 5。

  • 最大相關結果 int –

    要包含在相關資訊環境卡之 <relevant_information> 區段中的相關記錄 (類似記憶體，例如事實 / 偏好設定以及訊息) 數目上限。

    • 如果同時省略此值和 min_relevant_results_by_type，max_relevant_results 會解析為 5。
    • 如果提供 min_relevant_results_by_type，max_relevant_results 會解析為 max(max_relevant_results, sum(min_relevant_results_by_type.values()))。
  • token_budget int | None – 相關資訊環境卡中格式化相關結果之預估記號計數的選擇性嚴格限制。省略時，會使用執行緒搜尋組態。正值會在其累積預估符合預算時，依排名順序保留完整的結果。如果第一個結果不適合，則不會包含任何相關結果。非正值會停用上限。
  • soft_token_budget int | None – 格式化相關結果之預估記號計數的選擇性目標。省略時，會使用執行緒搜尋組態。達到或超過此目標的完整結果會被保留。非正值會停用此目標。當輸出必須同時具有絕對限制時，將 token_budget 設為較大的值。
  • max_recent_messages int – 要包含在相關資訊環境卡之 <recent_messages> 區段中的最近對話訊息數目上限。省略時，max_recent_messages 會解析為 0。

  • except_last_messages int –

    要從內容卡中所含產生的摘要與相關資訊搜尋中排除的尾端訊息數。這可防止在 LLM 提示中個別提供的訊息在內容卡中複製。使用下列其中一種樣式：

    • 外部原始尾端 (建議用於提示快取)：

      get_context_card(except_last_messages=N, max_recent_messages=0) 提示包含環境定義卡，後面接著最後 N 原始訊息。

    • 獨立的上下文卡：

      get_context_card(except_last_messages=N, max_recent_messages=N) 內容卡包含最後的 N 訊息本身。

    若非零，max_recent_messages 必須是 0 或相同的值。

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – 相關資訊環境卡中所含相關記錄的選擇性每種類型下限。系統會先搜尋要求的類型，然後從所有支援的類似記憶體的記錄類型中填入剩餘的 max_relevant_results 插槽。支援的金鑰為 "memory"、"fact"、"guideline"、"preference" 及 "message"。訊息結果限制為目前的執行緒。

  • metadata_filter dict[str, Any] | None –

    搜尋要包含在相關資訊環境卡中的類似記憶體記錄時，作為範圍與記錄類型篩選後其他篩選的選擇性描述資料篩選對應。metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的記錄描述資料中。巢狀字典會以遞迴方式比對巢狀描述資料物件。定量與清單值必須完全相符；清單順序與長度也必須相符。省略此引數，或傳送 None 以進行搜尋而不篩選描述資料。範例包括純量欄位的 metadata_filter={"source": "chat"}、巢狀欄位的 metadata_filter={"travel": {"need": "transit"}}，以及完全相符的清單 metadata_filter={"tags": ["trip", "urgent"]}。結合條件以要求所有條件：

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    若要測試陣列成員身分，請使用欄位層次運算子字典。"$array_contains" 會比對一個值或清單中的所有值。"$array_contains_any" 會比對清單中的至少一個值。"$not" 會否定相同欄位的另一個欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符：

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – 內容卡中是否包含無效生命週期狀態的相關記錄。省略此引數，或傳送 True 以包含這些引數。傳送 False 以排除它們。
  • **kwargs ( 任一 ) – 保留供未來內容卡選項使用。未預期的關鍵字引數會產生 TypeError。
• 傳回：包含以最新訊息為基礎之繫線相關資訊環境摘要的相關資訊環境卡物件。使用 OracleContextCard.content 來存取轉譯的類似 XML 文字。
• 傳回類型：OracleContextCard

備註

這會使用繫線的預設搜尋範圍與 exact_thread_match=False，因此可以包含來自相同使用者 / 代理程式之其他繫線的相關記憶體。

範例

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card().content
True
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

方法 get_context_card_async (非同步)

非同步傳回執行緒的環境定義卡物件。

• 參數：
  • fallback_message_count int – 衍生回溯摘要文字以進行擷取和呈現時，所要使用的最近訊息數目。省略時，會解析為 5。

  • 最大相關結果 int –

    要包含在相關資訊環境卡之 <relevant_information> 區段中的相關記錄 (類似記憶體，例如事實 / 偏好設定以及訊息) 數目上限。

    • 如果同時省略此值和 min_relevant_results_by_type，max_relevant_results 會解析為 5。
    • 如果提供 min_relevant_results_by_type，max_relevant_results 會解析為 max(max_relevant_results, sum(min_relevant_results_by_type.values()))。
  • token_budget int | None – 相關資訊環境卡中格式化相關結果之預估記號計數的選擇性嚴格限制。省略時，會使用執行緒搜尋組態。正值會在其累積預估符合預算時，依排名順序保留完整的結果。如果第一個結果不適合，則不會包含任何相關結果。非正值會停用上限。
  • soft_token_budget int | None – 格式化相關結果之預估記號計數的選擇性目標。省略時，會使用執行緒搜尋組態。達到或超過此目標的完整結果會被保留。非正值會停用此目標。當輸出必須同時具有絕對限制時，將 token_budget 設為較大的值。
  • max_recent_messages int – 要包含在相關資訊環境卡之 <recent_messages> 區段中的最近對話訊息數目上限。省略時，max_recent_messages 會解析為 0。

  • except_last_messages int –

    要從內容卡中所含產生的摘要與相關資訊搜尋中排除的尾端訊息數。這可防止在 LLM 提示中個別提供的訊息在內容卡中複製。使用下列其中一種樣式：

    • 外部原始尾端 (建議用於提示快取)：

      get_context_card(except_last_messages=N, max_recent_messages=0) 提示包含環境定義卡，後面接著最後 N 原始訊息。

    • 獨立的上下文卡：

      get_context_card(except_last_messages=N, max_recent_messages=N) 內容卡包含最後的 N 訊息本身。

    若非零，max_recent_messages 必須是 0 或相同的值。

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – 相關資訊環境卡中所含相關記錄的選擇性每種類型下限。系統會先搜尋要求的類型，然後從所有支援的類似記憶體的記錄類型中填入剩餘的 max_relevant_results 插槽。支援的金鑰為 "memory"、"fact"、"guideline"、"preference" 及 "message"。訊息結果限制為目前的執行緒。

  • metadata_filter dict[str, Any] | None –

    搜尋要包含在相關資訊環境卡中的類似記憶體記錄時，作為範圍與記錄類型篩選後其他篩選的選擇性描述資料篩選對應。metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的記錄描述資料中。巢狀字典會以遞迴方式比對巢狀描述資料物件。定量與清單值必須完全相符；清單順序與長度也必須相符。省略此引數，或傳送 None 以進行搜尋而不篩選描述資料。範例包括純量欄位的 metadata_filter={"source": "chat"}、巢狀欄位的 metadata_filter={"travel": {"need": "transit"}}，以及完全相符的清單 metadata_filter={"tags": ["trip", "urgent"]}。結合條件以要求所有條件：

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    若要測試陣列成員身分，請使用欄位層次運算子字典。"$array_contains" 會比對一個值或清單中的所有值。"$array_contains_any" 會比對清單中的至少一個值。"$not" 會否定相同欄位的另一個欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符：

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – 內容卡中是否包含無效生命週期狀態的相關記錄。省略此引數，或傳送 True 以包含這些引數。傳送 False 以排除它們。
  • **kwargs ( 任一 ) – 保留供未來內容卡選項使用。未預期的關鍵字引數會產生 TypeError。
• 傳回：繫線的相關資訊環境卡物件。
• 傳回類型：OracleContextCard

範例

import asyncio
card = asyncio.run(thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
))
len(card.relevant_results or []) <= 5
True

方法 get_message

傳回此執行緒擁有的一則訊息。

依預設，會傳回影像部分的 ID 和描述。傳送 included_image_ids 以載入所選影像部分的位元組。不相關的識別碼會被忽略。

• 參數：
  • message_id str – 要擷取之訊息的 ID。訊息必須屬於此討論串。
  • included_image_ids list[str] – 附加影像識別碼的選擇性清單，其位元組應該載入。省略此引數，或傳送 None 以在不載入位元組的情況下傳回影像描述資料。
• 傳回：要求的訊息，包括任何附加的影像部分。
• 傳回類型：訊息
• 發出：KeyError – 如果訊息不存在或屬於另一個執行緒。

方法 get_message_async (非同步)

以非同步方式傳回一則執行緒擁有的訊息。

included_image_ids 可選擇性地選取應載入位元組的附加影像部分；省略，或 None 僅傳回影像中繼資料。

• 參數：
  • message_id str – 要擷取之訊息的 ID。訊息必須屬於此討論串。
  • included_image_ids list[str] – 可選擇填入的附加影像 ID 清單。
• 傳回：要求的訊息，包括任何附加的影像部分。
• 傳回類型：訊息
• 發出：KeyError – 如果訊息不存在或屬於另一個執行緒。

方法 get_messages

回傳此討論串的已儲存訊息。

• 參數：
  • start int | None – 開始索引 (0-based)。與 end 一起省略時，會傳回最近連結的視窗。
  • end int | None – 結束索引 (不含)。省略時，會傳回最近訊息的連結視窗。傳送 None 或 -1 以明確向 start 要求所有訊息。
  • include_image_bytes bool – 是否要為附加至傳回之訊息的影像部分載入位元組。省略此引數，或傳送 False 以傳回影像描述資料，而不載入 BLOB 值。
• 傳回：依時間順序排列的訊息。
• 傳回類型： list[ 訊息 ]

範例

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

方法 get_messages_async (非同步)

以非同步方式從 add_messages 新增的繫線取得未處理的訊息。

• 參數：
  • start int | None – 開始索引 (0-based)。與 end 一起省略時，會傳回最近連結的視窗。
  • end int | None – 結束索引 (不含)。省略時，會傳回最近訊息的連結視窗。傳送 None 或 -1 以明確向 start 要求所有訊息。
  • include_image_bytes bool – 是否要為附加至傳回之訊息的影像部分載入位元組。省略此引數，或傳送 False 以傳回影像描述資料，而不載入 BLOB 值。
• 傳回：依時間順序排列的訊息。
• 傳回類型： list[ 訊息 ]

範例

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Stored message example"}]
))
len(message_ids)
1
messages = asyncio.run(thread.get_messages_async())
messages[-1].content
'Stored message example'

方法 get_summary

傳回執行緒的摘要。

整個執行緒要求會重複使用或重新整理持久性摘要。具有 except_last 的要求會彙總該字首，而不變更持久性完整執行緒摘要。

在 LLM 備份的實作可能執行遠端網路 I/O 時，偏好使用 get_summary_async。

• 參數：
  • except_last int – 要從摘要排除的最近訊息數目。
  • token_budget int – 軟權杖預算。省略時，會套用繫結的預設值。只有在格式化摘要超過預算時，正值才會截斷。非正值會停用以預算為基準的截斷；成績單後援則維持在 4,000 個字元的上限。
  • **kwargs ( 任一 ) – 保留供未來摘要選項使用。未預期的關鍵字引數會產生 TypeError。
• 傳回：包含合成繫線摘要文字的摘要物件。
• 傳回類型：OracleSummary

範例

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
bool(summary.content)
True

方法 get_summary_async (非同步)

非同步傳回執行緒摘要。

整個執行緒要求會重複使用或重新整理持久性摘要。具有 except_last 的要求會彙總該字首，而不變更持久性完整執行緒摘要。

• 參數：
  • except_last int – 要從摘要排除的最近訊息數目。
  • token_budget int – 軟權杖預算。省略時，會套用繫結的預設值。只有在格式化摘要超過預算時，正值才會截斷。非正值會停用以預算為基準的截斷；成績單後援則維持在 4,000 個字元的上限。
  • **kwargs ( 任一 ) – 保留供未來摘要選項使用。未預期的關鍵字引數會產生 TypeError。
• 傳回：包含合成繫線摘要文字的摘要物件。
• 傳回類型：OracleSummary

方法 link_records

建立此執行緒所擁有之兩筆記錄之間的導向關係。

目前這兩個端點都必須類似記憶體的記錄："memory"、"fact"、"guideline" 或 "preference"。內建關係類型包括 "supersedes" ("is_superseded_by")、"contradicts"、"refines" ("is_refined_by")、"supports" ("is_supported_by") 以及 "duplicates"。"contradicts" 和 "duplicates" 會反向使用相同的標籤。

兩個端點都必須屬於此精確繫線。一個端點組只能儲存一個方向。opposite_relation_type 會在從目標到來源的周遊時命名關係；例如，new "supersedes" old 會變成該方向的 old "is_superseded_by" new。

• 參數：
  • source_record_id str – 執行緒擁有之來源記錄的識別碼。
  • source_record_type str – 來源記錄的邏輯類型。
  • target_record_id str – 繫線擁有之目標記錄的 ID。
  • target_record_type str – 目標記錄的邏輯類型。
  • relation_type str – 來源至目標關係標籤。
  • opposite_relation_type str – 選擇性的反向追蹤標籤。若為內建記憶體關係類型，省略會使用其預先定義的反向標籤；若為自訂關係類型，省略會在兩個方向使用相同的標籤。
  • relation_id str – 選擇性的穩定關係識別碼。省略以產生。
  • timestamp str | None – 儲存在關係中的選擇性時間戳記。
  • 中繼資料 dict[str, Any] | None – 選擇性關係中繼資料。
• 傳回：所建立關係的識別碼。
• 傳回類型： str

範例

thread.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

方法 link_records_async (非同步)

非同步建立此執行緒所擁有記錄之間的關係。

目前這兩個端點都必須類似記憶體的記錄："memory"、"fact"、"guideline" 或 "preference"。內建關係類型包括 "supersedes" ("is_superseded_by")、"contradicts"、"refines" ("is_refined_by")、"supports" ("is_supported_by") 以及 "duplicates"。"contradicts" 和 "duplicates" 會反向使用相同的標籤。

• 參數：
  • source_record_id str
  • source_record_type str
  • target_record_id str
  • target_record_type str
  • relation_typestr
  • opposite_relation_type str
  • relation_id str
  • 時間戳記 str | None
  • 中繼資料 dict[str, Any] | None
• 傳回類型： str

方法 list_images

列出此執行緒擁有的影像記錄。

傳回的記錄預設包含影像描述資料。只有在提供 include_bytes=True 和 image_id 時，才會載入原始位元組。

• 參數：
  • image_id str – 用來篩選影像的選擇性識別碼。省略時，不會套用任何 ID 篩選。
  • metadata_filter dict[str, Any] | None – 套用至影像描述資料的選擇性篩選。
  • include_bytes bool – 是否要載入原始位元組。這需要 image_id。
  • limit int | None – 選擇性的記錄數目上限。傳送 None 以停用存放區的預設限制。
• 退貨：依商店順序比對影像。
• 傳回類型： list[ ImageRecord ]

方法 list_images_async (非同步)

以非同步方式列出此執行緒所擁有的影像記錄。

傳回的記錄預設包含影像描述資料。只有在提供 include_bytes=True 和 image_id 時，才會載入原始位元組。此繫線範圍會自動套用。

• 參數：
  • image_id str – 用來篩選影像的選擇性識別碼。省略時，不會套用任何 ID 篩選。
  • metadata_filter dict[str, Any] | None – 套用至影像描述資料的選擇性篩選。
  • include_bytes bool – 是否要載入原始位元組。這需要 image_id。
  • limit int | None – 選擇性的記錄數目上限。傳送 None 以停用存放區的預設限制。
• 退貨：依商店順序比對影像。
• 傳回類型： list[ ImageRecord ]

方法 search

同步搜尋與查詢相關的記錄。

• 參數：
  • query str – 自然語言查詢字串。
  • user_id str | None – 選擇性使用者範圍覆寫。省略的值會繼承繫線的預設使用者範圍。
  • agent_id str | None – 選擇性代理程式範圍覆寫。省略的值會繼承繫線的預設代理程式範圍。
  • thread_id str | None – 選擇性執行緒範圍置換。省略的值會繼承繫線目前的繫線 ID。
  • exact_user_match bool – 是否應嚴格比對使用者。
  • exact_agent_match bool – 是否應嚴格比對代理程式。
  • exact_thread_match bool – 是否應嚴格比對執行緒。
  • max_results int – 可選擇傳回的最大結果數。若有提供，至少必須為 1。省略此引數使用預設值 10。當有較少的非到期配對記錄存在時，呼叫可能會傳回少於 max_results。
  • token_budget int – 最終格式化結果之預估記號計數的選擇性嚴格限制。省略時，會使用解析的搜尋組態。正值會在其累積預估符合預算時，依排名順序保留完整的結果。如果第一個結果不符合，則不會傳回任何結果。非正值會停用此輸出界限。
  • soft_token_budget int – 最終格式化結果之預估記號計數的選擇性目標。省略時，會使用解析的搜尋組態。達到或超過此目標的完整結果會被保留。非正值會停用此目標。當輸出必須同時具有絕對限制時，將 token_budget 設為較大的值。
  • record_types list[str] – 要包含的選擇性記錄類型清單，例如 "memory"、"message" 或 "image"。

  • metadata_filter dict[str, Any] | None –

    作為範圍與記錄類型篩選後之其他篩選的選擇性描述資料篩選對應。metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的記錄描述資料中。巢狀字典會以遞迴方式比對巢狀描述資料物件。定量與清單值必須完全相符；清單順序與長度也必須相符。省略此引數，或傳送 None 以進行搜尋而不篩選描述資料。範例包括純量欄位的 metadata_filter={"source": "chat"}、巢狀欄位的 metadata_filter={"travel": {"need": "transit"}}，以及完全相符的清單 metadata_filter={"tags": ["trip", "urgent"]}。結合條件以要求所有條件：

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    若要測試陣列成員身分，請使用欄位層次運算子字典。"$array_contains" 會比對一個值或清單中的所有值。"$array_contains_any" 會比對清單中的至少一個值。"$not" 會否定相同欄位的另一個欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符：

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – 結果是否包含無效狀態的記錄。省略此引數，或傳送 True 以包含這些引數。傳送 False 以排除它們。
  • num_hops int – 每個直接記憶體結果中要遵循的記憶體連結邊緣數目。支援從 0 到 5 的值；僅忽略直接結果。直接訊息、影像及設定檔結果會保留，但不會以圖形展開。
  • max_linked_results int – 附加至每個直接結果之所有躍點的連結記憶體上限。省略預設值 100；傳送 0 以不傳回任何連結的相關資訊環境。
  • scope SearchScope – 選擇性的預建搜尋範圍。提供 scope 或明確的 ID 和完全相符的引數，不能同時提供兩者。
• 退貨：依遞減核發排序的搜尋結果。
• 傳回類型： list[SearchResult]
• 增加：ValueError – 如果 scope 與明確的 ID 或完全相符引數結合，如果 max_results 小於 1，或者 metadata_filter 既不是說明也不是 None，

備註

省略的範圍欄位會繼承此繫線的預設搜尋範圍：完全符合的使用者和代理程式，加上此繫線的目前 user_id、agent_id 和 thread_id。預設執行緒會故意留下 exact_thread_match=False，因此可能會從相同使用者 / 代理程式的其他執行緒傳回相關記錄。傳送 exact_thread_match=True 以將結果限制為目前的繫線。明確的 None 範圍值仍然遵循解析的完全相符規則：exact_*_match=False 會讓該維度維持不限制，而 exact_*_match=True 則只比對儲存的 None 值。

明確的 max_results 值必須至少為 1；省略引數會使用預設值 10。此為上限：當篩選條件的限制性太大、相符的記錄較少或因為實作特定的搜尋行為而導致呼叫傳回的結果可能少於 max_results。

方法 search_async (非同步)

以非同步方式搜尋與查詢相關的記錄。

• 參數：
  • query str – 自然語言查詢字串。
  • user_id str | None – 選擇性使用者範圍覆寫。省略的值會繼承繫線的預設使用者範圍。
  • agent_id str | None – 選擇性代理程式範圍覆寫。省略的值會繼承繫線的預設代理程式範圍。
  • thread_id str | None – 選擇性執行緒範圍置換。省略的值會繼承繫線目前的繫線 ID。
  • exact_user_match bool – 是否應嚴格比對使用者。
  • exact_agent_match bool – 是否應嚴格比對代理程式。
  • exact_thread_match bool – 是否應嚴格比對執行緒。
  • max_results int – 可選擇傳回的最大結果數。若有提供，至少必須為 1。省略此引數使用預設值 10。
  • token_budget int – 最終格式化結果之預估記號計數的選擇性嚴格限制。省略時，會使用解析的搜尋組態。正值會在其累積預估符合預算時，依排名順序保留完整的結果。如果第一個結果不符合，則不會傳回任何結果。非正值會停用此輸出界限。
  • soft_token_budget int – 最終格式化結果之預估記號計數的選擇性目標。省略時，會使用解析的搜尋組態。達到或超過此目標的完整結果會被保留。非正值會停用此目標。當輸出必須同時具有絕對限制時，將 token_budget 設為較大的值。
  • record_types list[str] – 要包含的選擇性記錄類型清單，例如 "memory"、"message" 或 "image"。

  • metadata_filter dict[str, Any] | None –

    作為範圍與記錄類型篩選後之其他篩選的選擇性描述資料篩選對應。metadata_filter 中的項目會與 AND 語意結合。值不是欄位層次運算子說明的項目，會使用完全相符的語意：要求的索引鍵必須存在於儲存的記錄描述資料中。巢狀字典會以遞迴方式比對巢狀描述資料物件。定量與清單值必須完全相符；清單順序與長度也必須相符。省略此引數，或傳送 None 以進行搜尋而不篩選描述資料。範例包括純量欄位的 metadata_filter={"source": "chat"}、巢狀欄位的 metadata_filter={"travel": {"need": "transit"}}，以及完全相符的清單 metadata_filter={"tags": ["trip", "urgent"]}。結合條件以要求所有條件：

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    若要測試陣列成員身分，請使用欄位層次運算子字典。"$array_contains" 會比對一個值或清單中的所有值。"$array_contains_any" 會比對清單中的至少一個值。"$not" 會否定相同欄位的另一個欄位層次表示式，包括運算子字典或原始完全相符值。正數表示式若失敗 (包括遺漏欄位)，負數表示式就會相符；負數陣列成員身分也會與非陣列欄位相符：

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – 結果是否包含無效狀態的記錄。省略此引數，或傳送 True 以包含這些引數。傳送 False 以排除它們。
  • num_hops int – 每個直接記憶體結果中要遵循的記憶體連結邊緣數目。支援從 0 到 5 的值；僅忽略直接結果。直接訊息、影像及設定檔結果會保留，但不會以圖形展開。
  • max_linked_results int – 附加至每個直接結果之所有躍點的連結記憶體上限。省略預設值 100；傳送 0 以不傳回任何連結的相關資訊環境。
  • scope SearchScope – 選擇性的預建搜尋範圍。提供 scope 或明確的 ID 和完全相符的引數，不能同時提供兩者。
• 退貨：依遞減核發排序的搜尋結果。
• 傳回類型： list[SearchResult]
• 增加：ValueError – 如果 scope 與明確的 ID 或完全相符引數結合，如果 max_results 小於 1，或者 metadata_filter 既不是說明也不是 None，

備註

省略的範圍欄位會繼承此繫線的預設搜尋範圍：完全符合的使用者和代理程式，加上此繫線的目前 user_id、agent_id 和 thread_id。預設執行緒會故意留下 exact_thread_match=False，因此可能會從相同使用者 / 代理程式的其他執行緒傳回相關記錄。傳送 exact_thread_match=True 以將結果限制為目前的繫線。明確的 None 範圍值仍然遵循解析的完全相符規則：exact_*_match=False 會讓該維度維持不限制，而 exact_*_match=True 則只比對儲存的 None 值。

明確的 max_results 值必須至少為 1；省略引數會使用預設值 10。此為上限：當篩選條件的限制性太大、相符的記錄較少或因為實作特定的搜尋行為而導致呼叫傳回的結果可能少於 max_results。

方法 update_image

更新此執行緒擁有的一個影像。

省略 image 以保留現有的位元組。如果提供 image，則必須隨其提供 mime_type。省略 description 以保留現有的描述。傳送 None 以使用設定的 LLM 產生新的描述；非空值描述會直接取代它。附加至訊息之影像的到期時間必須透過 update_message() 變更。

• 傳回：更新的影像 ID。
• 傳回類型： str
• 發出：ValueError – 如果為附加至訊息的圖像提供過期設定。
• 參數：
  • image_id str
  • 影像 bytes
  • 說明 str | None
  • mime_typeImageMimeType
  • 中繼資料 dict[str, Any] | None
  • 時間戳記 str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

方法 update_image_async (非同步)

以非同步方式更新此執行緒所擁有的影像。

省略 image 以保留現有的位元組。如果提供 image，則必須隨其提供 mime_type。省略 description 以保留現有的描述。傳送 None 以使用設定的 LLM 產生新的描述；非空值描述會直接取代它。提供時會更新描述資料、時戳和到期設定值。附加至訊息之影像的到期時間必須透過 update_message_async() 變更。

• 傳回：更新的影像 ID。
• 傳回類型： str
• 發出：ValueError – 如果為附加至訊息的圖像提供過期設定。
• 參數：
  • image_id str
  • 影像 bytes
  • 說明 str | None
  • mime_typeImageMimeType
  • 中繼資料 dict[str, Any] | None
  • 時間戳記 str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

方法 update_memory

更新此確切執行緒所擁有的類似記憶體記錄。

• 參數：
  • memory_id str – 記憶體 ID。只有儲存的 thread_id 完全符合此繫線的類似記憶體記錄 (memory、guideline、fact、preference) 才會更新。
  • content str – 可選替代內容。提供字串以取代儲存的內容。省略時，會保留儲存的內容。省略 content 以保留目前的值，或使用 delete_memory() 來移除記錄。
  • 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。省略時，會保留儲存的中繼資料。若有提供，它會取代儲存的描述資料物件；此 API 並非深層合併描述資料。
  • timestamp str | None – 此記憶體的選擇性新時戳。它代表記憶體建立的時間。省略時，會保留儲存的時間戳記。傳送 None 以清除儲存的時間戳記，並使用在商店中建立記錄的時間。當 ttl_anchor 為 TimeToLiveAnchor.TIMESTAMP 時，取代時戳必須是 ISO-8601 字串。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired memories are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為記憶體建立時間，使用 TimeToLiveAnchor.TIMESTAMP 作為相同更新中提供的取代 timestamp，或省略 timestamp 時的儲存事件時戳。提供不含 ttl_days 的 ttl_anchor 會使用綱要預設存留時間持續時間。進行重新整理時省略 ttl_anchor 時，繫線會使用 TimeToLiveAnchor.CREATED_AT。時間戳記錨定重新整理需要相同呼叫中的替代 ISO-8601 時間戳記，或該格式的現有儲存事件時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • status (狀態) RecordStatus – 此類似記憶體之記錄的選擇性取代生命週期狀態。省略以保留目前的狀態。
  • **kwargs ( 任一 ) – 會拒絕非預期的關鍵字引數。
• 傳回：更新之類似記憶體記錄的 ID。
• 傳回類型： str

方法 update_memory_async (非同步)

以非同步方式更新此確切執行緒所擁有的類似記憶體記錄。

• 參數：
  • memory_id str – 記憶體 ID。只有儲存的 thread_id 完全符合此繫線的類似記憶體記錄 (memory、guideline、fact、preference) 才會更新。
  • content str – 可選替代內容。提供字串以取代儲存的內容。省略時，會保留儲存的內容。省略 content 以保留目前的值，或使用 delete_memory() 來移除記錄。
  • 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。省略時，會保留儲存的中繼資料。若有提供，它會取代儲存的描述資料物件；此 API 並非深層合併描述資料。
  • timestamp str | None – 此記憶體的選擇性新時戳。它代表記憶體建立的時間。省略時，會保留儲存的時間戳記。傳送 None 以清除儲存的時間戳記，並使用在商店中建立記錄的時間。當 ttl_anchor 為 TimeToLiveAnchor.TIMESTAMP 時，取代時戳必須是 ISO-8601 字串。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired memories are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。使用 TimeToLiveAnchor.CREATED_AT 作為記憶體建立時間，使用 TimeToLiveAnchor.TIMESTAMP 作為相同更新中提供的取代 timestamp，或省略 timestamp 時的儲存事件時戳。提供不含 ttl_days 的 ttl_anchor 會使用綱要預設存留時間持續時間。進行重新整理時省略 ttl_anchor 時，繫線會使用 TimeToLiveAnchor.CREATED_AT。時間戳記錨定重新整理需要相同呼叫中的替代 ISO-8601 時間戳記，或該格式的現有儲存事件時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • status (狀態) RecordStatus – 此類似記憶體之記錄的選擇性取代生命週期狀態。省略以保留目前的狀態。
  • **kwargs ( 任一 ) – 會拒絕非預期的關鍵字引數。
• 傳回：更新之類似記憶體記錄的 ID。
• 傳回類型： str

範例

import asyncio
memory_id = asyncio.run(thread.add_memory_async("Original memory"))
(
    asyncio.run(thread.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

方法 update_message

更新此確切執行緒所擁有的原始訊息記錄。

• 參數：
  • message_id str – 訊息 ID。只會更新其儲存的 thread_id 完全符合此討論串的訊息。
  • content str | list[Mapping[str, Any]] – 可選替代訊息內容。提供字串以取代儲存的內容，或依序排列的文字與影像內容部分。省略時，會保留儲存的內容。使用空字串以空白文字內容取代它。
  • 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。省略時，會保留儲存的中繼資料。若有提供，它會取代儲存的描述資料物件；此 API 並非深層合併描述資料。
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired messages are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。針對訊息建立時間使用 TimeToLiveAnchor.CREATED_AT，或針對儲存的事件時戳使用 TimeToLiveAnchor.TIMESTAMP。提供不含 ttl_days 的 ttl_anchor 會使用綱要預設存留時間持續時間。進行重新整理時省略 ttl_anchor 時，繫線會使用 TimeToLiveAnchor.CREATED_AT。時間戳記錨定重新整理需要現有的儲存 ISO-8601 訊息時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • **kwargs ( 任一 ) – 會拒絕非預期的關鍵字引數。
• 傳回：已更新訊息記錄的識別碼。
• 傳回類型： str

備註

省略的欄位會從儲存的記錄中保留。儲存的角色和時戳維持不變。編輯內容會更新原始訊息歷史記錄，若啟用自動擷取功能，可能會讓 SDK 從已編輯訊息和較早的歷史記錄中重新擷取記憶體。在 INLINE 模式中，擷取會在此方法傳回之前完成。在 BACKGROUND 模式中，此方法會在原始訊息更新成功且嘗試背景擷取之後傳回。此後續追蹤工作不會影響後續 add_messages() 呼叫所使用的一般擷取頻率。新增從編輯內容擷取的記憶時，現有擷取的記憶會保留在原位。因為原始訊息更新和之後擷取的任何記憶體寫入都不會異常地發生，所以如果背景工作未排入佇列、設定的佇列容量等待達到其逾時，或稍後擷取工作失敗，則擷取的記憶體仍可反映先前的訊息內容。另請注意，當來源訊息的 TTL 變更時，現有擷取的記憶體會保留其原始到期時間。

範例

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

方法 update_message_async (非同步)

以非同步方式更新此確切執行緒所擁有的原始訊息記錄。

• 參數：
  • message_id str – 訊息 ID。只會更新其儲存的 thread_id 完全符合此討論串的訊息。
  • content str | list[Mapping[str, Any]] – 可選替代訊息內容。提供字串以取代儲存的內容，或依序排列的文字與影像內容部分。省略時，會保留儲存的內容。使用空字串以空白文字內容取代它。
  • 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料對應。省略時，會保留儲存的中繼資料。若有提供，它會取代儲存的描述資料物件；此 API 並非深層合併描述資料。
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired messages are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor – 過期重新整理的選擇性存留時間錨點。針對訊息建立時間使用 TimeToLiveAnchor.CREATED_AT，或針對儲存的事件時戳使用 TimeToLiveAnchor.TIMESTAMP。提供不含 ttl_days 的 ttl_anchor 會使用綱要預設存留時間持續時間。時間戳記錨定重新整理需要現有的儲存 ISO-8601 訊息時間戳記。沒有時區的 ISO-8601 時間戳記會被視為 UTC。
  • **kwargs ( 任一 ) – 會拒絕非預期的關鍵字引數。
• 傳回：已更新訊息記錄的識別碼。
• 傳回類型： str

備註

省略的欄位會從儲存的記錄中保留。儲存的角色和時戳維持不變。編輯內容會更新原始訊息歷史記錄，若啟用自動擷取功能，可能會讓 SDK 從已編輯訊息和較早的歷史記錄中重新擷取記憶體。在 INLINE 模式中，擷取會在此方法傳回之前完成。在 BACKGROUND 模式中，此方法會在原始訊息更新成功且嘗試背景擷取之後傳回。此後續追蹤工作不會影響後續 add_messages() 呼叫所使用的一般擷取頻率。新增從編輯內容擷取的記憶時，現有擷取的記憶會保留在原位。因為原始訊息更新和之後擷取的任何記憶體寫入都不會異常地發生，所以如果背景工作未排入佇列、設定的佇列容量等待達到其逾時，或稍後擷取工作失敗，則擷取的記憶體仍可反映先前的訊息內容。另請注意，當來源訊息的 TTL 變更時，現有擷取的記憶體會保留其原始到期時間。

範例

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Draft message"}]
))
(
    asyncio.run(thread.update_message_async(
        message_ids[0], content="Edited message"
    ))
    == message_ids[0]
)
True

方法 update_record_link

更新此繫線所擁有端點的關係。

省略的值會被保留。當 relation_type 變更為內建記憶體關係類型時，其固定反向標籤會取代 opposite_relation_type。

• 參數：
  • relation_id str – 執行緒擁有之關係的識別碼。
  • relation_type str – 可選的取代來源至目標標籤。
  • opposite_relation_type str – 選擇性的取代反向追蹤標籤。省略以保留預存標籤。
  • timestamp str | None – 選擇性取代時間戳記。傳送 None 以將其清除。
  • 中繼資料 dict[str, Any] | None – 選擇性取代中繼資料。它會取代預存物件。
• 傳回：更新的關係數目，可以是 0 或 1。
• 傳回類型：整數

範例

thread.update_record_link("relation-id", relation_type="supports")
1

方法 update_record_link_async (非同步)

非同步更新其端點屬於此繫線的關係。

• 參數：
  • relation_id str
  • relation_typestr
  • opposite_relation_type str
  • 時間戳記 str | None
  • 中繼資料 dict[str, Any] | None
• 傳回類型：整數

方法 wait_for_memory_extraction

等待此執行緒的較早背景記憶體擷取。

此方法會等待先前 add_messages()、add_messages_async()、update_message() 或 update_message_async() 透過相同代理程式記憶體元件對此繫線進行的背景擷取。如果其中一個呼叫已經完成，此方法會包含它在等待之前開始的擷取。

此方法不會等待此等待開始後開始擷取、由其他代理程式記憶體元件啟動擷取，或是在其他處理作業中執行的擷取。此等待的擷取失敗計數為已完成。

• 參數：timeout float | None – 選擇性的等待秒數上限。預設為 300。傳送 None，等待此繫線的待處理擷取完成。
• 發出：TimeoutError – 在先前的背景擷取完成之前逾時即觸發。
• 傳回類型：無

範例

thread.wait_for_memory_extraction(timeout=10)

方法 wait_for_memory_extraction_async (非同步)

非同步等待更早的背景記憶體擷取。

此方法遵循與 wait_for_memory_extraction() 相同的行為。

• 參數：timeout float | None – 選擇性的等待秒數上限。預設為 300。傳遞 None 以無限期等待。
• 發出：TimeoutError – 在先前的背景擷取完成之前逾時即觸發。
• 傳回類型：無

範例

import asyncio
asyncio.run(thread.wait_for_memory_extraction_async(timeout=10))

注意：delete_message() 只會刪除原始訊息資料列。衍生的記憶卡仍可搜尋或出現在內容卡中。使用 OracleAgentMemory.delete_thread() 可將繫線與其相關的訊息和記憶體一起刪除。透過繫線處理刪除訊息和記憶體會等待附加的從屬端針對該繫線所接受的較早背景擷取。這並非其他用戶端實例、程序，或等待開始後接受之工作的全域並行作業障礙。

訊息與訊息內容

類別 oracleagentmemory.apis.message.Message

基礎：object

執行緒與 LLM 轉接器共用的記憶體內訊息。

• 參數：
  • role str – 訊息角色。繫線訊息允許自訂角色名稱。
  • content str | collections.abc.Sequence[oracleagentmemory.apis.message.MessageContent] – 訊息文字或依序排列的 TextContent 和 ImageContent 部分。內容順序不得空白，且儲存為不可變元組。
  • timestamp str | None – 與訊息關聯的選擇性時間戳記。
  • 中繼資料 dict[str, Any] | None – 與訊息相關聯的選擇性 JSON 相容中繼資料。
  • id str | None – 選擇性穩定訊息 ID。當新增的訊息沒有識別碼時，商店會產生一個。

類別 oracleagentmemory.apis.message.MessageContent

基本：ABC

結構化訊息內容的基本類別。

• 參數：
  • id str – 此內容部分的穩定 ID。省略時自動產生。
  • timestamp str | None – 與此內容部分關聯的選擇性時間戳記。

類別 oracleagentmemory.apis.message.TextContent

基本：MessageContent

多重模型訊息中的文字部分。

• 參數：
  • 文字 str – 此內容部分所執行的文字。
  • id str – 繼承自 MessageContent 的穩定 ID。省略時自動產生。
  • timestamp str | None – 繼承自 MessageContent 的選擇性時戳。

類別 oracleagentmemory.apis.message.ImageContent

基本：MessageContent

多重模型訊息中的影像部分。

• 參數：
  • bytes bytes | None – 影像資料 (若有的話)。當訊息包含影像中繼資料而未載入影像位元組時，允許使用 None。
  • mime_type oracleagentmemory.apis.message.ImageMimeType – 影像 MIME 類型。
  • 說明 str | None – 描述影像的選擇性文字。None 時，高階影像與訊息 API 可能會使用其設定的 LLM 產生描述。
  • id str – 繼承自 MessageContent 的穩定 ID。省略時自動產生。
  • timestamp str | None – 繼承自 MessageContent 的選擇性時戳。

類別 oracleagentmemory.apis.message.ImageMimeType

基礎：str、Enum

影像內容支援的 MIME 類型。

不支援動畫 PNG 與 WebP。

JPEG = 'image/JPEG'

PNG = 'image/PNG'

WEBP = 'image/WEBP'

內容卡

類別 oracleagentmemory.apis.contextcard.ContextCard

基本：ABC

繫線 API 傳回的抽象相關資訊環境卡物件。

property content (摘要)

• 傳回類型： str
• 描述：傳回轉譯的內容卡文字。

類別 oracleagentmemory.core.contextcard.OracleContextCard

基本：ContextCard

Oracle 執行緒傳回的內容卡。

• 參數：
  • summary str – 卡片中內嵌的摘要文字。
  • 主題 Sequence[str] | None – 與執行緒關聯的選擇性擷取主題。
  • relevant_results Sequence[SearchResult] | None – 卡片中包含的選擇性擷取持久記錄。
  • recent_messages Sequence[Message] | None – 可選擇將最近的原始訊息轉譯到卡片中。
  • message_format str – 呈現 recent_messages 時使用的內部範本。

特性 content

• 傳回類型： str

• 描述：傳回轉譯的內容卡文字。

• 傳回：類似 XML 的轉譯相關資訊環境卡文字，適用於提示組合。
• 傳回類型： str

範例

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

特性 formatted_content

• 傳回類型： str

• 描述：傳回用於提示建立流程的已轉譯內容卡文字。

• 傳回： 類似 XML 的轉譯內容卡文字。
• 傳回類型： str

範例

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

摘要

類別 oracleagentmemory.apis.summary.Summary

基本：ABC

繫線 API 傳回的抽象繫線摘要物件。

property content (摘要)

• 傳回類型： str
• 描述：傳回合成摘要文字。

類別 oracleagentmemory.core.summary.OracleSummary

基本：Summary

Oracle 執行緒傳回的摘要。

• 參數： content str – 從繫線記錄合成的摘要文字。

範例

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

特性 content

• 傳回類型： str

• 描述：傳回合成摘要文字。

• 傳回：執行緒的摘要文字。
• 傳回類型： str

範例

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

特性 formatted_content

• 傳回類型： str

• 描述：傳回用於提示建立流程的轉譯摘要文字。

• 傳回：呈現的摘要文字。
• 傳回類型： str

範例

OracleSummary(content="Thread recap").formatted_content
'Thread recap'