스레드

이 페이지에서는 개발자용 메시지 도우미 유형과 함께 구체적인 Oracle 스레드 핸들을 제공합니다.

Oracle 스레드

클래스 oracleagentmemory.core.OracleThread

기준: IThread

Oracle 저장소가 지원하는 스레드입니다.

이 구현은 스레드 메시지와 수동으로 추가된 메모를 모두 포함 및 저장한 다음 저장된 모든 레코드에 대한 유사성 검색을 지원합니다.

주

• 메시지는 개별 레코드(메시지당 하나의 레코드)로 저장됩니다.
• 검색을 현재 스레드로 제한하거나 스레드(클라이언트 제어)에서 결과를 반환하도록 허용할 수 있습니다.

새 스레드 핸들을 생성합니다.

• 매개변수:
  • store OracleMemoryStore – 내장 레코드를 유지하는 데 사용되는 공유 저장소 백엔드입니다.
  • thread_id str – 스레드 식별자입니다. UUID를 제공하지 않으면 UUID가 생성됩니다.
  • user_id str – 스레드와 연관된 사용자 식별자입니다. 생략할 경우 UUID가 생성됩니다.
  • agent_id str – 스레드와 연관된 에이전트 식별자입니다. 생략할 경우 UUID가 생성됩니다.
  • metadata dict[str, Any] | None – 스레드와 연관된 선택적 JSON 유사 메타데이터입니다.
  • persist_messages_in_config bool – _to_config에 최근 원시 메시지 스냅샷이 포함되어야 하는지 여부입니다. 스레드 구성을 통해 메시지 테이블 콘텐츠를 익스포트하지 않도록 DB 저장소를 사용하는 스레드에 대해 자동으로 False로 설정됩니다.
  • LLM ILlm | None – 메모리 추출 및 컨텍스트 요약 업데이트에 사용되는 선택적 LLM 어댑터입니다. 제공된 경우 add_messages는 추가된 각 메시지에서 관련 메모리를 추출하여 입력된 메모리 레코드("memory", "guideline", "fact" 또는 "preference")로 저장합니다.
  • memory_extraction_window int – 추출 중 LLM에 컨텍스트로 제공할 가장 최근 메시지(새로 추가된 메시지 포함) 수입니다. 새로 추가된 메시지의 전체 뱃치를 사용하여 add_messages 호출당 한 번만 추출하려면 -1로 설정합니다. 기본값은 -1입니다.
  • context_summary_update_frequency int – 추출 컨텍스트 요약을 업데이트해야 하는 메시지 수입니다. 새로 추가된 메시지의 전체 뱃치를 사용하여 add_messages 호출당 한 번만 요약하려면 -1로 설정합니다. 기본값은 -1입니다.
  • memory_extraction_frequency int – 메모리 추출이 트리거된 후의 메시지 수입니다. 새로 추가된 메시지의 전체 뱃치를 사용하여 add_messages 호출당 한 번만 추출하려면 -1로 설정합니다.
  • memory_extraction_token_limit int – 메모리 추출 및 요약 업데이트 실행에 사용되는 LLM 프롬프트의 최대 크기(토큰)입니다. 더 긴 프롬프트가 잘립니다. 음수 또는 0인 경우 프롬프트 자르기가 사용 안함으로 설정됩니다.
  • context_card_token_limit int – 컨텍스트 카드 요약에 사용되는 LLM 프롬프트의 최대 크기(토큰)입니다. 기본값은 100_000 토큰입니다. 더 긴 프롬프트가 잘립니다. 음수 또는 0인 경우 프롬프트 자르기가 사용 안함으로 설정됩니다.
  • max_message_token_length int – LLM 지원 메모리 추출 및 컨텍스트 요약 업데이트 중 사용된 각 메시지의 프롬프트 시간 복사본에 대한 최대 크기(토큰)입니다. 저장된 메시지 내용은 변경되지 않습니다. 음수 또는 0인 경우 프롬프트 시간 단축이 수행되지 않습니다. LLM을 제공할 경우 크기가 너무 큰 프롬프트 복사본이 잘리지 않고 요약됩니다.
  • message_shortening_input_token_limit int – 대형 프롬프트 복사본을 줄일 때 LLM으로 전송된 메시지 발췌 내용의 최대 크기(토큰)입니다. 기본값은 30_000 토큰입니다. 음수 또는 0인 경우 LLM 기반 단축 중 아웃바운드 바인드가 적용되지 않습니다.
  • enable_context_summary bool – 스레드의 압축 실행 요약을 유지할지 여부입니다. 사용으로 설정되고 llm가 제공되면 context_summary_update_frequency에 따라 요약이 업데이트됩니다. 현재 요약은 메모리를 추출할 때 컨텍스트로 제공됩니다.
  • 클라이언트 Any | None

