컨텍스트 카드 콘텐츠 사용자정의

컨텍스트 카드는 에이전트가 응답을 생성할 때 사용할 수 있는 대화에 대한 간단한 컨텍스트를 제공합니다. 대화 스레드 요약, 최근 메시지 및 관련 메모리를 포함할 수 있습니다.

이 문서에서는 Oracle AI Agent Memory 컨텍스트 카드에 반환된 콘텐츠를 사용자정의하는 방법에 대해 설명합니다.

get_context_card()에서 반환되는 컨텍스트 카드에는 검색 항목 및 관련 영구 레코드가 포함될 수도 있습니다. 상담원이 긴 대화에서 연속성이 필요하지만 모델로 다시 전송된 전체 성적 증명서가 필요하지 않은 경우 컨텍스트 카드를 사용합니다. 이렇게 하면 입력 토큰 사용량을 줄이고 에이전트에 초점을 맞추고 프롬프트 컨텍스트의 관련 메모리를 맨 앞에 배치하여 일부 에이전트 레벨 도구 호출의 필요성을 줄일 수 있습니다.

LangGraph를 사용한 전체 프롬프트 압축 워크플로우는 Use Agent Memory Short-Term APIs with LangGraph를 참조하십시오. API 세부정보는 OracleThread 및 컨텍스트 카드를 참조하십시오.

참고: 기본 검색 결과에 레코드 유형의 올바른 조합이 포함되지 않은 경우 컨텍스트 카드 사용자정의를 사용합니다. 예를 들어, 일반 팩트가 결과를 지배하는 경우 응용 프로그램은 사용자 기본 설정 또는 응답 지침에 대한 공간을 예약할 수 있습니다.

레코드 유형별 요청 최소 결과

기본적으로 컨텍스트 카드 검색은 모든 메모리 유사 레코드 유형을 한 번에 검색합니다. 예를 들어 팩트 또는 일반 메모리가 기본 설정이나 지침을 혼잡하게 만드는 경우 min_relevant_results_by_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)

렌더링된 카드는 XML과 유사한 프롬프트 텍스트입니다. 정확한 레코드는 저장된 데이터에 따라 다르지만 <relevant_information> 섹션에는 all-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>

최소값은 최선의 노력이다. 요청된 유형에 대해 일치하는 레코드가 충분하지 않으면 호출이 계속 성공하고 나머지 결과 용량은 일반 all-memory-types 검색으로 채워질 수 있습니다. 최종 관련 레코드는 항상 max_relevant_results로 제한됩니다.

지원되는 키는 "memory", "fact", "guideline" 및 "preference"입니다. 기본 all-memory-types 검색 동작을 유지하려면 min_relevant_results_by_type을 생략합니다.

max_relevant_results를 생략하면 요청된 최소 합계가 더 큰 경우가 아니면 Oracle Agent Memory가 기본 관련 결과 예산을 사용합니다. 이 경우 유효 예산이 요청된 최소 합계에 맞게 확장됩니다.

유형 검색 동시실행 조정

유형별 검색은 하나의 모든 메모리 유형 채우기 검색과 요청된 각 레코드 유형에 대해 하나의 검색을 실행할 수 있습니다. 기본적으로 이러한 검색 중 최대 5개가 동시에 실행될 수 있습니다. 라이브 스레드 핸들의 백엔드 팬아웃을 줄이려면 스레드를 만들거나 다시 열 때 context_card_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,
    },
)

결론

이 설명서에서는 특정 메모리와 유사한 레코드 유형에 대해 최소 컨텍스트 카드 결과 수를 요청하는 방법과 유형별 검색에 사용되는 병렬 검색 팬아웃을 조정하는 방법을 배웠습니다.

컨텍스트 카드 검색을 사용자정의하는 방법을 배웠으므로 이제 Use Agent Memory Short-Term APIs with LangGraph를 진행할 수 있습니다.

전체 코드

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