본문으로 건너뛰기

인터페이스: Scope

정의 위치: packages/ai/src/scope.ts:23

대화별 데이터를 영속화하거나 회상하는 TanStack AI 하위 시스템의 공유 ID/격리 스코프입니다 — @tanstack/ai-persistence(threads, runs, interrupts에 대한 키 기반 CRUD)와 @tanstack/ai-memory(순위 기반 회상/저장)에 사용됩니다.

두 하위 시스템은 모두 "이 데이터는 누구의 것인가?"라는 동일한 근본 질문에 답하므로, 각자 고유한 용어를 만드는 대신 여기서 정의한 하나의 ID 용어를 공유합니다. threadId는 코드베이스 전체에서 사용하는 단일 대화 키입니다(ChatMiddlewareContext.threadId이며 conversationId는 이를 대신해 지원 중단 예정입니다). 하위 시스템은 같은 개념에 대해 두 번째 이름(sessionId, conversationId, …)을 도입해서는 안 됩니다.

보안​

Scope는 격리 경계입니다. 모든 필드는 신뢰할 수 있고 검증된 세션 상태에서 서버 측으로 도출해야 하며 — 절대로 클라이언트 입력에서 도출해서는 안 됩니다. 특히 threadId는 요청에서 클라이언트가 제공한 값으로 확인되므로, 사용자 소유 데이터를 읽거나 쓰는 하위 시스템(메모리, 사용자별 메타데이터)은 서버가 신뢰하는 userId/tenantId와 함께 사용해야 하며, 클라이언트의 threadId만으로 충분히 격리되었다고 취급해서는 안 됩니다. thread id는 추측할 수 있으므로, 그것만으로는 한 호출자가 다른 호출자의 데이터를 읽을 수 있습니다.

속성​

namespace?​

optional namespace?: string;

정의 위치: packages/ai/src/scope.ts:46

tenant/user 내의 논리적 파티션입니다(예: 서로 다른 메모리 뱅크 또는 영속성 네임스페이스 분리). 예약된 필드이며 아직 이를 키로 사용하는 하위 시스템은 없습니다. 이를 이해하지 못하는 어댑터는 오류를 발생시키지 말고 무시해야 합니다.

tenantId?​

optional tenantId?: string;

정의 위치: packages/ai/src/scope.ts:40

멀티테넌트 배포에서 tenant/조직의 경계입니다. 지정된 경우 모든 읽기와 쓰기는 이 범위로 제한되어야 합니다.

threadId​

threadId: string;

정의 위치: packages/ai/src/scope.ts:29

이 데이터가 속한 대화입니다. 필수이며, 두 하위 시스템이 이미 중심으로 삼는 최소 격리 키입니다. ChatMiddlewareContext.threadId와 같은 개념입니다.

userId?​

optional userId?: string;

정의 위치: packages/ai/src/scope.ts:35

스레드 간 회상과 사용자별 격리를 위한 영속적인 최종 사용자 ID입니다. 선택 사항이지만 모든 멀티유저 배포에서 실제로는 필수입니다. threadId만으로는 권한 부여 경계가 되지 않습니다(위의 보안 참조).