스레드

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

Oracle 스레드

클래스 oracleagentmemory.core.OracleThread

기준: IThread

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

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

노트

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

새 OracleThread 인스턴스를 생성하십시오.

• 매개변수:
  • store OracleMemoryStore – 내장 레코드를 유지하는 데 사용되는 공유 저장소 백엔드입니다.
  • thread_id str – 스레드 식별자입니다. UUID를 제공하지 않으면 UUID가 생성됩니다.
  • user_id str – 스레드와 연관된 사용자 식별자입니다. DB SchemaPolicy.NO_CHECK 런타임 저장소에서 생략할 경우 활성 일반 사용자 보안 컨텍스트의 사용자 이름이 사용됩니다. 그렇지 않은 경우 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_config MemoryExtractionConfig – 선택적 스레드 레벨 메모리 추출 구성입니다. 추출 모드, 요약 동작, 추출 제한 및 자동 추출의 활성화 여부와 같은 자동 추출 설정을 제어하는 데 사용합니다. 이 그룹화된 구성 또는 사용되지 않는 인라인 추출 매개변수 중 하나만 전달하십시오. 생략할 경우 독립형 OracleThread()는 추출 필드에 SDK 기본값을 사용하고 컨텍스트 요약을 사용으로 유지합니다. 생략된 이미지 컨텍스트는 DISABLED입니다.
  • image_input_limit_config ImageInputLimitConfig – 이 독립형 스레드에 대한 선택적 원시 이미지 및 LLM 이미지 요청 제한입니다. 생략된 필드는 SDK 기본값을 사용합니다. 검증을 사용 안함으로 설정할 수 없습니다.

  • memory_extraction_window int –

    추출 중 LLM에 컨텍스트로 제공할 가장 최근 메시지(새로 추가된 메시지 포함) 수입니다. 새로 추가된 메시지의 전체 뱃치를 사용하여 add_messages 호출당 한 번만 추출하려면 -1로 설정합니다. 기본값은 -1입니다.

    지원 중단됨

    버전 26.6.0 이후 더 이상 사용되지 않음: 이 매개변수는 26.6.0에서 더 이상 사용되지 않으며 27.1에서 제거됩니다. 대신 memory_extraction_config를 사용하십시오.

  • context_summary_update_frequency int –

    최근 적합한 요약 후 자동으로 새로고침되기 전의 메시지 수입니다. 메모리 추출이 활성화된 경우 검사는 만기될 때마다 수행되므로 나중에 Refresh가 발생할 수 있습니다. 모든 검사 시 0보다 작거나 같은 값이 새로 고쳐집니다. 기본값은 -1입니다.

    지원 중단됨

    버전 26.6.0 이후 더 이상 사용되지 않음: 이 매개변수는 26.6.0에서 더 이상 사용되지 않으며 27.1에서 제거됩니다. 대신 memory_extraction_config를 사용하십시오.

  • memory_extraction_frequency int –

    메모리 추출이 트리거되기 전의 메시지 수입니다. 새로 추가된 메시지의 전체 뱃치를 사용하여 add_messages 호출당 한 번만 추출하려면 -1로 설정합니다.

    지원 중단됨

    버전 26.6.0 이후 더 이상 사용되지 않음: 이 매개변수는 26.6.0에서 더 이상 사용되지 않으며 27.1에서 제거됩니다. 대신 memory_extraction_config를 사용하십시오.

  • memory_extraction_token_limit int –

    메모리 추출 및 요약 업데이트 실행에 사용되는 LLM 프롬프트의 최대 크기(토큰)입니다. 더 긴 프롬프트가 잘립니다. 음수 또는 0인 경우 프롬프트 자르기가 사용 안함으로 설정됩니다.

    지원 중단됨

    버전 26.6.0 이후 더 이상 사용되지 않음: 이 매개변수는 26.6.0에서 더 이상 사용되지 않으며 27.1에서 제거됩니다. 대신 memory_extraction_config를 사용하십시오.

  • context_card_token_limit int – 컨텍스트 카드에 포함된 요약 및 항목 목록을 작성하는 데 사용되는 LLM 프롬프트에 대한 최대 입력 토큰 예산입니다. 기본값은 100_000이며 0보다 작거나 같은 값은 프롬프트 잘림을 사용 안함으로 설정합니다.
  • context_card_type_search_concurrency int – min_relevant_results_by_type로 컨텍스트 카드를 작성할 때 동시에 실행할 최대 메모리 유사 레코드 검색 수입니다. 기본값은 5입니다.
  • max_message_token_length int – LLM 지원 메모리 추출 및 컨텍스트 요약 업데이트 중 사용된 각 메시지의 프롬프트 시간 복사본에 대한 최대 크기(토큰)입니다. 저장된 메시지 내용은 변경되지 않습니다. 음수 또는 0인 경우 프롬프트 시간 단축이 수행되지 않습니다. LLM이 제공되는 경우 크기가 너무 큰 프롬프트 복사본이 잘리지 않고 요약됩니다.
  • message_shortening_input_token_limit int – 대형 프롬프트 복사본을 줄일 때 LLM으로 전송된 메시지 발췌 내용의 최대 크기(토큰)입니다. 기본값은 30_000 토큰입니다. 음수 또는 0인 경우 LLM 기반 단축 중에 아웃바운드 바인드가 적용되지 않습니다.

  • enable_context_summary bool –

    스레드의 간단한 요약을 유지할지 여부입니다. 사용으로 설정되고 llm가 제공된 경우 OAM은 context_summary_update_frequency에 따라 새로 고치고 대상 메시지 이전의 요약을 추출 컨텍스트로 사용합니다. 독립형 OracleThread()의 경우 기본값은 True입니다.

    지원 중단됨

    버전 26.6.0 이후 더 이상 사용되지 않음: 이 매개변수는 26.6.0에서 더 이상 사용되지 않으며 27.1에서 제거됩니다. 대신 memory_extraction_config를 사용하십시오.

  • memory_extraction_custom_instructions str | None –

    이 스레드에 대한 자동 메모리 추출 시스템 프롬프트에 추가된 선택적 사용자 정의 지침입니다.

    지원 중단됨

    버전 26.6.0 이후 더 이상 사용되지 않음: 이 매개변수는 26.6.0에서 더 이상 사용되지 않으며 27.1에서 제거됩니다. 대신 memory_extraction_config를 사용하십시오.

  • memory_extraction_inherit_message_metadata bool | Sequence[str] –

    자동으로 추출된 메모리가 소스 메시지에서 메타데이터를 상속할지 여부입니다. True를 전달하여 모든 메시지 메타데이터를 상속하거나, 최상위 레벨 메시지 메타데이터 키의 비문자열 시퀀스를 전달하여 해당 키만 상속하거나, False을 전달하여 상속을 사용 안함으로 설정합니다. 기본값은 True입니다. 한 추출 패스가 여러 소스 메시지를 사용하는 경우 선택한 메타데이터가 해당 메시지에서 일치해야 합니다.

    지원 중단됨

    버전 26.6.0 이후 더 이상 사용되지 않음: 이 매개변수는 26.6.0에서 더 이상 사용되지 않으며 27.1에서 제거됩니다. 대신 memory_extraction_config를 사용하십시오.

  • search_config MemorySearchConfig – 이 스레드에 대한 선택적 검색 구성입니다. 생략할 경우 검색은 고정된 top-k 검색 구성을 사용합니다.
  • 클라이언트 OracleAgentMemory | None

예제

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

방법 add_image

이 스레드와 연관된 하나의 이미지를 유지합니다.

description는 이미지의 검색 가능한 텍스트로 저장됩니다. 생략되거나 None인 경우 연결된 LLM이 캡션을 생성합니다. 생략된 범위 값은 이 스레드의 해당 사용자, 에이전트 및 스레드 식별자를 상속합니다.

• 매개변수:
  • image bytes – 지속할 원시 이미지 바이트입니다.
  • description str | None – 선택적 설명 또는 캡션입니다. 캡션을 생성하려면 생략합니다.
  • mime_type ImageMimeType – 이미지 지속성 및 캡션 생성에 사용되는 선택적 MIME 유형입니다. 생략할 경우 SDK는 이미지 바이트에서 유형을 감지하고 검증합니다. 지원되는 감지 유형은 PNG, JPEG 및 WEBP입니다.
  • image_id str – 선택적 식별자입니다. 하나는 생략될 때 생성됩니다.
  • user_id str | None – 선택적 범위 검증입니다. 생략된 값은 이 스레드의 범위를 상속합니다. 제공된 값은 정확히 일치해야 합니다.
  • agent_id str | None – 선택적 범위 검증입니다. 생략된 값은 이 스레드의 범위를 상속합니다. 제공된 값은 정확히 일치해야 합니다.
  • thread_id str – 선택적 범위 검증입니다. 생략된 값은 이 스레드의 범위를 상속합니다. 제공된 값은 정확히 일치해야 합니다.
  • metadata dict[str, Any] | None – 이미지와 함께 저장된 선택적 메타데이터입니다.
  • timestamp str | None – 이 이미지에 대해 저장할 선택적 이벤트 시간 기록입니다. 이 인수를 생략하거나 None를 전달하여 NULL 이벤트 시간 기록을 저장합니다. 이미지를 읽으면 생성 시간이 유효 시간 기록으로 반환됩니다.
  • ttl_days int | None – 선택적 만료 설정입니다.
  • ttl_anchor TimeToLiveAnchor – 선택적 만료 설정입니다.
  • store_kwargs Any – 추가 저장소별 옵션입니다.
• 반환: 지속 이미지 식별자입니다.
• 반환 유형: str

method add_image_async(비동기)

이 스레드와 연관된 하나의 이미지를 비동기적으로 유지합니다.

description는 이미지의 검색 가능한 텍스트로 저장됩니다. 생략되거나 None인 경우 연결된 LLM이 캡션을 생성합니다. 생략된 범위 값은 이 스레드의 해당 사용자, 에이전트 및 스레드 식별자를 상속합니다.

