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 recientes y recuerdos relevantes.

En este artículo se explica cómo personalizar el contenido devuelto en las tarjetas de contexto de memoria del agente de Oracle AI.

Las tarjetas de contexto devueltas por get_context_card() también pueden incluir temas de recuperación y registros duraderos 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 agente 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.

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
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="YOUR DB CONNECT STRING",
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)

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

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 y la capacidad de resultados restante se puede completar mediante la búsqueda normal de todos los tipos de memoria. Los registros relevantes finales siempre están limitados por max_relevant_results.

Las claves admitidas son "memory", "fact", "guideline" y "preference". Omita min_relevant_results_by_type para mantener el comportamiento de recuperación por defecto de todos los tipos de memoria.

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 recuperación por tipo puede ejecutar una búsqueda de relleno de todos los tipos de memoria más una búsqueda para cada tipo de registro solicitado. De forma predeterminada, se pueden ejecutar hasta cinco de estas búsquedas al mismo tiempo. Para reducir el desvío de backend 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,
    },
)

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 continuar con Uso de API de corto plazo de memoria de agente 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
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="YOUR DB CONNECT STRING",
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)

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

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