Kontextkarteninhalt anpassen

Eine Kontextkarte bietet kompakten Kontext zu einer Unterhaltung, die ein Agent beim Generieren einer Antwort verwenden kann. Es kann eine Konversationsthreadzusammenfassung, relevante gespeicherte Nachrichten und relevante Speicher enthalten.

In diesem Handbuch wird erläutert, wie Sie den in Oracle AI Agent Memory-Kontextkarten zurückgegebenen Inhalt anpassen.

Kontextkarten, die von get_context_card() zurückgegeben werden, können auch Abrufthemen und relevante Datensätze enthalten. Verwenden Sie Kontextkarten, wenn ein Agent für eine lange Unterhaltung Kontinuität benötigt, das vollständige Transkript jedoch nicht an das Modell zurückgesendet werden muss. Dies kann die Verwendung von Eingabetokens reduzieren, den Agent fokussieren und die Notwendigkeit einiger Toolaufrufe auf Agent-Ebene reduzieren, indem der relevante Speicher im Prompt-Kontext im Voraus platziert wird.

Einen vollständigen Prompt-Compaction-Workflow mit LangGraph finden Sie unter Oracle Agent Memory Short-Term APIs mit LangGraph verwenden. API-Details finden Sie unter OracleThread und Kontextkarten.

Hinweis: Verwenden Sie die Anpassung der Kontextkarte, wenn die Standardabrufergebnisse nicht die richtige Mischung aus Datensatztypen enthalten. Beispiel: Eine Anwendung kann Speicherplatz für Benutzervoreinstellungen oder Antwortrichtlinien reservieren, wenn allgemeine Fakten die Ergebnisse sonst dominieren würden.

Informationen zum Konfigurieren von Ergebnislimits, Rangfolge-, Pruning- oder Tokenbudgets für Suchen und Kontextkarten finden Sie unter Relevanz der Suchergebnisse verbessern.

Minimale Ergebnisse nach Datensatztyp anfordern

Standardmäßig durchsucht Kontextkartenabruf alle speicherähnlichen Datensatztypen gleichzeitig. Beispiel: Wenn Fakten oder allgemeine Erinnerungen Voreinstellungen oder Richtlinien verdrängen, übergeben Sie min_relevant_results_by_type, um Mindestanzahlen für bestimmte Datensatztypen zu verlangen.

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="provider/model_id")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_CARD_CONTENT"

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id
)

thread = memory.create_thread(
    thread_id="context_card_customization_demo",
    user_id="user_123",
    agent_id="assistant_456",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Extract restaurant preferences as preference records and assistant "
            "response-style instructions as guideline records."
        )
    ),
)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "I need vegetarian dinner recommendations for Friday.",
        },
        {
            "role": "assistant",
            "content": "I can compare concise options and tradeoffs.",
        },
    ]
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

prompt_context = card.content
print(prompt_context)

Die gerenderte Karte ist XML-ähnlicher Prompt-Text. Die genauen Datensätze hängen von Ihren gespeicherten Daten ab. Der Abschnitt <relevant_information> kann jedoch die angeforderten Typen enthalten, bevor die restlichen Ergebnisse aus der Suche nach All-Memory-Typen abgerufen werden:

<context_card>
  <summary>
    User is planning dinner recommendations.
  </summary>
  <topics>
    <topic>pizza planning</topic>
    <topic>dinner</topic>
  </topics>
  <relevant_information>
    <preference>
      <content>User prefers vegetarian restaurants.</content>
    </preference>
    <guideline>
      <content>Offer concise recommendations with clear tradeoffs.</content>
    </guideline>
    <memory>
      <content>User is comparing pizza places for Friday.</content>
    </memory>
  </relevant_information>
  <recent_messages>
    ...
  </recent_messages>
</context_card>

