Threads

Auf dieser Seite wird das konkrete Oracle-Thread-Handle zusammen mit dem Entwickler-Helper-Typ vorgestellt.

Oracle-Thread

Klasse oracleagentmemory.core.OracleThread

Basen: IThread

Thread wird von einem Oracle-Speicher unterstützt.

Diese Implementierung integriert und speichert sowohl Thread-Nachrichten als auch manuell hinzugefügte Speicher und unterstützt dann die Ähnlichkeitssuche über alle gespeicherten Datensätze.

Hinweise

• Nachrichten werden als einzelne Datensätze gespeichert (ein Datensatz pro Nachricht).
• Die Suche kann auf den aktuellen Thread beschränkt sein oder Ergebnisse aus einem beliebigen Thread zurückgeben (Client-gesteuert).

Neuen Thread-Handle erstellen.

• Parameter:
  • store OracleMemoryStore: Shared Store-Backend, das zum Persistieren eingebetteter Datensätze verwendet wird.
  • thread_id str: Thread-ID. Wenn keine Angabe gemacht wird, wird eine UUID generiert.
  • user_id str: Mit dem Thread verknüpfte Benutzer-ID. Wird kein Wert angegeben, wird eine UUID generiert.
  • agent_id str: Agent-ID, die mit dem Thread verknüpft ist. Wird kein Wert angegeben, wird eine UUID generiert.
  • persist_messages_in_config bool – Gibt an, ob _to_config aktuelle Raw-Nachrichten-Snapshots enthalten soll. Wird automatisch für Threads, die den DB-Speicher verwenden, auf False gesetzt, um zu vermeiden, dass Inhalt der Meldungstabelle über die Threadkonfiguration exportiert wird.
  • LLM ILlm | None – Optionaler LLM-Adapter für Speicherextraktion und Aktualisierungen der Kontextübersicht. Wenn angegeben, extrahiert add_messages relevante Speicher aus jeder hinzugefügten Nachricht und speichert sie als record_type="memory".
  • memory_extraction_window int: Anzahl der neuesten Nachrichten (einschließlich der neu hinzugefügten Nachrichten), die während der Extraktion als Kontext für das LLM bereitgestellt werden. Setzen Sie diesen Wert auf -1, um nur einmal pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten zu extrahieren. Standard ist -1.
  • context_summary_update_frequency int – Anzahl der Nachrichten, nach denen die Kontextübersicht aktualisiert werden soll. Setzen Sie diesen Wert auf -1, um nur einmal pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten zusammenzufassen. Dieselbe Häufigkeit wird beim Aktualisieren von Threadzusammenfassungsmetadaten während Transkriptschreibvorgängen wieder verwendet.
  • memory_extraction_frequency int: Anzahl der Nachrichten, nach denen die Speicherextraktion ausgelöst wird. Setzen Sie diesen Wert auf -1, um nur einmal pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten zu extrahieren.
  • memory_extraction_token_limit int – Maximale Größe der Prompts, die bei der Speicherextraktion in Token verwendet werden. Längere Eingabeaufforderungen werden abgeschnitten. Wenn negativ oder 0, wird keine Abschneidung durchgeführt.
  • max_message_token_length int – Maximale Größe der Prompt-Time-Kopie jeder Nachricht, die während der LLM-gesicherten Speicherextraktion und Aktualisierungen der Kontextzusammenfassung verwendet wird, in Token. Der gespeicherte Nachrichteninhalt bleibt unverändert. Wenn negativ oder 0, wird keine Verkürzung der Prompt-Zeit durchgeführt. Wenn ein LLM bereitgestellt wird, werden übergroße Prompt-Kopien zusammengefasst und nicht abgeschnitten.
  • message_shortening_input_token_limit int – Maximale Größe des Nachrichtenauszugs in Token, der an das LLM gesendet wird, wenn übergroße Prompt-Kopien gekürzt werden. Standard ist 30_000-Token. Wenn negativ oder 0, wird während der LLM-basierten Verkürzung keine ausgehende Grenze angewendet.
  • enable_context_summary bool – Gibt an, ob eine kompakte Zusammenfassung des Threads ausgeführt werden soll. Wenn diese Option aktiviert ist und eine llm angegeben ist, wird die Übersicht gemäß context_summary_update_frequency aktualisiert. Die aktuelle Zusammenfassung wird als Kontext beim Extrahieren von Speichern bereitgestellt.
  • Client Any | None