• 매개변수:
  • image bytes – 지속할 원시 이미지 바이트입니다.
  • description str | None – 선택적 설명 또는 캡션입니다. 캡션을 생성하려면 생략합니다.
  • mime_type ImageMimeType – 이미지 지속성 및 캡션 생성에 사용되는 선택적 MIME 유형입니다. 생략할 경우 SDK는 이미지 바이트에서 유형을 감지하고 검증합니다. 지원되는 감지 유형은 PNG, JPEG 및 WEBP입니다.
  • image_id str – 선택적 식별자입니다. 하나는 생략될 때 생성됩니다.
  • user_id str | None – 선택적 범위 검증입니다. 생략된 값은 이 스레드의 범위를 상속합니다. 제공된 값은 정확히 일치해야 합니다.
  • agent_id str | None – 선택적 범위 검증입니다. 생략된 값은 이 스레드의 범위를 상속합니다. 제공된 값은 정확히 일치해야 합니다.
  • thread_id str – 선택적 범위 검증입니다. 생략된 값은 이 스레드의 범위를 상속합니다. 제공된 값은 정확히 일치해야 합니다.
  • metadata dict[str, Any] | None – 이미지와 함께 저장된 선택적 메타데이터입니다.
  • timestamp str | None – 이 이미지에 대해 저장할 선택적 이벤트 시간 기록입니다. 이 인수를 생략하거나 None를 전달하여 NULL 이벤트 시간 기록을 저장합니다. 이미지를 읽으면 생성 시간이 유효 시간 기록으로 반환됩니다.
  • ttl_days int | None – 선택적 만료 설정입니다.
  • ttl_anchor TimeToLiveAnchor – 선택적 만료 설정입니다.
  • store_kwargs Any – 추가 저장소별 옵션입니다.
• 반환: 지속 이미지 식별자입니다.
• 반환 유형: str

방법 add_memory

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

• 매개변수:
  • content str – 메모리로 저장할 텍스트 콘텐츠입니다.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – 저장할 메모리 범주입니다. 지원되는 값은 "memory", "fact", "guideline" 및 "preference"입니다. 생략하면 콘텐츠가 일반 "memory"로 저장됩니다.
  • user_id str – 선택적 사용자 식별자 대체입니다.
  • agent_id str – 선택적 에이전트 식별자 대체입니다.
  • thread_id str – 선택적 스레드 식별자 대체입니다.
  • memory_id str – 이 메모리 행에 대해 선택적인 호출자가 제공하는 안정적인 식별자입니다.
  • metadata dict[str, Any] | None – 저장된 메모리와 함께 지속되는 선택적 메타데이터입니다.
  • timestamp str | None – 이 메모리에 대해 저장할 선택적 이벤트 시간 기록입니다. 이 인수를 생략하거나 None를 전달하여 NULL 이벤트 시간 기록을 저장합니다. 레코드를 읽으면 생성 시간이 유효 시간 기록으로 반환됩니다. ttl_anchor가 TimeToLiveAnchor.TIMESTAMP인 경우 구체적인 ISO-8601 시간 기록 값을 제공합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • ttl_days int | None – 선택적 TTL 기간(일)입니다. 스키마 기본 TTL 기간을 사용하려면 이 인수를 생략하십시오. 보존 구성이 하나를 설정할 때 MemoryRetentionConfig.max_ttl_days를 사용하거나 만료되지 않는 메모리를 저장하려면 None를 전달합니다. MemoryRetentionConfig.max_ttl_days 이상의 값은 경고와 함께 해당 최대값으로 고정됩니다.
  • ttl_anchor TimeToLiveAnchor – 선택적 TTL(Time-to-Live) 앵커 데이터베이스 생성 시간에 TimeToLiveAnchor.CREATED_AT를 사용하고 메모리 시간 기록에 TimeToLiveAnchor.TIMESTAMP를 사용합니다. 타임스탬프 기록 만료에는 이 메모리에 대한 구체적인 ISO-8601 타임스탬프가 필요합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • status RecordStatus – 초기 수명 주기 상태입니다. RecordStatus.VALID를 저장하려면 생략합니다.
  • autonomous_linking bool – 스레드의 LLM을 사용하여 이 새 메모리에서 관련 저장된 메모리에 대한 링크를 생성할지 여부입니다. 생략하면 LLM이 존재할 때 사용으로 설정됩니다. 건너뛰려면 False을 전달하십시오. 실패하면 메모리가 저장되지 않습니다.
  • memory_id_to_link str – 함께 새 메모리에서 이 기존 스레드 소유 메모리로의 지정 링크를 만듭니다. 생략된 사용자, 에이전트 및 스레드 범위는 해당 대상에서 상속됩니다. 명시적 링크를 생성하지 않으려면 둘 다 생략합니다.
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker – 함께 새 메모리에서 이 기존 스레드 소유 메모리로의 지정 링크를 만듭니다. 생략된 사용자, 에이전트 및 스레드 범위는 해당 대상에서 상속됩니다. 명시적 링크를 생성하지 않으려면 둘 다 생략합니다.
  • link_id str – 명시적 링크에 대한 선택적 식별자, 시간 기록 및 메타데이터입니다.
  • link_timestamp str | None – 명시적 링크에 대한 선택적 식별자, 시간 기록 및 메타데이터입니다.
  • link_metadata dict[str, Any] | None – 명시적 링크에 대한 선택적 식별자, 시간 기록 및 메타데이터입니다.
  • **store_kwargs(임의) – 보조 기억 장치로 전달된 저장소별 쓰기 옵션입니다.
• 반환: 삽입된 메모리 레코드의 식별자입니다.
• 반환 유형: str

예제

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

method add_memory_async(비동기)

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

• 매개변수:
  • content str – 메모리로 저장할 텍스트 콘텐츠입니다.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – 저장할 메모리 범주입니다. 지원되는 값은 "memory", "fact", "guideline" 및 "preference"입니다. 생략하면 콘텐츠가 일반 "memory"로 저장됩니다.
  • user_id str – 선택적 사용자 식별자 대체입니다.
  • agent_id str – 선택적 에이전트 식별자 대체입니다.
  • thread_id str – 선택적 스레드 식별자 대체입니다.
  • memory_id str – 이 메모리 행에 대해 선택적인 호출자가 제공하는 안정적인 식별자입니다.
  • metadata dict[str, Any] | None – 저장된 메모리와 함께 지속되는 선택적 메타데이터입니다.
  • timestamp str | None – 이 메모리에 대해 저장할 선택적 이벤트 시간 기록입니다. 이 인수를 생략하거나 None를 전달하여 NULL 이벤트 시간 기록을 저장합니다. 레코드를 읽으면 생성 시간이 유효 시간 기록으로 반환됩니다. ttl_anchor가 TimeToLiveAnchor.TIMESTAMP인 경우 구체적인 ISO-8601 시간 기록 값을 제공합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • ttl_days int | None – 선택적 TTL 기간(일)입니다. 스키마 기본 TTL 기간을 사용하려면 이 인수를 생략하십시오. 보존 구성이 하나를 설정할 때 MemoryRetentionConfig.max_ttl_days를 사용하거나 만료되지 않는 메모리를 저장하려면 None를 전달합니다. MemoryRetentionConfig.max_ttl_days 이상의 값은 경고와 함께 해당 최대값으로 고정됩니다.
  • ttl_anchor TimeToLiveAnchor – 선택적 TTL(Time-to-Live) 앵커 데이터베이스 생성 시간에 TimeToLiveAnchor.CREATED_AT를 사용하고 메모리 시간 기록에 TimeToLiveAnchor.TIMESTAMP를 사용합니다. 타임스탬프 기록 만료에는 이 메모리에 대한 구체적인 ISO-8601 타임스탬프가 필요합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • status RecordStatus – 초기 수명 주기 상태입니다. RecordStatus.VALID를 저장하려면 생략합니다.
  • autonomous_linking bool – 스레드의 LLM을 사용하여 이 새 메모리에서 관련 저장된 메모리에 대한 링크를 생성할지 여부입니다. 생략하면 LLM이 존재할 때 사용으로 설정됩니다. 건너뛰려면 False을 전달하십시오. 실패하면 메모리가 저장되지 않습니다.
  • memory_id_to_link str – 함께 새 메모리에서 이 기존 스레드 소유 메모리로의 지정 링크를 만듭니다. 생략된 사용자, 에이전트 및 스레드 범위는 해당 대상에서 상속됩니다. 명시적 링크를 생성하지 않으려면 둘 다 생략합니다.
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker – 함께 새 메모리에서 이 기존 스레드 소유 메모리로의 지정 링크를 만듭니다. 생략된 사용자, 에이전트 및 스레드 범위는 해당 대상에서 상속됩니다. 명시적 링크를 생성하지 않으려면 둘 다 생략합니다.
  • link_id str – 명시적 링크에 대한 선택적 식별자, 시간 기록 및 메타데이터입니다.
  • link_timestamp str | None – 명시적 링크에 대한 선택적 식별자, 시간 기록 및 메타데이터입니다.
  • link_metadata dict[str, Any] | None – 명시적 링크에 대한 선택적 식별자, 시간 기록 및 메타데이터입니다.
  • **store_kwargs(임의) – 보조 기억 장치로 전달된 저장소별 쓰기 옵션입니다.
• 반환: 삽입된 메모리 레코드의 식별자입니다.
• 반환 유형: str

예제

import asyncio
asyncio.run(thread.add_memory_async(
    "Remember this preference", memory_id="mem-thread-docs-async"
))
'mem-thread-docs-async'

방법 add_messages

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

백그라운드 추출 모드에서 이 메소드는 원시 메시지가 삽입되고 백그라운드에서 백그라운드 추출을 시도한 후에 반환됩니다.

원시 메시지는 두 모드 중 하나에서 자동 추출되기 전에 저장됩니다. 추후 추출 또는 파생 메모리 저장이 실패할 경우 원시 메시지는 저장된 상태로 유지되지만 파생된 메모리 또는 요약 업데이트가 누락될 수 있습니다.

• 매개변수:
  • messages Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]] – 추가할 메시지 목록입니다. 메시지는 Message 객체 또는 role 및 content(및 선택적 id)의 사전일 수 있습니다.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – 지속할 선택적 공유 또는 메시지별 메타데이터입니다. 생략할 경우 각 메시지에 포함된 메타데이터가 사용됩니다.
  • ttl_days int | None | list[int | None] – 추가된 메시지에 대한 선택적 TTL 기간(일)입니다. 스키마 기본 TTL 기간을 사용하려면 이 인수를 생략하십시오. 보존 구성이 하나를 설정할 때 MemoryRetentionConfig.max_ttl_days를 사용하거나 만료되지 않는 메시지를 만들려면 None를 전달합니다. MemoryRetentionConfig.max_ttl_days 이상의 값은 경고와 함께 해당 최대값으로 고정됩니다. 스칼라 값은 전체 배치에 적용됩니다.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – 선택적 TTL(Time-to-Live) 앵커 데이터베이스 생성 시간에는 TimeToLiveAnchor.CREATED_AT를 사용하고 각 메시지 시간기록에는 TimeToLiveAnchor.TIMESTAMP를 사용합니다. 타임스탬프 기록 만료 시 영향을 받는 각 메시지에 대해 구체적인 ISO-8601 타임스탬프가 필요합니다. 생략할 경우 메시지는 TimeToLiveAnchor.CREATED_AT를 기준으로 만료됩니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • **store_kwargs(임의) – 보조 기억 장치로 전달된 저장소별 쓰기 옵션입니다.