예제

from oracleagentmemory.core import OracleAgentMemory
db_pool = ...
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    enable_context_summary=True,
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

방법 add_memory

수동 메모리 항목을 추가하고 인덱스화합니다.

• 매개변수:
  • content str – 메모리로 저장할 텍스트 콘텐츠입니다.
  • user_id str – 선택적 사용자 식별자 대체입니다.
  • agent_id str – 선택적 에이전트 식별자 대체입니다.
  • thread_id str – 선택적 스레드 식별자 대체입니다.
  • memory_id str – 이 메모리 행에 대해 선택적인 호출자가 제공하는 안정적인 식별자입니다.
  • **store_kwargs(임의) – 보조 기억 장치로 전달된 저장소별 쓰기 옵션입니다.
• 반환: 삽입된 메모리 레코드의 식별자입니다.
• 반환 유형: str

예제

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

방법 add_messages

스레드에 메시지를 추가하고 색인화합니다.

• 매개변수:
  • messages list[Message | MessageT] – 추가할 메시지 목록입니다. 메시지는 Message 객체 또는 role 및 content(및 선택적 id)가 포함된 사전일 수 있습니다.
  • **store_kwargs(임의) – 보조 기억 장치로 전달된 저장소별 쓰기 옵션입니다.
• 반환: 삽입된 메시지 레코드의 식별자입니다.
• 반환 유형: list[str]

예제

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

method add_messages_async(비동기)

메시지를 스레드에 비동기적으로 추가하고 인덱스화합니다.

• 매개변수:
  • 메시지 list[Message | MessageT]
  • store_kwargs Any
• 반환 유형: list[str]

방법 delete_memory

식별자별로 이 정확한 스레드에서 메모리 유사 레코드(예: 메모리, 팩트, 기본 설정 또는 지침)를 삭제합니다.

• 매개변수: memory_id str – 메모리 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메모리 유사 레코드(memory, guideline, fact, preference)만 삭제됩니다.
• 반환: 삭제된 레코드 수(0 또는 1). 식별자가 존재하지 않거나 다른 스레드에 속하는 경우 0를 반환합니다.
• 반품 유형: int

예제

thread.delete_memory("456")
0

방법 delete_message

식별자별로 정확한 이 스레드에서 메시지 레코드를 삭제합니다.

• 매개변수: message_id str – 메시지 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메시지만 삭제됩니다.
• 반환: 삭제된 메시지 레코드 수(0 또는 1)입니다. 식별자가 존재하지 않거나 다른 스레드에 속하는 경우 0를 반환합니다.
• 반품 유형: int

주

메시지를 삭제하면 원시 메시지 레코드만 제거됩니다. 추출된 메모리는 메시지별 출처를 지속하지 않으므로 파생 메모리는 삭제되지 않으므로 검색 가능한 상태로 유지되거나 컨텍스트 카드 출력에 여전히 영향을 줄 수 있습니다. OracleAgentMemory.delete_thread()를 사용하여 연관된 메시지 및 메모리와 함께 스레드를 삭제합니다.

예제

thread.delete_message("123")
0

방법 get_context_card

스레드에 대한 컨텍스트 카드 객체를 반환합니다.