Beispiele

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

Methode add_memory

Fügen Sie einen manuellen Speichereintrag hinzu, und indexieren Sie ihn.

• Parameter:
  • content str: Textinhalt, der als Speicher gespeichert werden soll.
  • user_id str: Optionales Überschreiben der Benutzer-ID.
  • agent_id str: Optionales Überschreiben der Agent-ID.
  • thread_id str – Optionales Überschreiben der Thread-ID.
  • memory_id str – Optionale vom Aufrufer bereitgestellte stabile ID für diese Speicherzeile.
  • **store_kwargs (Beliebige) – Speicherspezifische Schreiboptionen, die an den zugrunde liegenden Speicher weitergeleitet werden.
• Rückgaben: ID des eingefügten Speicherdatensatzes.
• Rückgabetyp: str

Beispiele

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

Methode add_messages

Fügen Sie dem Thread Nachrichten hinzu, und indexieren Sie sie.

• Parameter:
  • Nachrichten list[Message | MessageT]: Liste der anzuhängenden Nachrichten. Nachrichten können Message-Objekte oder Wörterbücher mit role und content (und optional id) sein.
  • **store_kwargs (Beliebige) – Speicherspezifische Schreiboptionen, die an den zugrunde liegenden Speicher weitergeleitet werden.
• Rücksendungen: IDs eingefügter Meldungsdatensätze.
• Rückgabetyp: list[str]

Beispiele

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

Methode add_messages_async (asynchron)

Fügen Sie dem Thread asynchron Nachrichten hinzu, und indexieren Sie sie.

• Parameter:
  • Nachrichten list[Message | MessageT]
  • store_kwargs Any
• Rückgabetyp: list[str]

Methode delete_memory

Speicherdatensatz nach Kennung aus diesem Thread löschen.

• Parameter: memory_id str – Speicher-ID. Nur Speicher, deren gespeicherte thread_id genau mit diesem Thread übereinstimmt, werden gelöscht.
• Rücksendungen: Anzahl der gelöschten Datensätze (0 oder 1). Gibt 0 zurück, wenn die ID nicht vorhanden ist oder zu einem anderen Thread gehört.
• Rückgabetyp: int

Beispiele

thread.delete_memory("456")
0

Methode delete_message

Meldungsdatensatz aus diesem Thread nach ID löschen.

• Parameter: message_id str: Nachrichten-ID. Nur Nachrichten, deren gespeicherte thread_id genau mit diesem Thread übereinstimmt, werden gelöscht.
• Rücksendungen: Anzahl der gelöschten Datensätze (0 oder 1). Gibt 0 zurück, wenn die ID nicht vorhanden ist oder zu einem anderen Thread gehört.
• Rückgabetyp: int

Hinweise

Beim erfolgreichen Löschen wird der abgeleitete Thread-Zusammenfassungsstatus gelöscht, sodass später Zusammenfassungs- und Kontextkartenaufrufe aus dem verbleibenden Transkript neu erstellt werden. Abgeleitete Speicher werden nicht automatisch gelöscht, da extrahierte Speicher derzeit nicht pro Nachrichtenherkunft beibehalten werden.

Beispiele

thread.delete_message("123")
0

Methode get_context_card

Gibt eine XML-ähnliche Kontextkarte für den Thread zurück.

Wählen Sie get_context_card_async, wenn eine LLM-gestützte Implementierung Remote-Netzwerk-I/O ausführen kann.

• Parameter:
  • fallback_message_count int: Anzahl der letzten Nachrichten, die verwendet werden sollen, wenn der Fallback-Zusammenfassungstext zum Abrufen und Rendering abgeleitet wird.
  • max_relevant_results int – Maximale Anzahl der abgerufenen dauerhaften Datensätze, die eingeschlossen werden sollen.
  • max_recent_messages int: Maximale Anzahl der nachgestellten Raw-Nachrichten, die ausführlich eingebettet werden.
  • **kwargs (Beliebig) – Reserviert für zukünftige Kontextkartenoptionen. Unerwartete Schlüsselwortargumente lösen TypeError aus.
• Rückgaben: Eine Karte, die eine Threadkontextübersicht basierend auf den neuesten Nachrichten enthält.
• Rückgabetyp: str

Hinweise