• 반환: 삽입된 메시지 레코드의 식별자입니다. 백그라운드 추출 모드에서는 이러한 식별자가 반환될 때 자동 추출 작업이 계속 실행 중일 수 있습니다.
• 반환 유형: list[str]

노트

MemoryExtractionMode.BACKGROUND에서는 추출된 메모리가 저장되기 전에 원시 메시지가 지속됩니다. 백그라운드 추출이 대기열에 추가되지 않거나 구성된 대기열 용량 대기가 시간 초과에 도달하면 삽입된 원시 메시지는 저장된 상태로 유지되며 추출된 메모리 없이 호출이 계속되거나 background_extraction_queue_full_behavior에 따라 TimeoutError가 발생합니다.

예제

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

method add_messages_async(비동기)

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

백그라운드 추출 모드에서 이 메소드는 원시 메시지가 삽입되고 백그라운드에서 백그라운드 추출을 시도한 후에 반환됩니다.

원시 메시지는 두 모드 중 하나에서 자동 추출되기 전에 저장됩니다. 추후 추출 또는 파생 메모리 저장이 실패할 경우 원시 메시지는 저장된 상태로 유지되지만 파생된 메모리 또는 요약 업데이트가 누락될 수 있습니다.

MemoryExtractionMode.BACKGROUND에서는 추출된 메모리가 저장되기 전에 원시 메시지가 지속됩니다. 백그라운드 추출이 대기열에 추가되지 않거나 구성된 대기열 용량 대기가 시간 초과에 도달하면 삽입된 원시 메시지는 저장된 상태로 유지되며 추출된 메모리 없이 호출이 계속되거나 background_extraction_queue_full_behavior에 따라 TimeoutError가 발생합니다.

• 매개변수:
  • 메시지 Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]]
  • 메타데이터 dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• 반환 유형: list[str]

방법 delete_image

이 스레드가 소유한 하나의 이미지를 삭제합니다.

• 매개변수: image_id str – 삭제할 이미지의 식별자입니다.
• 반환: 삭제된 경우 1, 그렇지 않은 경우 이미지가 존재하지 않거나 다른 스레드에 속하는 경우 0입니다.
• 반품 유형: int
• Raises: ValueError – 이미지가 메시지에 연결된 경우입니다. 대신 상위 메시지를 삭제하거나 업데이트하십시오.

method delete_image_async(비동기)

이 스레드가 소유한 하나의 이미지를 비동기적으로 삭제합니다.

• 매개변수: image_id str – 삭제할 이미지의 식별자입니다.
• 반환: 삭제된 경우 1, 그렇지 않은 경우 이미지가 존재하지 않거나 다른 스레드에 속하는 경우 0입니다.
• 반품 유형: int
• Raises: ValueError – 이미지가 메시지에 연결된 경우입니다. 대신 상위 메시지를 삭제하거나 업데이트하십시오.

방법 delete_memory

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

• 매개변수: memory_id str – 메모리 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메모리 유사 레코드(memory, guideline, fact, preference)만 삭제됩니다.
• 반환: 삭제된 레코드 수(0 또는 1). 식별자가 존재하지 않거나 다른 스레드에 속하는 경우 0를 반환합니다.
• 반품 유형: int
• 발생: TimeoutError – 이 스레드에 대해 이전에 수락된 백그라운드 추출이 300초 내에 완료되지 않을 때 레코드를 삭제하지 않고 발생합니다.

노트

레코드를 삭제하기 전에 이 메소드는 연결된 에이전트 메모리 구성 요소를 통해 이 스레드에 대해 수락된 이전 백그라운드 추출을 기다립니다. 대기가 시작된 후 또는 다른 구성 요소나 프로세스가 작업을 시작한 후 수락된 작업을 기다리지 않습니다.

예제

thread.delete_memory("456")
0

method delete_memory_async(비동기)

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

• 매개변수: memory_id str – 메모리 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메모리 유사 레코드(memory, guideline, fact, preference)만 삭제됩니다.
• 반환: 삭제된 레코드 수(0 또는 1). 식별자가 존재하지 않거나 다른 스레드에 속하는 경우 0를 반환합니다.
• 반품 유형: int
• 발생: TimeoutError – 이 스레드에 대해 이전에 수락된 백그라운드 추출이 300초 내에 완료되지 않을 때 레코드를 삭제하지 않고 발생합니다.

노트

이 방법은 delete_memory()에 설명된 백그라운드 추출 대기 및 동시성 동작을 따릅니다.

예제

import asyncio
asyncio.run(thread.delete_memory_async("456"))
0

방법 delete_message

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

• 매개변수: message_id str – 메시지 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메시지만 삭제됩니다.
• 반환: 삭제된 메시지 레코드 수(0 또는 1)입니다. 식별자가 존재하지 않거나 다른 스레드에 속하는 경우 0를 반환합니다.
• 반품 유형: int
• 발생: TimeoutError – 이 스레드에 대해 이전에 수락된 백그라운드 추출이 300초 내에 완료되지 않을 때 메시지를 삭제하지 않고 발생합니다.

노트

메시지를 삭제하기 전에 이 메소드는 연결된 에이전트 메모리 구성 요소를 통해 이 스레드에 대해 수락된 이전 백그라운드 추출을 기다립니다. 대기가 시작된 후 또는 다른 구성 요소나 프로세스가 작업을 시작한 후 수락된 작업을 기다리지 않습니다.

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

예제

thread.delete_message("123")
0

method delete_message_async(비동기)

이 스레드에서 비동기식 식별자로 메시지 레코드를 삭제합니다.

• 매개변수: message_id str – 메시지 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메시지만 삭제됩니다.
• 반환: 삭제된 메시지 레코드 수(0 또는 1)입니다. 식별자가 존재하지 않거나 다른 스레드에 속하는 경우 0를 반환합니다.
• 반품 유형: int
• 발생: TimeoutError – 이 스레드에 대해 이전에 수락된 백그라운드 추출이 300초 내에 완료되지 않을 때 메시지를 삭제하지 않고 발생합니다.

노트

이 방법은 delete_message()에 설명된 백그라운드 추출 대기 및 동시성 동작을 따릅니다.

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

예제

import asyncio
asyncio.run(thread.delete_message_async("123"))
0

방법 delete_record_link

ID별 스레드 소유 관계를 삭제하거나 끝점 튜플을 완료합니다.

끝점-튜플 선택기는 저장된 소스-대상 방향을 사용해야 합니다.

• 매개변수:
  • source_record_id str – 끝점 튜플 선택기의 소스 식별자입니다.
  • source_record_type str – 끝점 튜플 선택기에 대한 논리적 소스 레코드 유형입니다.
  • target_record_id str – 끝점 튜플 선택기의 대상 식별자입니다.
  • target_record_type str – 끝점 튜플 선택기에 대한 논리적 대상 레코드 유형입니다.
  • relation_type str – 끝점 튜플 선택기에 대한 소스-대상 레이블입니다.
  • relation_id str – 직접 선택할 관계 식별자입니다. 이 인수만 제공하십시오.
• 반환: 삭제된 관계 수(0 또는 1)입니다.
• 반품 유형: int

예제

thread.delete_record_link(relation_id="relation-id")
1

method delete_record_link_async(비동기)

이 스레드가 소유한 관계를 비동기적으로 삭제합니다.

• 매개변수:
  • source_record_id str
  • source_record_type str
  • target_record_id str
  • target_record_type str
  • relation_type str
  • relation_id str
• 반품 유형: int

방법 get_context_card

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

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