LLM 지원 구현에서 원격 네트워크 I/O를 수행할 수 있는 경우 get_context_card_async을 선호합니다.

• 매개변수:
  • fallback_message_count int – 검색 및 렌더링을 위해 폴백 요약 텍스트를 파생할 때 사용할 최근 메시지 수입니다.
  • max_relevant_results int – 포함할 검색된 영구 레코드의 최대 수입니다.
  • max_recent_messages int – 동사를 포함할 최대 후행 원시 메시지 수입니다.
  • **kwargs(Any) – 이후 컨텍스트 카드 옵션용으로 예약되어 있습니다. 예상치 않은 키워드 인수가 TypeError를 발생시킵니다.
• 반환: 가장 최근 메시지를 기반으로 하는 스레드 컨텍스트 요약을 포함하는 컨텍스트 카드 객체입니다. OracleContextCard.content를 사용하여 렌더링된 XML 유사 텍스트에 액세스합니다.
• 반환 유형: OracleContextCard

주

그러면 스레드의 기본 검색 범위가 exact_thread_match=False와 함께 사용되므로 동일한 사용자/에이전트에 대한 다른 스레드의 관련 메모리가 포함될 수 있습니다.

예제

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card().content
True

method get_context_card_async(비동기)

스레드에 대한 컨텍스트 카드 객체를 비동기적으로 반환합니다.

• 매개변수:
  • fallback_message_count int – 검색 및 렌더링을 위해 폴백 요약 텍스트를 파생할 때 사용할 최근 메시지 수입니다.
  • max_relevant_results int – 포함할 검색된 영구 레코드의 최대 수입니다.
  • max_recent_messages int – 동사를 포함할 최대 후행 원시 메시지 수입니다.
  • **kwargs(Any) – 이후 컨텍스트 카드 옵션용으로 예약되어 있습니다. 예상치 않은 키워드 인수가 TypeError를 발생시킵니다.
• 반환: 스레드에 대한 컨텍스트 카드 객체입니다.
• 반환 유형: OracleContextCard

방법 get_messages

현재 글 모음에 저장된 메시지를 반환합니다.

• 매개변수:
  • start int | None – 시작 인덱스(0 기반)입니다. end와 함께 생략하면 가장 최근의 바인드된 창이 반환됩니다.
  • end int | None – 종료 인덱스(배타적)입니다. 생략하면 가장 최근 메시지의 제한된 창이 반환됩니다. None 또는 -1를 전달하여 start 이후부터 모든 메시지를 명시적으로 요청합니다.
• 반환: 시간순으로 메시지를 표시합니다.
• 반환 유형: list[메시지]

예제

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

방법 get_summary

스레드의 최선의 요약을 반환합니다.

LLM 지원 구현에서 원격 네트워크 I/O를 수행할 수 있는 경우 get_summary_async을 선호합니다.

• 매개변수:
  • except_last int – 요약에서 제외할 가장 최근 메시지 수입니다.
  • token_budget int – 소프트 토큰 예산입니다. 생략할 경우 제한된 기본값이 적용됩니다. 형식 지정된 요약이 _estimate_tokens()로 추정되는 예산을 초과하는 경우에만 양수 값이 잘립니다. 그러면 반환된 텍스트가 int(token_budget * 3.5)자로 제한됩니다. 양수가 아닌 값은 출력 한도를 사용 안함으로 설정합니다.
  • **kwargs(Any) – 이후 요약 옵션을 위해 예약됩니다. 예상치 않은 키워드 인수가 TypeError를 발생시킵니다.
• 반환: 합성된 스레드 요약 텍스트를 포함하는 요약 객체입니다.
• 반품 유형: OracleSummary

예제

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
bool(summary.content)
True

method get_summary_async(비동기)

스레드의 최선 조건 요약을 비동기적으로 반환합니다.