Die Mindestwerte sind die beste Anstrengung. Wenn nicht genügend übereinstimmende Datensätze für einen angeforderten Typ vorhanden sind, ist der Aufruf dennoch erfolgreich. Übereinstimmungen von jedem unterstützten speicherähnlichen Datensatztyp können die verbleibenden Ergebnis-Slots verwenden. Die endgültigen relevanten Datensätze werden immer durch max_relevant_results begrenzt.

Unterstützte Schlüssel sind "memory", "fact", "guideline", "preference" und "message". Nachrichtenergebnisse werden nur im aktuellen Thread durchsucht. Die anderen Datensatztypen behalten den normalen Suchbereich für Benutzer/Agent bei. Lassen Sie min_relevant_results_by_type weg, um das Standardabrufverhalten beizubehalten.

Beim Erstellen einer Kontextkarte durchsucht Oracle Agent Memory speicherähnliche Datensätze getrennt von Nachrichten im aktuellen Thread. Bei der Konfiguration des Umschneidens oder Beschneidens wird es separat auf jeden Ergebnissatz angewendet, bevor die Sätze kombiniert werden. Wenn min_relevant_results_by_type angegeben wird, wird jeder angeforderte Datensatztyp separat durchsucht. Nachträglich oder beschneiden, wenn konfiguriert, wird auch separat auf die Ergebnisse jeder Suche angewendet. Eine weitere Suche über alle speicherähnlichen Datensatztypen hinweg kann dann alle verbleibenden Ergebnis-Slots verwenden.

Wenn für eine reguläre Suche, die mehrere record_types anfordert, eine erneute Einstufung oder Pruning konfiguriert ist, wird diese einmal auf die kombinierten Suchergebnisse angewendet.

Wenn max_relevant_results ausgelassen wird, verwendet Oracle Agent Memory das Standardbudget für relevante Ergebnisse, es sei denn, die angeforderte Mindestsumme ist größer. In diesem Fall wird das effektive Budget entsprechend dem geforderten Mindestbetrag erweitert.

Nebenläufigkeit für Suchtyp optimieren

Die Erstellung einer Kontextkarte kann eine Suche für jeden angeforderten Datensatztyp sowie eine Suche über alle speicherähnlichen Datensatztypen hinweg ausführen, um verbleibende Ergebnis-Slots zu verwenden. Standardmäßig können bis zu fünf dieser Suchen gleichzeitig ausgeführt werden. Um die Anzahl gleichzeitiger Suchen nach einem Live-Thread-Handle zu reduzieren, übergeben Sie context_card_type_search_concurrency, wenn Sie den Thread erstellen oder erneut öffnen. Dieser Wert wird in der Threadzeile nicht beibehalten:

thread = memory.get_thread(
    "context_card_customization_demo",
    context_card_type_search_concurrency=2,
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

Abschluss

In diesem Handbuch haben wir gelernt, wie Sie die minimale Anzahl von Kontextkartenergebnissen für bestimmte speicherähnliche Datensatztypen anfordern und wie Sie das parallele Such-Fanout optimieren, das vom Abruf pro Typ verwendet wird.

→ Nachdem Sie gelernt haben, wie Sie das Abrufen von Kontextkarten anpassen, können Sie jetzt mit Oracle Agent Memory Short-Term APIs mit LangGraph verwenden fortfahren.

Vollständiger Code

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Customize Context Card Content
#-----------------------------------------------------------------

##Reserve relevant results by record type

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="provider/model_id")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_CARD_CONTENT"

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id
)

thread = memory.create_thread(
    thread_id="context_card_customization_demo",
    user_id="user_123",
    agent_id="assistant_456",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Extract restaurant preferences as preference records and assistant "
            "response-style instructions as guideline records."
        )
    ),
)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "I need vegetarian dinner recommendations for Friday.",
        },
        {
            "role": "assistant",
            "content": "I can compare concise options and tradeoffs.",
        },
    ]
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

prompt_context = card.content
print(prompt_context)

##Tune type search concurrency

thread = memory.get_thread(
    "context_card_customization_demo",
    context_card_type_search_concurrency=2,
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)