• 매개변수:
  • fallback_message_count int – 검색 및 렌더링을 위해 폴백 요약 텍스트를 파생할 때 사용할 최근 메시지 수입니다. 생략할 경우 5로 해결됩니다.

  • max_relevant_results int –

    컨텍스트 카드의 <relevant_information> 섹션에 포함할 관련 레코드의 최대 수(메모리 유사(예: 팩트/환경설정, 메시지)입니다.

    • 이 값과 min_relevant_results_by_type를 모두 생략하면 max_relevant_results가 5로 분석됩니다.
    • min_relevant_results_by_type가 제공된 경우 max_relevant_results는 max(max_relevant_results, sum(min_relevant_results_by_type.values()))로 분석됩니다.
  • token_budget int | None – 컨텍스트 카드에서 형식이 지정된 관련 결과의 예상 토큰 수에 대한 하드 한계(선택사항)입니다. 생략할 경우 스레드 검색 구성이 사용됩니다. 양수 값은 전체 결과를 순위 순서대로 유지하며 누적 예측은 예산에 맞습니다. 첫 번째 결과가 맞지 않으면 관련 결과가 포함되지 않습니다. 양수가 아닌 값은 상한값을 사용 안함으로 설정합니다.
  • soft_token_budget int | None – 형식이 지정된 관련 결과의 예상 토큰 수에 대한 선택적 대상입니다. 생략할 경우 스레드 검색 구성이 사용됩니다. 이 대상에 도달하거나 초과한 전체 결과는 보존됩니다. 양수가 아닌 값은 이 대상을 사용 안함으로 설정합니다. 출력에 절대 제한도 있어야 하는 경우 token_budget를 더 큰 값으로 설정합니다.
  • max_recent_messages int – 컨텍스트 카드의 <recent_messages> 섹션에 포함할 최대 최근 대화 메시지 수입니다. 생략할 경우 max_recent_messages는 0로 분석됩니다.

  • except_last_messages int –

    컨텍스트 카드에 포함된 생성된 요약 및 관련 정보 검색에서 제외할 후행 메시지 수입니다. 이렇게 하면 LLM 프롬프트에 별도로 제공된 메시지가 컨텍스트 카드에서 중복되지 않습니다. 다음 패턴 중 하나를 사용합니다.

    • 외부 원시 꼬리(프롬프트 캐싱에 권장됨):

      get_context_card(except_last_messages=N, max_recent_messages=0) 프롬프트에는 컨텍스트 카드와 마지막 N 원시 메시지가 포함됩니다.

    • 자체 포함 컨텍스트 카드:

      get_context_card(except_last_messages=N, max_recent_messages=N) 컨텍스트 카드에는 마지막 N 메시지 자체가 포함됩니다.

    0이 아닌 경우 max_recent_messages은 0 또는 동일한 값이어야 합니다.

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – 컨텍스트 카드에 포함된 관련 레코드에 대한 선택적 유형별 최소값입니다. 요청된 유형이 먼저 검색되고 나머지 max_relevant_results 슬롯은 지원되는 모든 메모리 유사 레코드 유형에서 채워집니다. 지원되는 키는 "memory", "fact", "guideline", "preference" 및 "message"입니다. 메시지 결과는 현재 스레드로 제한됩니다.

  • metadata_filter dict[str, Any] | None –

    컨텍스트 카드에 포함할 메모리 유사 레코드를 검색할 때 범위 및 레코드 유형 필터링 후 추가 필터로 사용되는 선택적 메타데이터 필터 매핑입니다. metadata_filter의 항목은 AND 의미와 결합됩니다. 값이 필드 레벨 연산자 딕셔너리가 아닌 항목은 정확한 일치 의미를 사용합니다. 즉, 요청된 키가 저장된 레코드 메타데이터에 있어야 합니다. 중첩된 딕셔너리는 중첩된 메타 데이터 객체를 재귀적으로 일치시킵니다. 스칼라 및 목록 값이 정확히 일치해야 합니다. 목록 순서 및 길이도 일치해야 합니다. 메타데이터 필터링 없이 검색하려면 이 인수를 생략하거나 None를 전달하십시오. 예를 들어 스칼라 필드의 경우 metadata_filter={"source": "chat"}, 중첩 필드의 경우 metadata_filter={"travel": {"need": "transit"}}, 정확한 목록 일치의 경우 metadata_filter={"tags": ["trip", "urgent"]}가 있습니다. 조건을 결합하여 모든 조건을 요구합니다.

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    배열 멤버쉽을 테스트하려면 필드 레벨 연산자 딕셔너리를 사용합니다. "$array_contains"는 하나의 값 또는 목록의 모든 값과 일치합니다. "$array_contains_any"는 목록의 하나 이상의 값과 일치합니다. "$not"는 연산자 딕셔너리 또는 원시 정확한 일치 값을 포함하여 동일한 필드에서 다른 필드 레벨 표현식을 부정합니다. 누락된 필드를 포함하여 양수 표현식이 실패할 때 음수 표현식이 일치합니다. 음수 배열 멤버쉽도 배열이 아닌 필드와 일치합니다.

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – 잘못된 수명 주기 상태의 관련 레코드가 컨텍스트 카드에 포함되는지 여부입니다. 이 인수를 생략하거나 포함하려면 True를 전달하십시오. False를 전달하여 제외합니다.
  • **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
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

method get_context_card_async(비동기)

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

• 매개변수:
  • fallback_message_count int – 검색 및 렌더링을 위해 폴백 요약 텍스트를 파생할 때 사용할 최근 메시지 수입니다. 생략할 경우 5로 해결됩니다.

  • max_relevant_results int –

    컨텍스트 카드의 <relevant_information> 섹션에 포함할 관련 레코드의 최대 수(메모리 유사(예: 팩트/환경설정, 메시지)입니다.

    • 이 값과 min_relevant_results_by_type를 모두 생략하면 max_relevant_results가 5로 분석됩니다.
    • min_relevant_results_by_type가 제공된 경우 max_relevant_results는 max(max_relevant_results, sum(min_relevant_results_by_type.values()))로 분석됩니다.
  • token_budget int | None – 컨텍스트 카드에서 형식이 지정된 관련 결과의 예상 토큰 수에 대한 하드 한계(선택사항)입니다. 생략할 경우 스레드 검색 구성이 사용됩니다. 양수 값은 전체 결과를 순위 순서대로 유지하며 누적 예측은 예산에 맞습니다. 첫 번째 결과가 맞지 않으면 관련 결과가 포함되지 않습니다. 양수가 아닌 값은 상한값을 사용 안함으로 설정합니다.
  • soft_token_budget int | None – 형식이 지정된 관련 결과의 예상 토큰 수에 대한 선택적 대상입니다. 생략할 경우 스레드 검색 구성이 사용됩니다. 이 대상에 도달하거나 초과한 전체 결과는 보존됩니다. 양수가 아닌 값은 이 대상을 사용 안함으로 설정합니다. 출력에 절대 제한도 있어야 하는 경우 token_budget를 더 큰 값으로 설정합니다.
  • max_recent_messages int – 컨텍스트 카드의 <recent_messages> 섹션에 포함할 최대 최근 대화 메시지 수입니다. 생략할 경우 max_recent_messages는 0로 분석됩니다.

  • except_last_messages int –

    컨텍스트 카드에 포함된 생성된 요약 및 관련 정보 검색에서 제외할 후행 메시지 수입니다. 이렇게 하면 LLM 프롬프트에 별도로 제공된 메시지가 컨텍스트 카드에서 중복되지 않습니다. 다음 패턴 중 하나를 사용합니다.

    • 외부 원시 꼬리(프롬프트 캐싱에 권장됨):

      get_context_card(except_last_messages=N, max_recent_messages=0) 프롬프트에는 컨텍스트 카드와 마지막 N 원시 메시지가 포함됩니다.

    • 자체 포함 컨텍스트 카드:

      get_context_card(except_last_messages=N, max_recent_messages=N) 컨텍스트 카드에는 마지막 N 메시지 자체가 포함됩니다.

    0이 아닌 경우 max_recent_messages은 0 또는 동일한 값이어야 합니다.

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – 컨텍스트 카드에 포함된 관련 레코드에 대한 선택적 유형별 최소값입니다. 요청된 유형이 먼저 검색되고 나머지 max_relevant_results 슬롯은 지원되는 모든 메모리 유사 레코드 유형에서 채워집니다. 지원되는 키는 "memory", "fact", "guideline", "preference" 및 "message"입니다. 메시지 결과는 현재 스레드로 제한됩니다.

  • metadata_filter dict[str, Any] | None –

    컨텍스트 카드에 포함할 메모리 유사 레코드를 검색할 때 범위 및 레코드 유형 필터링 후 추가 필터로 사용되는 선택적 메타데이터 필터 매핑입니다. metadata_filter의 항목은 AND 의미와 결합됩니다. 값이 필드 레벨 연산자 딕셔너리가 아닌 항목은 정확한 일치 의미를 사용합니다. 즉, 요청된 키가 저장된 레코드 메타데이터에 있어야 합니다. 중첩된 딕셔너리는 중첩된 메타 데이터 객체를 재귀적으로 일치시킵니다. 스칼라 및 목록 값이 정확히 일치해야 합니다. 목록 순서 및 길이도 일치해야 합니다. 메타데이터 필터링 없이 검색하려면 이 인수를 생략하거나 None를 전달하십시오. 예를 들어 스칼라 필드의 경우 metadata_filter={"source": "chat"}, 중첩 필드의 경우 metadata_filter={"travel": {"need": "transit"}}, 정확한 목록 일치의 경우 metadata_filter={"tags": ["trip", "urgent"]}가 있습니다. 조건을 결합하여 모든 조건을 요구합니다.

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    배열 멤버쉽을 테스트하려면 필드 레벨 연산자 딕셔너리를 사용합니다. "$array_contains"는 하나의 값 또는 목록의 모든 값과 일치합니다. "$array_contains_any"는 목록의 하나 이상의 값과 일치합니다. "$not"는 연산자 딕셔너리 또는 원시 정확한 일치 값을 포함하여 동일한 필드에서 다른 필드 레벨 표현식을 부정합니다. 누락된 필드를 포함하여 양수 표현식이 실패할 때 음수 표현식이 일치합니다. 음수 배열 멤버쉽도 배열이 아닌 필드와 일치합니다.

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – 잘못된 수명 주기 상태의 관련 레코드가 컨텍스트 카드에 포함되는지 여부입니다. 이 인수를 생략하거나 포함하려면 True를 전달하십시오. False를 전달하여 제외합니다.
  • **kwargs(Any) – 이후 컨텍스트 카드 옵션용으로 예약되어 있습니다. 예상치 않은 키워드 인수가 TypeError를 발생시킵니다.
• 반환: 스레드에 대한 컨텍스트 카드 객체입니다.
• 반환 유형: OracleContextCard

예제

import asyncio
card = asyncio.run(thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
))
len(card.relevant_results or []) <= 5
True

방법 get_message

이 글타래가 소유하는 메시지 한 개를 반환합니다.

이미지 부분은 기본적으로 식별자 및 설명과 함께 반환됩니다. 선택한 이미지 부분에 대한 바이트를 로드하려면 included_image_ids를 전달합니다. 관련 없는 식별자는 무시됩니다.

• 매개변수:
  • message_id str – 검색할 메시지의 식별자입니다. 메시지는 이 글타래에 속해야 합니다.
  • included_image_ids list[str] – 바이트가 로드되어야 하는 연결된 이미지 식별자의 선택적 목록입니다. 이 인수를 생략하거나 바이트를 로드하지 않고 이미지 메타데이터를 반환하도록 None를 전달하십시오.
• 반환: 첨부된 이미지 부분을 포함하여 요청된 메시지입니다.
• 반환 유형: 메시지
• 발생: KeyError – 메시지가 존재하지 않거나 다른 스레드에 속하는 경우입니다.

method get_message_async(비동기)

하나의 스레드 소유 메시지를 비동기적으로 반환합니다.

included_image_ids는 선택적으로 바이트를 로드해야 하는 연결된 이미지 부분을 선택합니다. 생략하거나 None는 이미지 메타데이터만 반환합니다.

• 매개변수:
  • message_id str – 검색할 메시지의 식별자입니다. 메시지는 이 글타래에 속해야 합니다.
  • included_image_ids list[str] – 하이드레이트할 연결된 이미지 식별자의 선택적 목록입니다.
• 반환: 첨부된 이미지 부분을 포함하여 요청된 메시지입니다.
• 반환 유형: 메시지
• 발생: KeyError – 메시지가 존재하지 않거나 다른 스레드에 속하는 경우입니다.

방법 get_messages

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

• 매개변수:
  • start int | None – 시작 인덱스(0 기반)입니다. end와 함께 생략하면 가장 최근의 바인드된 창이 반환됩니다.
  • end int | None – 종료 인덱스(배타적)입니다. 생략하면 가장 최근 메시지의 제한된 창이 반환됩니다. None 또는 -1를 전달하여 start 이후부터 모든 메시지를 명시적으로 요청합니다.
  • include_image_bytes bool – 반환된 메시지에 연결된 이미지 부분에 대한 바이트를 로드할지 여부입니다. 이 인수를 생략하거나 BLOB 값을 로드하지 않고 이미지 메타데이터를 반환하도록 False를 전달합니다.
• 반환: 시간순으로 메시지를 표시합니다.
• 반환 유형: list[메시지]

예제

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

method get_messages_async(비동기)

add_messages와 함께 비동기적으로 추가된 대로 스레드에서 처리되지 않은 메시지를 가져옵니다.

• 매개변수:
  • start int | None – 시작 인덱스(0 기반)입니다. end와 함께 생략하면 가장 최근의 바인드된 창이 반환됩니다.
  • end int | None – 종료 인덱스(배타적)입니다. 생략하면 가장 최근 메시지의 제한된 창이 반환됩니다. None 또는 -1를 전달하여 start 이후부터 모든 메시지를 명시적으로 요청합니다.
  • include_image_bytes bool – 반환된 메시지에 연결된 이미지 부분에 대한 바이트를 로드할지 여부입니다. 이 인수를 생략하거나 BLOB 값을 로드하지 않고 이미지 메타데이터를 반환하도록 False를 전달합니다.
• 반환: 시간순으로 메시지를 표시합니다.
• 반환 유형: list[메시지]

예제

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Stored message example"}]
))
len(message_ids)
1
messages = asyncio.run(thread.get_messages_async())
messages[-1].content
'Stored message example'