Dabei wird der standardmäßige Suchgeltungsbereich des Threads mit exact_thread_match=False verwendet, sodass relevante Speicher aus anderen Threads für denselben Benutzer/Agent enthalten sein können.

Beispiele

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()
True

Methode get_context_card_async (asynchron)

Gibt asynchron eine XML-ähnliche Kontextkarte für den Thread zurück.

• Parameter:
  • fallback_message_count int: Anzahl der letzten Nachrichten, die verwendet werden sollen, wenn der Fallback-Zusammenfassungstext zum Abrufen und Rendering abgeleitet wird.
  • max_relevant_results int – Maximale Anzahl der abgerufenen dauerhaften Datensätze, die eingeschlossen werden sollen.
  • max_recent_messages int: Maximale Anzahl der nachgestellten Raw-Nachrichten, die ausführlich eingebettet werden.
  • **kwargs (Beliebig) – Reserviert für zukünftige Kontextkartenoptionen. Unerwartete Schlüsselwortargumente lösen TypeError aus.
• Rücksendungen: Eine Karte, die eine Threadkontextübersicht basierend auf den neuesten Nachrichten enthält.
• Rückgabetyp: str

Methode get_messages

Gespeicherte Nachrichten für diesen Thread zurückgeben.

• Parameter:
  • start int | None: Startindex (0-basiert). Wenn zusammen mit end ausgelassen wird, wird das zuletzt beschränkte Fenster zurückgegeben.
  • end int | None: Endindex (exklusiv). Wenn diese Option ausgelassen wird, wird ein begrenztes Fenster mit den neuesten Nachrichten zurückgegeben. Übergeben Sie None oder -1, um alle Nachrichten ab start explizit anzufordern.
• Rückgaben: Nachrichten in chronologischer Reihenfolge.
• Liste Rückgabetyp:[Nachricht]

Beispiele

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

Methode get_summary

Gibt eine Best Effort-Zusammenfassung des Threads zurück.

Wählen Sie get_summary_async, wenn eine LLM-gestützte Implementierung Remote-Netzwerk-I/O ausführen kann.

• Parameter:
  • except_last int – Anzahl der letzten Nachrichten, die aus der Übersicht ausgeschlossen werden sollen.
  • token_budget int: Budget für Soft-Token. Wenn kein Wert angegeben wird, wird ein gebundener Standardwert angewendet. Positive Werte werden nur abgeschnitten, wenn die formatierte Übersicht das Budget nach der Schätzung von _estimate_tokens() überschreitet. Der zurückgegebene Text wird dann auf int(token_budget * 3.5) Zeichen begrenzt. Nicht positive Werte deaktivieren die Ausgabegrenze.
  • **kwargs (Beliebig) – Reserviert für zukünftige Übersichtsoptionen. Unerwartete Schlüsselwortargumente lösen TypeError aus.
• Rückgaben: Eine Assistenznachricht mit der Zusammenfassung oder eine leere Liste, wenn der Thread keine Nachrichten enthält.
• Liste Rückgabetyp:[Nachricht]

Beispiele

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

Methode get_summary_async (asynchron)

Gibt asynchron eine Best Effort-Zusammenfassung des Threads zurück.

• Parameter:
  • except_last int – Anzahl der letzten Nachrichten, die aus der Übersicht ausgeschlossen werden sollen.
  • token_budget int: Budget für Soft-Token. Wenn kein Wert angegeben wird, wird ein gebundener Standardwert angewendet. Positive Werte werden nur abgeschnitten, wenn die formatierte Übersicht das Budget nach der Schätzung von _estimate_tokens() überschreitet. Der zurückgegebene Text wird dann auf int(token_budget * 3.5) Zeichen begrenzt. Nicht positive Werte deaktivieren die Ausgabegrenze.
  • **kwargs (Beliebig) – Reserviert für zukünftige Übersichtsoptionen. Unerwartete Schlüsselwortargumente lösen TypeError aus.
• Rückgaben: Eine Assistenznachricht mit der Zusammenfassung oder eine leere Liste, wenn der Thread keine Nachrichten enthält.
• Liste Rückgabetyp:[Nachricht]

Nachrichten

Klasse oracleagentmemory.apis.thread.Message

Basis: object

• Parameter:
  • Rolle str
  • Inhalt str
  • Zeitstempel str | None
  • Metadaten dict[str, Any] | None
  • ID str | None