Personnaliser le contenu de la carte contextuelle
Une carte de contexte fournit un contexte compact sur une conversation qu'un agent peut utiliser lors de la génération d'une réponse. Il peut inclure un résumé du fil de conversation, des messages stockés pertinents et des mémoires pertinentes.
Ce guide explique comment personnaliser le contenu renvoyé dans les cartes de contexte Oracle AI Agent Memory.
Les cartes de contexte renvoyées par get_context_card() peuvent également inclure des rubriques d'extraction et des enregistrements pertinents. Utilisez des cartes contextuelles lorsqu'un agent a besoin d'une continuité dans une longue conversation, mais n'a pas besoin que la transcription complète soit renvoyée au modèle. Cela peut réduire l'utilisation des jetons d'entrée, maintenir l'agent concentré et réduire le besoin d'appels d'outil au niveau de l'agent en plaçant la mémoire pertinente dans le contexte d'invite à l'avance.
Pour un workflow complet de compression d'invite avec LangGraph, reportez-vous à Utilisation des API à court terme de mémoire d'agent Oracle avec LangGraph. Pour plus de détails sur l'API, reportez-vous à OracleThread et à Cartes de contexte.
Remarque : Utilisez la personnalisation de la carte de contexte lorsque les résultats d'extraction par défaut n'incluent pas la bonne combinaison de types d'enregistrement. Par exemple, une application peut réserver de l'espace pour les préférences utilisateur ou les directives de réponse lorsque les faits généraux dominent les résultats.
Pour configurer les limites de résultats, le reclassement, l'élagage ou les budgets par jeton pour les recherches et les cartes de contexte, voir Améliorer la pertinence des résultats de recherche.
Résultats minimum de demande par type d'enregistrement
Par défaut, l'extraction de la carte de contexte recherche simultanément tous les types d'enregistrement de type mémoire. Par exemple, si des faits ou des mémoires générales excluent des préférences ou des directives, transmettez min_relevant_results_by_type pour demander des nombres minimaux pour des types d'enregistrement spécifiques.
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 carte affichée est un texte d'invite de type XML. Les enregistrements exacts dépendent de vos données stockées, mais la section <relevant_information> peut inclure les types demandés avant les résultats restants de la recherche tout-memory-types :
<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>Les minimums sont les meilleurs efforts. S'il n'y a pas assez d'enregistrements correspondants pour un type demandé, l'appel réussit toujours. Les correspondances à partir de tout type d'enregistrement de type mémoire pris en charge peuvent utiliser les emplacements de résultats restants. Les derniers enregistrements pertinents sont toujours plafonnés par max_relevant_results.
Les clés prises en charge sont "memory", "fact", "guideline", "preference" et "message". Les résultats des messages sont recherchés uniquement dans le thread en cours ; les autres types d'enregistrement conservent la portée de recherche utilisateur/agent normale. Omettez min_relevant_results_by_type pour conserver le comportement d'extraction par défaut.
Lors de la création d'une carte de contexte, la mémoire de l'agent Oracle recherche les enregistrements de type mémoire séparément des messages du thread en cours. Lorsque le reclassement ou l'élagage est configuré, il est appliqué séparément à chaque ensemble de résultats avant que les ensembles ne soient combinés. Lorsque min_relevant_results_by_type est fourni, chaque type d'enregistrement demandé fait l'objet d'une recherche distincte. Le reclassement ou l'élagage, lorsqu'il est configuré, est également appliqué séparément aux résultats de chaque recherche. Une autre recherche sur tous les types d'enregistrements de type mémoire peut ensuite utiliser tous les emplacements de résultats restants.
Par comparaison, si le reclassement ou l'élagage est configuré pour une recherche standard qui demande plusieurs éléments record_types, il est appliqué une seule fois aux résultats de la recherche combinée.
Lorsque max_relevant_results est omis, la mémoire de l'agent Oracle utilise le budget pertinent-results par défaut, sauf si le total minimum demandé est supérieur. Dans ce cas, le budget effectif est élargi pour correspondre au total minimum demandé.
Concomitance de recherche de type de réglage
La création d'une carte de contexte peut exécuter une recherche pour chaque type d'enregistrement demandé, plus une recherche sur tous les types d'enregistrement de type mémoire pour utiliser les emplacements de résultats restants. Par défaut, jusqu'à cinq de ces recherches peuvent être exécutées en même temps. Pour réduire le nombre de recherches simultanées pour un descripteur de thread actif, transmettez context_card_type_search_concurrency lors de la création ou de la réouverture du thread. Cette valeur n'est pas conservée avec la ligne de 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,
},
)Conclusion
Dans ce guide, nous avons appris à demander un nombre minimal de résultats de carte de contexte pour des types d'enregistrement spécifiques de type mémoire et à régler le ventilateur de recherche parallèle utilisé par l'extraction par type.
→ Après avoir appris à personnaliser l'extraction des cartes contextuelles, vous pouvez maintenant passer à Utiliser les API à court terme de mémoire d'agent Oracle avec LangGraph.
Code complet
#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,
},
)