방법 get_summary

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

전체 스레드 요청은 영구 요약을 재사용하거나 새로 고칩니다. except_last가 포함된 요청은 내구성이 뛰어난 전체 스레드 요약을 변경하지 않고 해당 접두어를 요약합니다.

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

• 매개변수:
  • except_last int – 요약에서 제외할 최근 메시지 수입니다.
  • token_budget int – 소프트 토큰 예산입니다. 생략할 경우 제한된 기본값이 적용됩니다. 형식 지정된 요약이 예산을 초과하는 경우에만 양수 값이 잘립니다. 양수가 아닌 값은 예산 기반 자르기를 사용 안함으로 설정합니다. 성적 증명서 폴백은 4,000자로 제한됩니다.
  • **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가 포함된 요청은 내구성이 뛰어난 전체 스레드 요약을 변경하지 않고 해당 접두어를 요약합니다.

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

방법 link_records

이 스레드가 소유한 두 레코드 간에 지시된 관계를 생성합니다.

현재 두 끝점은 메모리와 유사한 레코드("memory", "fact", "guideline" 또는 "preference")여야 합니다. 기본 제공 관계 유형은 "supersedes"("is_superseded_by"), "contradicts", "refines"("is_refined_by"), "supports"("is_supported_by") 및 "duplicates"입니다. "contradicts" 및 "duplicates"는 동일한 레이블을 역방향으로 사용합니다.

두 끝점은 이 정확한 스레드에 속해야 합니다. 끝점 쌍에 대해 하나의 방향만 저장할 수 있습니다. opposite_relation_type는 대상에서 소스로 순회할 때 관계 이름을 지정합니다. 예를 들어, new "supersedes" old은 해당 방향에서 old "is_superseded_by" new가 됩니다.

• 매개변수:
  • source_record_id str – 스레드 소유 소스 레코드의 식별자입니다.
  • source_record_type str – 소스 레코드의 논리적 유형입니다.
  • target_record_id str – 스레드 소유 대상 레코드의 식별자입니다.
  • target_record_type str – 대상 레코드의 논리적 유형입니다.
  • relation_type str – 소스-대상 관계 레이블입니다.
  • opposite_relation_type str – 선택적 역방향 레이블입니다. 내장 메모리 관계 유형의 경우 생략은 미리 정의된 역방향 레이블을 사용하고, 사용자 관계 유형의 경우 생략은 양방향에서 동일한 레이블을 사용합니다.
  • relation_id str – 선택적 안정적 관계 식별자입니다. 생성하려면 생략합니다.
  • timestamp str | None – 관계에 저장된 선택적 시간 기록입니다.
  • metadata dict[str, Any] | None – 선택적 관계 메타데이터입니다.
• 반환: 생성된 관계의 식별자입니다.
• 반환 유형: str

예제

thread.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

method link_records_async(비동기)

이 스레드가 소유한 레코드 간에 비동기적으로 관계를 생성합니다.

현재 두 끝점은 메모리와 유사한 레코드("memory", "fact", "guideline" 또는 "preference")여야 합니다. 기본 제공 관계 유형은 "supersedes"("is_superseded_by"), "contradicts", "refines"("is_refined_by"), "supports"("is_supported_by") 및 "duplicates"입니다. "contradicts" 및 "duplicates"는 동일한 레이블을 역방향으로 사용합니다.

• 매개변수:
  • source_record_id str
  • source_record_type str
  • target_record_id str
  • target_record_type str
  • relation_type str
  • opposite_relation_type str
  • relation_id str
  • 시간 기록 str | None
  • 메타데이터 dict[str, Any] | None
• 반환 유형: str

방법 list_images

이 스레드가 소유한 이미지 레코드를 나열합니다.

반환된 레코드에는 기본적으로 이미지 메타데이터가 포함됩니다. 원시 바이트는 include_bytes=True 및 image_id가 제공된 경우에만 로드됩니다.

• 매개변수:
  • image_id str – 이미지를 필터링하는 데 사용되는 선택적 식별자입니다. 생략할 경우 식별자 필터가 적용되지 않습니다.
  • metadata_filter dict[str, Any] | None – 이미지 메타데이터에 적용되는 선택적 필터입니다.
  • include_bytes bool – 원시 바이트를 로드할지 여부입니다. image_id가 필요합니다.
  • limit int | None – 최대 레코드 수(선택 사항)입니다. 저장소의 기본 제한을 사용 안함으로 설정하려면 None을 전달합니다.
• 반품: 매장 순서대로 이미지를 일치시킵니다.
• 반환 유형: list[ImageRecord]

method list_images_async(비동기)

이 스레드가 소유한 이미지 레코드를 비동기적으로 나열합니다.

반환된 레코드에는 기본적으로 이미지 메타데이터가 포함됩니다. 원시 바이트는 include_bytes=True 및 image_id가 제공된 경우에만 로드됩니다. 이 스레드의 범위는 자동으로 적용됩니다.

• 매개변수:
  • image_id str – 이미지를 필터링하는 데 사용되는 선택적 식별자입니다. 생략할 경우 식별자 필터가 적용되지 않습니다.
  • metadata_filter dict[str, Any] | None – 이미지 메타데이터에 적용되는 선택적 필터입니다.
  • include_bytes bool – 원시 바이트를 로드할지 여부입니다. image_id가 필요합니다.
  • limit int | None – 최대 레코드 수(선택 사항)입니다. 저장소의 기본 제한을 사용 안함으로 설정하려면 None을 전달합니다.
• 반품: 매장 순서대로 이미지를 일치시킵니다.
• 반환 유형: list[ImageRecord]

방법 search

조회와 관련된 레코드를 동기적으로 검색합니다.

• 매개변수:
  • query str – 자연어 질의 문자열입니다.
  • user_id str | None – 선택적 사용자 범위 대체입니다. 생략된 값은 스레드의 기본 사용자 범위를 상속합니다.
  • agent_id str | None – 선택적 에이전트 범위 대체입니다. 생략된 값은 스레드의 기본 에이전트 범위를 상속합니다.
  • thread_id str | None – 선택적 스레드 범위 대체입니다. 생략된 값은 스레드의 현재 스레드 식별자를 상속합니다.
  • exact_user_match bool – 사용자 일치가 엄격해야 하는지 여부입니다.
  • exact_agent_match bool – 에이전트 일치가 엄격해야 하는지 여부입니다.
  • exact_thread_match bool – 스레드 일치가 엄격해야 하는지 여부입니다.
  • max_results int – 반환할 최대 결과 수(선택 사항)입니다. 제공된 경우 1 이상이어야 합니다. 이 인수를 생략하면 기본값인 10가 사용됩니다. 만료되지 않은 일치 레코드가 더 적을 경우 호출이 max_results 미만으로 반환될 수 있습니다.
  • token_budget int – 최종 형식 지정된 결과의 예상 토큰 수에 대한 선택적 하드 제한입니다. 생략할 경우 확인된 검색 구성이 사용됩니다. 양수 값은 전체 결과를 순위 순서대로 유지하며 누적 예측은 예산에 맞습니다. 첫 번째 결과가 맞지 않으면 결과가 반환되지 않습니다. 양수가 아닌 값은 이 출력 한도를 사용 안함으로 설정합니다.
  • soft_token_budget int – 최종 형식 지정된 결과의 예상 토큰 수에 대한 선택적 대상입니다. 생략할 경우 확인된 검색 구성이 사용됩니다. 이 대상에 도달하거나 초과한 전체 결과는 보존됩니다. 양수가 아닌 값은 이 대상을 사용 안함으로 설정합니다. 출력에 절대 제한도 있어야 하는 경우 token_budget를 더 큰 값으로 설정합니다.
  • record_types list[str] – 포함할 레코드 유형(예: "memory", "message" 또는 "image")의 선택적 목록입니다.

  • metadata_filter dict[str, Any] | None –

    범위 및 레코드 유형 필터링 후 추가 필터로 사용되는 선택적 메타데이터 필터 매핑입니다. metadata_filter의 항목은 AND 의미와 결합됩니다. 값이 필드 레벨 연산자 딕셔너리가 아닌 항목은 정확한 일치 의미를 사용합니다. 즉, 요청된 키가 저장된 레코드 메타데이터에 있어야 합니다. 중첩된 딕셔너리는 중첩된 메타 데이터 객체를 재귀적으로 일치시킵니다. 스칼라 및 목록 값이 정확히 일치해야 합니다. 목록 순서 및 길이도 일치해야 합니다. 메타데이터 필터링 없이 검색하려면 이 인수를 생략하거나 None를 전달하십시오. 예를 들어 스칼라 필드의 경우 metadata_filter={"source": "chat"}, 중첩 필드의 경우 metadata_filter={"travel": {"need": "transit"}}, 정확한 목록 일치의 경우 metadata_filter={"tags": ["trip", "urgent"]}가 있습니다. 조건을 결합하여 모든 조건을 요구합니다.

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    배열 멤버쉽을 테스트하려면 필드 레벨 연산자 딕셔너리를 사용합니다. "$array_contains"는 하나의 값 또는 목록의 모든 값과 일치합니다. "$array_contains_any"는 목록의 하나 이상의 값과 일치합니다. "$not"는 연산자 딕셔너리 또는 원시 정확한 일치 값을 포함하여 동일한 필드에서 다른 필드 레벨 표현식을 부정합니다. 누락된 필드를 포함하여 양수 표현식이 실패할 때 음수 표현식이 일치합니다. 음수 배열 멤버쉽도 배열이 아닌 필드와 일치합니다.

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool - 결과에 부적합한 상태의 레코드가 포함되는지 여부입니다. 이 인수를 생략하거나 포함하려면 True를 전달하십시오. False를 전달하여 제외합니다.
  • num_hops int – 각 직접 메모리 결과에서 따를 메모리 링크 모서리 수입니다. 0에서 5까지의 값이 지원됩니다. 직접 결과에 대해서만 생략합니다. 직접 메시지, 이미지 및 프로파일 결과는 유지되지만 그래프로 확장되지는 않습니다.
  • max_linked_results int – 각 직접 결과에 연결된 모든 홉에서 연결된 최대 메모리입니다. 기본값인 100를 생략합니다. 링크된 컨텍스트를 반환하지 않으려면 0를 전달합니다.
  • scope SearchScope – 사전 구축된 검색 범위(선택사항)입니다. scope 또는 명시적 식별자 및 정확한 일치 인수 중 하나만 제공하십시오.
