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 recentes e memórias relevantes.

Este artigo explica como personalizar o conteúdo retornado nos cartões de contexto de Memória do Agente do Oracle AI.

Os cartões de contexto retornados pelo get_context_card() também podem incluir tópicos de recuperação e registros duráveis 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 imediata completo com o LangGraph, consulte Usar APIs de Curto Prazo de Memória do Agente 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.

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

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 e a capacidade de resultado restante poderá ser preenchida pela pesquisa normal de todos os tipos de memória. Os registros relevantes finais são sempre limitados por max_relevant_results.

As chaves suportadas são "memory", "fact", "guideline" e "preference". Omita min_relevant_results_by_type para manter o comportamento de recuperação padrão de todos os tipos de memória.

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 recuperação por tipo pode executar uma pesquisa de preenchimento de todos os tipos de memória mais uma pesquisa para cada tipo de registro solicitado. Por padrão, até cinco dessas pesquisas podem ser executadas ao mesmo tempo. Para reduzir o fanout de backend para um handle de thread ativo, informe 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,
    },
)

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.

Depois de aprender 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 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
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,
    },
)