Personalizza contenuto scheda contesto

Una scheda contesto fornisce un contesto compatto su una conversazione che un agente può utilizzare durante la generazione di una risposta. Può includere un riepilogo del thread di conversazione, messaggi archiviati pertinenti e memorie pertinenti.

Questa guida spiega come personalizzare il contenuto restituito nelle schede di contesto di Oracle AI Agent Memory.

Le schede contesto restituite da get_context_card() possono includere anche argomenti di recupero e record pertinenti. Utilizzare le schede contesto quando un agente ha bisogno di continuità in una lunga conversazione, ma non ha bisogno della trascrizione completa inviata di nuovo al modello. Ciò può ridurre l'uso del token di input, mantenere l'agente attivo e ridurre la necessità di alcune chiamate agli strumenti a livello di agente posizionando la memoria rilevante nel contesto del prompt in alto.

Per un flusso di lavoro di compattazione rapida completo con LangGraph, vedere Utilizzare le API a breve termine della memoria di Oracle Agent con LangGraph. Per informazioni dettagliate sulle API, vedere OracleThread e Context Cards.

Nota: utilizzare la personalizzazione della scheda di contesto quando i risultati di recupero predefiniti non includono la combinazione corretta dei tipi di record. Ad esempio, un'applicazione può riservare spazio per le preferenze utente o le linee guida di risposta quando i fatti generali dominano i risultati.

Per configurare i limiti dei risultati, la riclassificazione, l'eliminazione o i budget token sia per le ricerche che per le schede di contesto, vedere Migliorare la rilevanza dei risultati della ricerca.

Risultati minimi richiesta per tipo di record

Per impostazione predefinita, il recupero delle schede di contesto esegue contemporaneamente ricerche in tutti i tipi di record simili alla memoria. Ad esempio, se i fatti o le memorie generali escludono le preferenze o le linee guida, passare min_relevant_results_by_type per richiedere conteggi minimi per tipi di record specifici.

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)

La scheda visualizzata è un testo del prompt simile a XML. I record esatti dipendono dai dati memorizzati, ma la sezione <relevant_information> può includere i tipi richiesti prima dei risultati rimanenti della ricerca di tutti i tipi di memoria:

<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>

I minimi sono il miglior sforzo. Se non sono presenti record corrispondenti sufficienti per un tipo richiesto, la chiamata riesce comunque. Le corrispondenze da qualsiasi tipo di record di tipo memoria supportato possono utilizzare gli slot dei risultati che rimangono. Le registrazioni finali rilevanti sono sempre limitate da max_relevant_results.

Le chiavi supportate sono "memory", "fact", "guideline", "preference" e "message". I risultati della ricerca dei messaggi vengono cercati solo nel thread corrente; gli altri tipi di record mantengono l'ambito di ricerca utente/agente normale. Omettere min_relevant_results_by_type per mantenere il funzionamento di recupero predefinito.

Quando si crea una scheda di contesto, la memoria dell'agente Oracle cerca i record simili alla memoria separatamente dai messaggi nel thread corrente. Quando la ridefinizione o la potatura è configurata, viene applicata separatamente a ciascun set di risultati prima che i set vengano combinati. Se si specifica min_relevant_results_by_type, la ricerca di ogni tipo di record richiesto viene eseguita separatamente. Anche la riassegnazione o la potatura, se configurata, viene applicata separatamente ai risultati di ogni ricerca. Un'altra ricerca su tutti i tipi di record simili alla memoria può quindi utilizzare tutti gli slot dei risultati che rimangono.

In confronto, se la riassegnazione o l'eliminazione è configurata per una ricerca regolare che richiede più di record_types, viene applicata una volta ai risultati della ricerca combinata.

Quando max_relevant_results viene omesso, la memoria dell'agente Oracle utilizza il budget dei risultati rilevanti predefinito a meno che il totale minimo richiesto non sia maggiore. In tal caso, il bilancio effettivo si espande per adattarsi al totale minimo richiesto.

Concorrenza ricerca tipo di tuning

La creazione di una scheda di contesto può eseguire una ricerca per ogni tipo di record richiesto, oltre a una ricerca in tutti i tipi di record simili alla memoria per utilizzare gli slot dei risultati che rimangono. Per impostazione predefinita, è possibile eseguire contemporaneamente fino a cinque di queste ricerche. Per ridurre il numero di ricerche simultanee per un handle di thread attivo, passare context_card_type_search_concurrency durante la creazione o la riapertura del thread. Questo valore non viene reso persistente con la riga del thread:

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,
    },
)

Conclusione

In questa guida abbiamo imparato come richiedere il conteggio minimo dei risultati delle schede di contesto per tipi di record specifici simili alla memoria e come regolare il fanout della ricerca parallela utilizzato dal recupero per tipo.

→ Dopo aver appreso come personalizzare il recupero delle schede di contesto, ora è possibile passare a Usa API a breve termine della memoria di Oracle Agent con LangGraph.

Codice completo

#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,
    },
)