• 반품: 관련성을 줄여 정렬된 검색 결과입니다.
• 반환 유형: list[SearchResult]
• 확장: ValueError – scope가 명시적 식별자 또는 정확한 일치 인수와 결합된 경우(max_results가 1보다 작거나 metadata_filter가 딕셔너리 또는 None가 아닌 경우)

노트

생략된 범위 필드는 이 스레드의 기본 검색 범위(정확한 사용자 및 에이전트 일치와 이 스레드의 현재 user_id, agent_id 및 thread_id)를 상속합니다. 기본 스레드 검색은 의도적으로 exact_thread_match=False를 벗어나 동일한 사용자/에이전트에 대해 다른 스레드에서 관련 레코드를 반환할 수 있습니다. 결과를 현재 스레드로 제한하려면 exact_thread_match=True를 전달합니다. 명시적 None 범위 값은 해결된 정확한 일치 규칙을 계속 따릅니다. exact_*_match=False는 해당 차원을 제약 없는 상태로 두고 exact_*_match=True는 저장된 None 값만 일치시킵니다.

명시적 max_results 값은 1 이상이어야 합니다. 인수를 생략하면 10의 기본값이 사용됩니다. 상한입니다. 필터가 너무 제한적이거나, 일치하는 레코드가 적거나, 구현별 검색 동작으로 인해 호출이 max_results개 미만의 결과를 반환할 수 있습니다.

method search_async(비동기)

조회와 관련된 레코드를 비동기적으로 검색합니다.

• 매개변수:
  • query str – 자연어 질의 문자열입니다.
  • user_id str | None – 선택적 사용자 범위 대체입니다. 생략된 값은 스레드의 기본 사용자 범위를 상속합니다.
  • agent_id str | None – 선택적 에이전트 범위 대체입니다. 생략된 값은 스레드의 기본 에이전트 범위를 상속합니다.
  • thread_id str | None – 선택적 스레드 범위 대체입니다. 생략된 값은 스레드의 현재 스레드 식별자를 상속합니다.
  • exact_user_match bool – 사용자 일치가 엄격해야 하는지 여부입니다.
  • exact_agent_match bool – 에이전트 일치가 엄격해야 하는지 여부입니다.
  • exact_thread_match bool – 스레드 일치가 엄격해야 하는지 여부입니다.
  • max_results int – 반환할 최대 결과 수(선택 사항)입니다. 제공된 경우 1 이상이어야 합니다. 이 인수를 생략하면 기본값인 10가 사용됩니다.
  • token_budget int – 최종 형식 지정된 결과의 예상 토큰 수에 대한 선택적 하드 제한입니다. 생략할 경우 확인된 검색 구성이 사용됩니다. 양수 값은 전체 결과를 순위 순서대로 유지하며 누적 예측은 예산에 맞습니다. 첫 번째 결과가 맞지 않으면 결과가 반환되지 않습니다. 양수가 아닌 값은 이 출력 한도를 사용 안함으로 설정합니다.
  • soft_token_budget int – 최종 형식 지정된 결과의 예상 토큰 수에 대한 선택적 대상입니다. 생략할 경우 확인된 검색 구성이 사용됩니다. 이 대상에 도달하거나 초과한 전체 결과는 보존됩니다. 양수가 아닌 값은 이 대상을 사용 안함으로 설정합니다. 출력에 절대 제한도 있어야 하는 경우 token_budget를 더 큰 값으로 설정합니다.
  • record_types list[str] – 포함할 레코드 유형(예: "memory", "message" 또는 "image")의 선택적 목록입니다.

  • metadata_filter dict[str, Any] | None –

    범위 및 레코드 유형 필터링 후 추가 필터로 사용되는 선택적 메타데이터 필터 매핑입니다. metadata_filter의 항목은 AND 의미와 결합됩니다. 값이 필드 레벨 연산자 딕셔너리가 아닌 항목은 정확한 일치 의미를 사용합니다. 즉, 요청된 키가 저장된 레코드 메타데이터에 있어야 합니다. 중첩된 딕셔너리는 중첩된 메타 데이터 객체를 재귀적으로 일치시킵니다. 스칼라 및 목록 값이 정확히 일치해야 합니다. 목록 순서 및 길이도 일치해야 합니다. 메타데이터 필터링 없이 검색하려면 이 인수를 생략하거나 None를 전달하십시오. 예를 들어 스칼라 필드의 경우 metadata_filter={"source": "chat"}, 중첩 필드의 경우 metadata_filter={"travel": {"need": "transit"}}, 정확한 목록 일치의 경우 metadata_filter={"tags": ["trip", "urgent"]}가 있습니다. 조건을 결합하여 모든 조건을 요구합니다.

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    배열 멤버쉽을 테스트하려면 필드 레벨 연산자 딕셔너리를 사용합니다. "$array_contains"는 하나의 값 또는 목록의 모든 값과 일치합니다. "$array_contains_any"는 목록의 하나 이상의 값과 일치합니다. "$not"는 연산자 딕셔너리 또는 원시 정확한 일치 값을 포함하여 동일한 필드에서 다른 필드 레벨 표현식을 부정합니다. 누락된 필드를 포함하여 양수 표현식이 실패할 때 음수 표현식이 일치합니다. 음수 배열 멤버쉽도 배열이 아닌 필드와 일치합니다.

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool - 결과에 부적합한 상태의 레코드가 포함되는지 여부입니다. 이 인수를 생략하거나 포함하려면 True를 전달하십시오. False를 전달하여 제외합니다.
  • num_hops int – 각 직접 메모리 결과에서 따를 메모리 링크 모서리 수입니다. 0에서 5까지의 값이 지원됩니다. 직접 결과에 대해서만 생략합니다. 직접 메시지, 이미지 및 프로파일 결과는 유지되지만 그래프로 확장되지는 않습니다.
  • max_linked_results int – 각 직접 결과에 연결된 모든 홉에서 연결된 최대 메모리입니다. 기본값인 100를 생략합니다. 링크된 컨텍스트를 반환하지 않으려면 0를 전달합니다.
  • scope SearchScope – 사전 구축된 검색 범위(선택사항)입니다. scope 또는 명시적 식별자 및 정확한 일치 인수 중 하나만 제공하십시오.
• 반품: 관련성을 줄여 정렬된 검색 결과입니다.
• 반환 유형: list[SearchResult]
• 확장: ValueError – scope가 명시적 식별자 또는 정확한 일치 인수와 결합된 경우(max_results가 1보다 작거나 metadata_filter가 딕셔너리 또는 None가 아닌 경우)

노트

생략된 범위 필드는 이 스레드의 기본 검색 범위(정확한 사용자 및 에이전트 일치와 이 스레드의 현재 user_id, agent_id 및 thread_id)를 상속합니다. 기본 스레드 검색은 의도적으로 exact_thread_match=False를 벗어나 동일한 사용자/에이전트에 대해 다른 스레드에서 관련 레코드를 반환할 수 있습니다. 결과를 현재 스레드로 제한하려면 exact_thread_match=True를 전달합니다. 명시적 None 범위 값은 해결된 정확한 일치 규칙을 계속 따릅니다. exact_*_match=False는 해당 차원을 제약 없는 상태로 두고 exact_*_match=True는 저장된 None 값만 일치시킵니다.

명시적 max_results 값은 1 이상이어야 합니다. 인수를 생략하면 10의 기본값이 사용됩니다. 상한입니다. 필터가 너무 제한적이거나, 일치하는 레코드가 적거나, 구현별 검색 동작으로 인해 호출이 max_results개 미만의 결과를 반환할 수 있습니다.

방법 update_image

이 스레드가 소유한 이미지를 업데이트합니다.

기존 바이트를 보존하려면 image를 생략합니다. image가 제공된 경우 mime_type를 제공해야 합니다. 기존 설명을 보존하려면 description를 생략합니다. None을 전달하여 구성된 LLM으로 새 설명을 생성합니다. 널이 아닌 설명이 직접 대체됩니다. 메시지에 첨부된 이미지의 만료는 update_message()를 통해 변경해야 합니다.

• 반환: 업데이트된 이미지 식별자입니다.
• 반환 유형: str
• Raises: ValueError – 메시지에 첨부된 이미지에 대한 만료 설정이 제공된 경우입니다.
• 매개변수:
  • image_id str
  • 이미지 bytes
  • 설명 str | None
  • mime_type ImageMimeType
  • 메타데이터 dict[str, Any] | None
  • 시간 기록 str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

method update_image_async(비동기)

이 스레드가 소유한 하나의 이미지를 비동기적으로 업데이트합니다.

기존 바이트를 보존하려면 image를 생략합니다. image가 제공된 경우 mime_type를 제공해야 합니다. 기존 설명을 보존하려면 description를 생략합니다. None을 전달하여 구성된 LLM으로 새 설명을 생성합니다. 널이 아닌 설명이 직접 대체됩니다. 메타데이터, 시간 기록 및 만료 설정은 제공될 때 업데이트됩니다. 메시지에 첨부된 이미지의 만료는 update_message_async()를 통해 변경해야 합니다.

• 반환: 업데이트된 이미지 식별자입니다.
• 반환 유형: str
• Raises: ValueError – 메시지에 첨부된 이미지에 대한 만료 설정이 제공된 경우입니다.
• 매개변수:
  • image_id str
  • 이미지 bytes
  • 설명 str | None
  • mime_type ImageMimeType
  • 메타데이터 dict[str, Any] | None
  • 시간 기록 str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

방법 update_memory