• 매개변수:
  • except_last int – 요약에서 제외할 가장 최근 메시지 수입니다.
  • token_budget int – 소프트 토큰 예산입니다. 생략할 경우 제한된 기본값이 적용됩니다. 형식 지정된 요약이 _estimate_tokens()로 추정되는 예산을 초과하는 경우에만 양수 값이 잘립니다. 그러면 반환된 텍스트가 int(token_budget * 3.5)자로 제한됩니다. 양수가 아닌 값은 출력 한도를 사용 안함으로 설정합니다.
  • **kwargs(Any) – 이후 요약 옵션을 위해 예약됩니다. 예상치 않은 키워드 인수가 TypeError를 발생시킵니다.
• 반환: 합성된 스레드 요약 텍스트를 포함하는 요약 객체입니다.
• 반품 유형: OracleSummary

주: delete_message()는 원시 메시지 행만 삭제합니다. 파생 된 기억은 여전히 검색 가능하거나 컨텍스트 카드에 나타날 수 있습니다. OracleAgentMemory.delete_thread()를 사용하여 연관된 메시지 및 메모리와 함께 스레드를 삭제합니다.

메시지

클래스 oracleagentmemory.apis.thread.Message

기준: object

• 매개변수:
  • 역할 str
  • 콘텐츠 str
  • 시간 기록 str | None
  • 메타데이터 dict[str, Any] | None
  • id str | None

컨텍스트 카드

클래스 oracleagentmemory.apis.contextcard.ContextCard

기준: ABC

스레드 API에서 반환된 추상 컨텍스트 카드 객체입니다.

등록 정보 content(개요)

• 반품 유형: str
• 설명: 렌더링된 컨텍스트 카드 텍스트를 반환합니다.

클래스 oracleagentmemory.core.contextcard.OracleContextCard

기준: ContextCard

Oracle 스레드에서 반환된 컨텍스트 카드입니다.

• 매개변수:
  • 요약 str – 카드에 포함된 요약 텍스트입니다.
  • 항목 Sequence[str] | None – 스레드와 연관된 선택적 검색 항목입니다.
  • relevant_results Sequence[SearchResult] | None – 카드에 포함된 선택적 검색된 영구 레코드입니다.
  • recent_messages Sequence[Message] | None – 카드로 렌더링된 선택적 최근 원시 메시지입니다.
  • message_format str – recent_messages를 렌더링할 때 사용되는 내부 템플리트입니다.

등록 정보 content

• 반품 유형: str

• 설명: 렌더링된 컨텍스트 카드 텍스트를 반환합니다.

• 반환: 프롬프트 어셈블리에 적합한 XML과 유사한 렌더링된 컨텍스트 카드 텍스트입니다.
• 반환 유형: str

예제

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

등록 정보 formatted_content

• 반품 유형: str

• 설명: 프롬프트 작성 플로우에 사용되는 렌더링된 컨텍스트 카드 텍스트를 반환합니다.

• 반환: XML과 유사한 렌더링된 컨텍스트 카드 텍스트입니다.
• 반환 유형: str

예제

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

요약

클래스 oracleagentmemory.apis.summary.Summary

기준: ABC

스레드 API에서 반환된 추상 스레드 요약 객체입니다.

등록 정보 content(개요)

• 반품 유형: str
• 설명: 합성된 요약 텍스트를 반환합니다.

클래스 oracleagentmemory.core.summary.OracleSummary

기준: Summary

Oracle 스레드에서 반환된 요약입니다.

• 매개변수: content str – 스레드 기록에서 합성된 요약 텍스트입니다.

예제

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

등록 정보 content

• 반품 유형: str

• 설명: 합성된 요약 텍스트를 반환합니다.

• 반환: 스레드에 대한 요약 텍스트입니다.
• 반환 유형: str

예제

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

등록 정보 formatted_content

• 반품 유형: str

• 설명: 프롬프트 작성 플로우에 사용되는 렌더링된 요약 텍스트를 반환합니다.

• 반환: 렌더링된 요약 텍스트입니다.
• 반환 유형: str

예제

OracleSummary(content="Thread recap").formatted_content
'Thread recap'