Personalizar conteúdo de cartão de contexto

Um cartão de contexto fornece um contexto compacto sobre uma conversa que um agente pode usar ao gerar uma resposta. Ele pode incluir um resumo de thread de conversa, mensagens armazenadas relevantes e memórias relevantes.

Este guia explica como personalizar o conteúdo retornado nos cartões de contexto do Oracle AI Agent Memory.

Os cartões de contexto retornados pelo get_context_card() também podem incluir tópicos de recuperação e registros relevantes. Use cartões de contexto quando um agente precisar de continuidade em uma conversa longa, mas não precisar da transcrição completa enviada de volta ao modelo. Isso pode reduzir o uso do token de entrada, manter o agente focado e reduzir a necessidade de algumas chamadas de ferramenta no nível do agente, colocando a memória relevante no contexto do prompt antecipadamente.

Para obter um workflow de compactação de prompt completo com o LangGraph, consulte Usar APIs de Curto Prazo de Memória do Agente Oracle com o LangGraph. Para obter detalhes da API, consulte OracleThread e Cartões de Contexto.

Observação: use a personalização de cartão de contexto quando os resultados de recuperação padrão não incluírem a combinação certa de tipos de registro. Por exemplo, um aplicativo pode reservar espaço para preferências do usuário ou diretrizes de resposta quando fatos gerais de outra forma dominariam os resultados.

Para configurar limites de resultados, reclassificação, remoção ou orçamentos de token para pesquisas e cartões de contexto, consulte Melhorar a Relevância do Resultado da Pesquisa.

Solicitar Resultados Mínimos por Tipo de Registro

Por padrão, a recuperação de cartão de contexto pesquisa todos os tipos de registro semelhantes à memória de uma só vez. Por exemplo, se fatos ou memórias gerais excluírem preferências ou diretrizes, passe min_relevant_results_by_type para solicitar contagens mínimas 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)

O cartão renderizado é um texto de prompt semelhante a XML. Os registros exatos dependem dos seus dados armazenados, mas a seção <relevant_information> pode incluir os tipos solicitados antes dos resultados restantes da pesquisa de todos os tipos de memória:

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

Os mínimos são o melhor esforço. Se não houver registros correspondentes suficientes para um tipo solicitado, a chamada ainda será bem-sucedida. As correspondências de qualquer tipo de registro compatível com memória podem usar os slots de resultado que permanecem. Os registros relevantes finais são sempre limitados por max_relevant_results.

As chaves suportadas são "memory", "fact", "guideline", "preference" e "message". Os resultados da mensagem são pesquisados somente no thread atual; os outros tipos de registro mantêm o escopo de pesquisa normal de usuário/agente. Omita min_relevant_results_by_type para manter o comportamento de recuperação padrão.

Ao criar um cartão de contexto, o Oracle Agent Memory pesquisa registros semelhantes à memória separadamente das mensagens no thread atual. Quando a nova classificação ou a poda é configurada, ela é aplicada separadamente a cada conjunto de resultados antes que os conjuntos sejam combinados. Quando o min_relevant_results_by_type é fornecido, cada tipo de registro solicitado é pesquisado separadamente. Reranking ou poda, quando configurado, também é aplicado separadamente aos resultados de cada pesquisa. Outra pesquisa em todos os tipos de registro semelhantes à memória pode usar qualquer slot de resultado restante.

Por comparação, se a reclassificação ou a remoção estiver configurada para uma pesquisa regular que solicite vários record_types, ela será aplicada uma vez aos resultados da pesquisa combinada.

Quando max_relevant_results é omitido, a Memória do Agente Oracle usa o orçamento padrão de resultados relevantes, a menos que o total mínimo solicitado seja maior. Nesse caso, o orçamento efetivo se expande para se adequar ao total mínimo solicitado.

Ajustar simultaneidade de pesquisa de tipo

A criação de uma placa de contexto pode executar uma pesquisa para cada tipo de registro solicitado, além de uma pesquisa em todos os tipos de registro semelhantes à memória para usar qualquer slot de resultado restante. Por padrão, até cinco dessas pesquisas podem ser executadas ao mesmo tempo. Para reduzir o número de pesquisas simultâneas para um handle de thread ativo, passe context_card_type_search_concurrency ao criar ou reabrir o thread. Este valor não é persistido com a linha 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,
    },
)

Conclusão

Neste guia, aprendemos a solicitar contagens mínimas de resultados de cartão de contexto para tipos de registro específicos semelhantes à memória e como ajustar o fanout de pesquisa paralela usado pela recuperação por tipo.

→ Tendo aprendido a personalizar a recuperação de cartão de contexto, agora você pode prosseguir para Usar APIs de Curto Prazo de Memória do Agente Oracle com LangGraph.

Código Inteiro

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