이 스레드가 소유한 메모리 유사 레코드를 업데이트합니다.

• 매개변수:
  • memory_id str – 메모리 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메모리 유사 레코드(memory, guideline, fact, preference)만 업데이트됩니다.
  • content str – 선택적 대체 컨텐츠입니다. 저장된 콘텐츠를 대체할 문자열을 제공합니다. 생략하면 저장된 내용이 보존됩니다. 현재 값을 유지하려면 content를 생략하고, 레코드를 제거하려면 delete_memory()를 사용합니다.
  • metadata dict[str, Any] | None – 선택적 대체 메타데이터 매핑입니다. 생략하면 저장된 메타데이터가 보존됩니다. 제공된 경우 저장된 메타데이터 객체를 대체합니다. 이 API는 메타데이터를 심층 병합하지 않습니다.
  • timestamp str | None – 이 메모리에 대한 선택적 새 시간 기록입니다. 메모리가 생성된 시기를 나타냅니다. 생략하면 저장된 시간 기록이 보존됩니다. 저장된 시간 기록을 지우고 저장소에서 레코드가 생성된 시간을 사용하려면 None을 전달합니다. ttl_anchor가 TimeToLiveAnchor.TIMESTAMP인 경우 교체 시간 기록은 ISO-8601 문자열이어야 합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • ttl_days int | None – 선택적 만료 새로 고침(일)입니다. ttl_anchor가 제공되지 않은 경우 현재 만료를 변경하지 않고 그대로 두려면 이 인수를 생략합니다. 보존 구성이 하나를 설정할 때 MemoryRetentionConfig.max_ttl_days를 사용하거나 그렇지 않을 때 만료를 지우려면 None를 전달합니다. MemoryRetentionConfig.max_ttl_days 이상의 값은 경고와 함께 해당 최대값으로 고정됩니다. 만료된 메모리는 이 스레드 API에 사용할 수 없으며 새로 고칠 수 없습니다.
  • ttl_anchor TimeToLiveAnchor – 만료 새로 고침에 대한 선택적 TTL 앵커입니다. 메모리 생성 시간에는 TimeToLiveAnchor.CREATED_AT를 사용하고, 동일한 업데이트에 제공된 교체 timestamp에는 TimeToLiveAnchor.TIMESTAMP를 사용하고, timestamp가 생략된 경우 저장된 이벤트 시간 기록을 사용합니다. ttl_days 없이 ttl_anchor를 제공하면 스키마 기본 TTL 기간이 사용됩니다. 새로 고치는 동안 ttl_anchor를 생략하면 스레드가 TimeToLiveAnchor.CREATED_AT를 사용합니다. 타임스탬프 앵커된 새로 고침에는 동일한 호출의 대체 ISO-8601 타임스탬프 또는 해당 형식의 기존 저장된 이벤트 타임스탬프가 필요합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • status RecordStatus – 이 메모리 유사 레코드에 대한 선택적 대체 수명 주기 상태입니다. 현재 상태를 유지하려면 생략합니다.
  • **kwargs(Any) – 예상치 않은 키워드 인수가 거부되었습니다.
• 반환: 업데이트된 메모리 유사 레코드의 식별자입니다.
• 반환 유형: str

method update_memory_async(비동기)

이 스레드가 소유한 메모리 유사 레코드를 비동기적으로 업데이트합니다.

• 매개변수:
  • memory_id str – 메모리 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메모리 유사 레코드(memory, guideline, fact, preference)만 업데이트됩니다.
  • content str – 선택적 대체 컨텐츠입니다. 저장된 콘텐츠를 대체할 문자열을 제공합니다. 생략하면 저장된 내용이 보존됩니다. 현재 값을 유지하려면 content를 생략하고, 레코드를 제거하려면 delete_memory()를 사용합니다.
  • metadata dict[str, Any] | None – 선택적 대체 메타데이터 매핑입니다. 생략하면 저장된 메타데이터가 보존됩니다. 제공된 경우 저장된 메타데이터 객체를 대체합니다. 이 API는 메타데이터를 심층 병합하지 않습니다.
  • timestamp str | None – 이 메모리에 대한 선택적 새 시간 기록입니다. 메모리가 생성된 시기를 나타냅니다. 생략하면 저장된 시간 기록이 보존됩니다. 저장된 시간 기록을 지우고 저장소에서 레코드가 생성된 시간을 사용하려면 None을 전달합니다. ttl_anchor가 TimeToLiveAnchor.TIMESTAMP인 경우 교체 시간 기록은 ISO-8601 문자열이어야 합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • ttl_days int | None – 선택적 만료 새로 고침(일)입니다. ttl_anchor가 제공되지 않은 경우 현재 만료를 변경하지 않고 그대로 두려면 이 인수를 생략합니다. 보존 구성이 하나를 설정할 때 MemoryRetentionConfig.max_ttl_days를 사용하거나 그렇지 않을 때 만료를 지우려면 None를 전달합니다. MemoryRetentionConfig.max_ttl_days 이상의 값은 경고와 함께 해당 최대값으로 고정됩니다. 만료된 메모리는 이 스레드 API에 사용할 수 없으며 새로 고칠 수 없습니다.
  • ttl_anchor TimeToLiveAnchor – 만료 새로 고침에 대한 선택적 TTL 앵커입니다. 메모리 생성 시간에는 TimeToLiveAnchor.CREATED_AT를 사용하고, 동일한 업데이트에 제공된 교체 timestamp에는 TimeToLiveAnchor.TIMESTAMP를 사용하고, timestamp가 생략된 경우 저장된 이벤트 시간 기록을 사용합니다. ttl_days 없이 ttl_anchor를 제공하면 스키마 기본 TTL 기간이 사용됩니다. 새로 고치는 동안 ttl_anchor를 생략하면 스레드가 TimeToLiveAnchor.CREATED_AT를 사용합니다. 타임스탬프 앵커된 새로 고침에는 동일한 호출의 대체 ISO-8601 타임스탬프 또는 해당 형식의 기존 저장된 이벤트 타임스탬프가 필요합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • status RecordStatus – 이 메모리 유사 레코드에 대한 선택적 대체 수명 주기 상태입니다. 현재 상태를 유지하려면 생략합니다.
  • **kwargs(Any) – 예상치 않은 키워드 인수가 거부되었습니다.
• 반환: 업데이트된 메모리 유사 레코드의 식별자입니다.
• 반환 유형: str

예제

import asyncio
memory_id = asyncio.run(thread.add_memory_async("Original memory"))
(
    asyncio.run(thread.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

방법 update_message

이 정확한 스레드가 소유한 원시 메시지 레코드를 업데이트합니다.

• 매개변수:
  • message_id str – 메시지 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메시지만 업데이트됩니다.
  • content str | list[Mapping[str, Any]] – 선택적 대체 메시지 컨텐츠입니다. 저장된 콘텐츠 또는 정렬된 텍스트 및 이미지 콘텐츠 부분을 바꿀 문자열을 제공합니다. 생략하면 저장된 내용이 보존됩니다. 빈 문자열을 사용하여 빈 텍스트 콘텐츠로 바꿉니다.
  • metadata dict[str, Any] | None – 선택적 대체 메타데이터 매핑입니다. 생략하면 저장된 메타데이터가 보존됩니다. 제공된 경우 저장된 메타데이터 객체를 대체합니다. 이 API는 메타데이터를 심층 병합하지 않습니다.
  • ttl_days int | None – 선택적 만료 새로 고침(일)입니다. ttl_anchor가 제공되지 않은 경우 현재 만료를 변경하지 않고 그대로 두려면 이 인수를 생략합니다. 보존 구성이 하나를 설정할 때 MemoryRetentionConfig.max_ttl_days를 사용하거나 그렇지 않을 때 만료를 지우려면 None를 전달합니다. MemoryRetentionConfig.max_ttl_days 이상의 값은 경고와 함께 해당 최대값으로 고정됩니다. 만료된 메시지는 이 스레드 API에서 사용할 수 없으며 새로 고칠 수 없습니다.
  • ttl_anchor TimeToLiveAnchor – 만료 새로 고침에 대한 선택적 TTL 앵커입니다. 메시지 생성 시간에는 TimeToLiveAnchor.CREATED_AT를 사용하고, 저장된 이벤트 시간 기록에는 TimeToLiveAnchor.TIMESTAMP를 사용합니다. ttl_days 없이 ttl_anchor를 제공하면 스키마 기본 TTL 기간이 사용됩니다. 새로 고치는 동안 ttl_anchor를 생략하면 스레드가 TimeToLiveAnchor.CREATED_AT를 사용합니다. 타임스탬프 앵커된 새로 고침에는 기존의 저장된 ISO-8601 메시지 타임스탬프가 필요합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • **kwargs(Any) – 예상치 않은 키워드 인수가 거부되었습니다.
• 반환: 업데이트된 메시지 레코드의 식별자입니다.
• 반환 유형: str

노트

생략된 필드는 저장된 레코드에서 보존됩니다. 저장된 역할 및 시간 기록은 변경되지 않습니다. 콘텐츠를 편집하면 원시 메시지 기록이 업데이트되고, 자동 추출이 사용으로 설정된 경우 SDK가 편집된 메시지 및 이전 기록에서 메모리를 다시 추출할 수 있습니다. INLINE 모드에서는 이 메소드가 반환되기 전에 추출이 완료됩니다. BACKGROUND 모드에서는 원시 메시지 업데이트가 성공하고 백그라운드 추출이 시도된 후 이 메소드가 반환됩니다. 이 후속 작업은 이후 add_messages() 호출에서 사용되는 일반 추출 빈도에 영향을 주지 않습니다. 기존 추출된 메모리는 그대로 유지되지만 편집된 콘텐츠에서 새로 추출된 메모리는 추가될 수 있습니다. 원시 메시지 업데이트 및 나중에 추출된 메모리 쓰기는 자동으로 수행되지 않으므로 백그라운드 작업이 대기열에 추가되지 않거나, 구성된 대기열 용량 대기가 시간 초과에 도달하거나, 나중에 추출 작업이 실패할 경우 추출된 메모리에 이전 메시지 내용이 계속 반영될 수 있습니다. 또한 소스 메시지의 TTL이 변경될 때 추출된 기존 메모리는 원래 만료 상태를 유지합니다.

예제

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

method update_message_async(비동기)

이 정확한 스레드가 소유한 원시 메시지 레코드를 비동기식으로 업데이트합니다.

• 매개변수:
  • message_id str – 메시지 식별자입니다. 저장된 thread_id가 이 스레드와 정확히 일치하는 메시지만 업데이트됩니다.
  • content str | list[Mapping[str, Any]] – 선택적 대체 메시지 컨텐츠입니다. 저장된 콘텐츠 또는 정렬된 텍스트 및 이미지 콘텐츠 부분을 바꿀 문자열을 제공합니다. 생략하면 저장된 내용이 보존됩니다. 빈 문자열을 사용하여 빈 텍스트 콘텐츠로 바꿉니다.
  • metadata dict[str, Any] | None – 선택적 대체 메타데이터 매핑입니다. 생략하면 저장된 메타데이터가 보존됩니다. 제공된 경우 저장된 메타데이터 객체를 대체합니다. 이 API는 메타데이터를 심층 병합하지 않습니다.
  • ttl_days int | None – 선택적 만료 새로 고침(일)입니다. ttl_anchor가 제공되지 않은 경우 현재 만료를 변경하지 않고 그대로 두려면 이 인수를 생략합니다. 보존 구성이 하나를 설정할 때 MemoryRetentionConfig.max_ttl_days를 사용하거나 그렇지 않을 때 만료를 지우려면 None를 전달합니다. MemoryRetentionConfig.max_ttl_days 이상의 값은 경고와 함께 해당 최대값으로 고정됩니다. 만료된 메시지는 이 스레드 API에서 사용할 수 없으며 새로 고칠 수 없습니다.
  • ttl_anchor TimeToLiveAnchor – 만료 새로 고침에 대한 선택적 TTL 앵커입니다. 메시지 생성 시간에는 TimeToLiveAnchor.CREATED_AT를 사용하고, 저장된 이벤트 시간 기록에는 TimeToLiveAnchor.TIMESTAMP를 사용합니다. ttl_days 없이 ttl_anchor를 제공하면 스키마 기본 TTL 기간이 사용됩니다. 타임스탬프 앵커된 새로 고침에는 기존의 저장된 ISO-8601 메시지 타임스탬프가 필요합니다. 표준 시간대가 없는 ISO-8601 시간 기록은 UTC로 처리됩니다.
  • **kwargs(Any) – 예상치 않은 키워드 인수가 거부되었습니다.
• 반환: 업데이트된 메시지 레코드의 식별자입니다.
• 반환 유형: str

노트

생략된 필드는 저장된 레코드에서 보존됩니다. 저장된 역할 및 시간 기록은 변경되지 않습니다. 콘텐츠를 편집하면 원시 메시지 기록이 업데이트되고, 자동 추출이 사용으로 설정된 경우 SDK가 편집된 메시지 및 이전 기록에서 메모리를 다시 추출할 수 있습니다. INLINE 모드에서는 이 메소드가 반환되기 전에 추출이 완료됩니다. BACKGROUND 모드에서는 원시 메시지 업데이트가 성공하고 백그라운드 추출이 시도된 후 이 메소드가 반환됩니다. 이 후속 작업은 이후 add_messages() 호출에서 사용되는 일반 추출 빈도에 영향을 주지 않습니다. 기존 추출된 메모리는 그대로 유지되지만 편집된 콘텐츠에서 새로 추출된 메모리는 추가될 수 있습니다. 원시 메시지 업데이트 및 나중에 추출된 메모리 쓰기는 자동으로 수행되지 않으므로 백그라운드 작업이 대기열에 추가되지 않거나, 구성된 대기열 용량 대기가 시간 초과에 도달하거나, 나중에 추출 작업이 실패할 경우 추출된 메모리에 이전 메시지 내용이 계속 반영될 수 있습니다. 또한 소스 메시지의 TTL이 변경될 때 추출된 기존 메모리는 원래 만료 상태를 유지합니다.

예제

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Draft message"}]
))
(
    asyncio.run(thread.update_message_async(
        message_ids[0], content="Edited message"
    ))
    == message_ids[0]
)
True

