Personalizar contenido de tarjeta de contexto

Una tarjeta de contexto proporciona un contexto compacto sobre una conversación que un agente puede utilizar al generar una respuesta. Puede incluir un resumen del hilo de conversación, mensajes almacenados relevantes y recuerdos relevantes.

En esta guía se explica cómo personalizar el contenido devuelto en las tarjetas de contexto de Oracle AI Agent Memory.

Las tarjetas de contexto devueltas por get_context_card() también pueden incluir temas de recuperación y registros relevantes. Utilice tarjetas de contexto cuando un agente necesite continuidad en una conversación larga pero no necesite la transcripción completa devuelta al modelo. Esto puede reducir el uso de tokens de entrada, mantener el agente centrado y reducir la necesidad de algunas llamadas a herramientas a nivel de agente colocando la memoria relevante en el contexto de petición de datos por adelantado.

Para obtener un flujo de trabajo completo de compactación de peticiones de datos con LangGraph, consulte Uso de API de corto plazo de memoria de Oracle Agent con LangGraph. Para obtener más información sobre la API, consulte OracleThread y Tarjetas de contexto.

Nota: Utilice la personalización de tarjetas contextuales cuando los resultados de recuperación predeterminados no incluyan la combinación correcta de tipos de registro. Por ejemplo, una aplicación puede reservar espacio para las preferencias del usuario o las directrices de respuesta cuando los hechos generales dominarían los resultados.

Para configurar los límites de resultados, la nueva clasificación, la depuración o los presupuestos de token para las búsquedas y las tarjetas contextuales, consulte Mejora de la relevancia de los resultados de la búsqueda.

Solicitar resultados mínimos por tipo de registro

De forma predeterminada, la recuperación de tarjetas de contexto busca a la vez en todos los tipos de registro similares a la memoria. Por ejemplo, si los hechos o las memorias generales acumulan preferencias o directrices, pase min_relevant_results_by_type para solicitar recuentos mínimos para tipos de registro específicos.

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 tarjeta representada es un texto de petición de datos similar a XML. Los registros exactos dependen de los datos almacenados, pero la sección <relevant_information> puede incluir los tipos solicitados antes de los resultados restantes de la búsqueda de todos los tipos de 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>

Los mínimos son el mejor esfuerzo. Si no hay suficientes registros coincidentes para un tipo solicitado, la llamada se sigue realizando correctamente. Las coincidencias de cualquier tipo de registro similar a la memoria compatible pueden utilizar las ranuras de resultados que quedan. Los registros relevantes finales siempre están limitados por max_relevant_results.

Las claves admitidas son "memory", "fact", "guideline", "preference" y "message". Los resultados de los mensajes solo se buscan en el thread actual; los demás tipos de registro conservan el ámbito de búsqueda normal de usuario/agente. Omita min_relevant_results_by_type para mantener el comportamiento de recuperación por defecto.

Al crear una tarjeta de contexto, la memoria del agente de Oracle busca registros similares a la memoria independientemente de los mensajes del thread actual. Cuando se configura la modificación o depuración, se aplica por separado a cada conjunto de resultados antes de combinar los conjuntos. Cuando se proporciona min_relevant_results_by_type, cada tipo de registro solicitado se busca por separado. La modificación o depuración, cuando se configura, también se aplica por separado a los resultados de cada búsqueda. Otra búsqueda en todos los tipos de registro similares a la memoria puede utilizar cualquier espacio de resultados que quede.

En comparación, si la modificación o depuración está configurada para una búsqueda normal que solicita varios record_types, se aplica una vez a los resultados de búsqueda combinados.

Cuando se omite max_relevant_results, la memoria del agente de Oracle utiliza el presupuesto por defecto de resultados relevantes a menos que el total mínimo solicitado sea mayor. En ese caso, el presupuesto efectivo se amplía para ajustarse al total mínimo solicitado.

Simultaneidad de búsqueda de tipo de ajuste

La creación de una tarjeta de contexto puede ejecutar una búsqueda para cada tipo de registro solicitado, además de una búsqueda en todos los tipos de registro similares a la memoria para utilizar cualquier espacio de resultados que quede. De forma predeterminada, se pueden ejecutar hasta cinco de estas búsquedas al mismo tiempo. Para reducir el número de búsquedas simultáneas de un identificador de thread activo, transfiera context_card_type_search_concurrency al crear o volver a abrir el thread. Este valor no se mantiene con la fila 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,
    },
)

Conclusión

En esta guía, hemos aprendido a solicitar recuentos mínimos de resultados de tarjetas contextuales para tipos de registro específicos similares a la memoria y a ajustar el abanico de búsqueda paralela utilizado por la recuperación por tipo.

→ Después de haber aprendido a personalizar la recuperación de tarjetas de contexto, ahora puede usar API de corto plazo de memoria de Oracle Agent con LangGraph.

Código 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,
    },
)