방법 update_record_link

이 스레드가 끝점을 소유하는 관계를 업데이트합니다.

생략된 값은 보존됩니다. relation_type가 내장 메모리 관계 유형으로 변경되면 고정 역방향 레이블이 opposite_relation_type를 대체합니다.

• 매개변수:
  • relation_id str – 스레드 소유 관계의 식별자입니다.
  • relation_type str – 선택적 대체 소스-대상 레이블입니다.
  • opposite_relation_type str – 선택적 대체 역방향 레이블입니다. 저장된 레이블을 유지하려면 생략합니다.
  • timestamp str | None – 선택적 대체 시간 기록입니다. 지우려면 None를 전달합니다.
  • metadata dict[str, Any] | None – 선택적 대체 메타데이터입니다. 저장된 객체를 대체합니다.
• 반환: 업데이트된 관계 수(0 또는 1)입니다.
• 반품 유형: int

예제

thread.update_record_link("relation-id", relation_type="supports")
1

method update_record_link_async(비동기)

이 스레드에 속한 끝점이 있는 관계를 비동기적으로 업데이트합니다.

• 매개변수:
  • relation_id str
  • relation_type str
  • opposite_relation_type str
  • 시간 기록 str | None
  • 메타데이터 dict[str, Any] | None
• 반품 유형: int

방법 wait_for_memory_extraction

이 스레드에 대한 이전 백그라운드 메모리 추출을 기다립니다.

이 메소드는 동일한 에이전트 메모리 구성 요소를 통해 이 스레드에서 이전 add_messages(), add_messages_async(), update_message() 또는 update_message_async() 호출에 의해 시작된 백그라운드 추출을 기다립니다. 이러한 호출 중 하나가 이미 종료된 경우 이 메소드는 대기 전에 시작하는 추출을 포함합니다.

이 메소드는 이 대기가 시작된 후, 다른 에이전트 메모리 구성 요소에 의해 추출이 시작되거나 다른 프로세스에서 추출이 실행될 때까지 기다리지 않습니다. 추출 실패는 이 대기에 대해 완료된 것으로 계산됩니다.

• 매개변수: timeout float | None – 선택적 최대 대기 시간(초)입니다. 기본값은 300입니다. 이 스레드에 대한 보류 중인 추출이 완료될 때까지 기다리려면 None를 전달합니다.
• 발생: TimeoutError – 이전 백그라운드 추출이 완료되기 전에 시간 초과가 만료될 때 발생합니다.
• 반환 유형: 없음

예제

thread.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async(비동기)

이전 백그라운드 메모리 추출을 비동기적으로 기다립니다.

이 메소드는 wait_for_memory_extraction()와 동일한 동작을 따릅니다.

• 매개변수: timeout float | None – 선택적 최대 대기 시간(초)입니다. 기본값은 300입니다. None를 전달하여 무기한 기다립니다.
• 발생: TimeoutError – 이전 백그라운드 추출이 완료되기 전에 시간 초과가 만료될 때 발생합니다.
• 반환 유형: 없음

예제

import asyncio
asyncio.run(thread.wait_for_memory_extraction_async(timeout=10))

주: delete_message()는 원시 메시지 행만 삭제합니다. 파생 된 기억은 여전히 검색 가능하거나 컨텍스트 카드에 나타날 수 있습니다. OracleAgentMemory.delete_thread()를 사용하여 연관된 메시지 및 메모리와 함께 스레드를 삭제합니다. 스레드 핸들을 통한 메시지 및 메모리 삭제는 연결된 클라이언트가 해당 스레드에 대해 이미 수락한 이전 백그라운드 추출을 기다립니다. 이는 다른 클라이언트 Instance, 프로세스 또는 대기 시작 후 수락된 작업에 대한 Global 동시성 장벽이 아닙니다.

메시지 및 메시지 내용

클래스 oracleagentmemory.apis.message.Message

기준: object

스레드 및 LLM 어댑터가 공유하는 인메모리 메시지입니다.

• 매개변수:
  • role str – 메시지 역할입니다. 스레드 메시지에 대해 사용자정의 역할 이름이 허용됩니다.
  • content str | collections.abc.Sequence[oracleagentmemory.apis.message.MessageContent] – TextContent 및 ImageContent 부분의 메시지 텍스트 또는 정렬된 시퀀스입니다. 콘텐츠 시퀀스는 비워 둘 수 없으며 변경할 수 없는 튜플로 저장됩니다.
  • timestamp str | None – 메시지와 연관된 선택적 시간 기록입니다.
  • metadata dict[str, Any] | None – 메시지와 연관된 선택적 JSON 호환 메타데이터입니다.
  • id str | None – 선택적 안정적 메시지 식별자입니다. 메시지가 식별자 없이 추가될 때 저장소가 하나를 생성합니다.

클래스 oracleagentmemory.apis.message.MessageContent

기준: ABC

구조화된 메시지 콘텐츠에 대한 기본 클래스입니다.

• 매개변수:
  • id str – 이 컨텐츠 부분에 대한 안정적인 식별자입니다. 생략 시 자동으로 생성됩니다.
  • timestamp str | None – 이 콘텐츠 부분과 연관된 선택적 시간 기록입니다.

클래스 oracleagentmemory.apis.message.TextContent

기준: MessageContent

멀티모달 메시지의 텍스트 부분입니다.

• 매개변수:
  • text str – 이 콘텐츠 부분이 전달하는 텍스트입니다.
  • id str – MessageContent에서 상속된 안정적인 식별자입니다. 생략 시 자동으로 생성됩니다.
  • timestamp str | None – MessageContent에서 상속된 선택적 시간 기록입니다.

클래스 oracleagentmemory.apis.message.ImageContent

기준: MessageContent

멀티모달 메시지의 이미지 부분입니다.

• 매개변수:
  • bytes bytes | None – 사용 가능한 경우 이미지 데이터입니다. None는 이미지 바이트를 로드하지 않고 메시지에 이미지 메타데이터가 포함된 경우 허용됩니다.
  • mime_type oracleagentmemory.apis.message.ImageMimeType – 이미지 MIME 유형입니다.
  • description str | None – 이미지를 설명하는 선택적 텍스트입니다. None의 경우 상위 레벨 이미지 및 메시지 API가 구성된 LLM을 사용하여 설명을 생성할 수 있습니다.
  • id str – MessageContent에서 상속된 안정적인 식별자입니다. 생략 시 자동으로 생성됩니다.
  • timestamp str | None – MessageContent에서 상속된 선택적 시간 기록입니다.

클래스 oracleagentmemory.apis.message.ImageMimeType

기준: str, Enum

이미지 콘텐츠에 대해 지원되는 MIME 유형입니다.

PNG와 WebP 애니메이션은 지원되지 않습니다.

JPEG = 'image/JPEG'

PNG = 'image/PNG'

WEBP = 'image/WEBP'

컨텍스트 카드

클래스 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'