보안 고려사항

범위: 이 문서에서는 에이전트 메모리 Python SDK와 관련된 보안 고려 사항을 다룹니다. SDK의 활성 메모리 기능 또는 저장소 계층만 사용하는 애플리케이션에 적용됩니다.

중요한 이유: 에이전트 메모리는 Oracle AI Database에서 스레드 콘텐츠 및 메모리 레코드를 보관할 수 있으며, LLM 지원 기능이 사용으로 설정된 경우 요약, 메모리 추출 또는 임베딩을 위해 구성된 모델 엔드포인트로 콘텐츠를 전송할 수 있습니다. 따라서 보안 배포는 애플리케이션 데이터, 검색 범위, 데이터베이스 액세스, 외부 모델 엔드포인트 및 보존 정책의 신중한 처리에 따라 달라집니다.

LLM 지원 메모리 처리에 대한 고려 사항

에이전트 메모리는 스레드 요약 및 자동 메모리 추출과 같은 활성 메모리 기능을 지원합니다. 이러한 기능이 사용으로 설정되면 SDK는 최근 메시지, 스레드 요약, 검색된 메모리를 전송하거나 구성된 LLM 또는 포함 끝점으로 텍스트를 검색할 수 있습니다.

주: 구성된 모델 끝점 및 배치 정책에 적합한 에이전트 메모리로만 콘텐츠를 전송합니다. 메모리 파이프라인에 들어가기 전에 콘텐츠를 검증하고 최소화하며 메시지나 메모리에 비밀, 자격 증명 또는 불필요한 민감한 데이터를 포함하지 마십시오. 추출된 메모리, 요약, 컨텍스트 카드 및 기타 모델 파생 텍스트를 통합 응용 프로그램에서 안전하게 검토하고 처리해야 하는 신뢰할 수 없는 출력으로 처리합니다.

active-memory 기능을 사용할 때는 다음 권장 사항을 따르십시오.

• 애플리케이션 데이터 검증 및 최소화: 애플리케이션이 SDK로 전송하는 메시지, 메타데이터 및 ID를 검토합니다. 메모리 워크플로우에 필요한 것보다 많은 데이터를 전달하지 마십시오.

• 신뢰할 수 있는 모델 엔드포인트 사용: 전송 보안, 데이터 레지던시, 보존, 운영 모니터링 관련 요구 사항을 충족하는 LLM 및 임베딩 엔드포인트를 구성할 수 있습니다.

• 생성된 메모리를 응용 프로그램 데이터 및 신뢰할 수 없는 출력으로 처리: 추출된 메모리, 요약 및 컨텍스트 카드는 파생 출력입니다. 특히 권한이 있는 작업, 외부 도구 호출 또는 고객이 볼 수 있는 의사 결정에 영향을 주기 전에 애플리케이션에서 이를 사용하는 방법을 검토합니다.

• 영구적 프롬프트 삽입 계정: 메모리에 저장된 호출자가 제공, 검색 또는 모델에서 파생된 텍스트를 나중에 요약, 추출, 컨텍스트 카드 또는 에이전트 프롬프트로 재생할 수 있습니다. 프롬프트 구분자, 이스케이프 및 추출 지침은 모델 입력을 구성하는 데 도움이 될 수 있지만 보안 경계는 아닙니다. 자동 주기에서 파생된 메모리는 응용 프로그램이 검토할 때까지 신뢰할 수 없는 메모리로 처리합니다.

• 대상에 대해 파생된 텍스트 초기화 또는 이스케이프: 모델에서 파생된 콘텐츠를 HTML, 마크다운, 템플리트, 로그 또는 기타 출력 표면으로 렌더링하기 전에 컨텍스트에 적합한 이스케이프 또는 sanitization을 적용합니다. 다운스트림 프롬프트, 도구 입력, 명령 또는 기타 인터프리터와 유사한 컨텍스트에서 파생된 텍스트를 재사용하기 전에 동일한 주의를 기울이십시오.

• 적합한 작동 모드 선택: 애플리케이션이 내구성이 뛰어난 메모리를 완벽하게 제어해야 하는 경우 자동 추출을 수행하지 않아야 하는 워크플로우에 명시적 메모리 쓰기, 저장소 전용 통합 또는 extract_memories=False를 사용하는 것이 좋습니다.

지속성 및 데이터 최소화에 대한 고려 사항

에이전트 메모리는 DB 지원 저장소가 사용될 때 Oracle AI Database에 메시지, 메모리, 메타데이터 및 임베딩을 지속하도록 설계되었습니다. 이를 통해 내구성이 뛰어난 검색 및 세션 간 메모리를 사용할 수 있지만, 애플리케이션은 보유하기에 적합한 데이터를 계획해야 합니다.

다음 지침은 안전한 데이터 처리 관행에 맞춰 배포를 유지하는 데 도움이 됩니다.

• 저장소 전용으로 사용하는 경우 필요한 항목만 유지: 비즈니스에 적합한 유용한 콘텐츠만 메모리 저장소에 기록하도록 응용 프로그램을 설계합니다.

• 활성 메모리 기능이 사용으로 설정된 경우 파생된 레코드 계획: 메시지 및 메타데이터와 같은 호출자가 제공한 콘텐츠 외에도 워크플로우가 추출된 메모리, 요약 또는 임베딩을 지속할 수도 있습니다.

• 먼저 보존 및 삭제 정책 정의: 애플리케이션이 삭제 또는 보존 약정을 제공하는 경우 워크플로우에서 생성된 원시 메시지, 추출된 메모리, 메타데이터 및 기타 관련 레코드를 포함하는지 확인합니다.

• 진실한 소스로서의 메모리에 의존하지 않기: 저장된 메모리는 컨텍스트 및 검색을 개선하기 위한 것입니다. 애플리케이션은 중요한 의사 결정을 위해 신뢰할 수 있는 시스템에 계속 의존해야 합니다.

검색 범위 및 액세스 제어 관련 고려 사항

에이전트 메모리는 호출자가 제공한 user_id, agent_id 및 thread_id 값을 사용하여 검색 범위를 지정합니다. 이는 강력한 필터링 모델이지만 검색된 콘텐츠가 사용되거나 표시되는 방법을 결정할 때 애플리케이션이 사용하는 유일한 제어는 아니어야 합니다.

기본적으로 스레드 범위 검색은 user_id 및 agent_id에 대한 정확한 일치와 thread_id에 대한 광범위한 일치를 사용하므로 관련 결과가 동일한 사용자 에이전트 쌍에 대한 과거 스레드로 확장될 수 있습니다. 최상위 레벨 OracleAgentMemory.search() 및 search_async() 호출에는 구체적인 user_id 및 정확한 사용자 일치도 필요합니다. 생략된 사용자 범위 user_id=None 및 exact_user_match=False를 거부하므로 공용 클라이언트 API가 실수로 여러 사용자를 검색하지 않습니다.

검색을 설계할 때 다음 연습을 사용합니다.

• 애플리케이션 규칙을 메모리 범위에 매핑: 애플리케이션이 SDK로 전달하는 범위가 테넌트, 사용자 및 데이터 공유 규칙과 일치하는지 확인합니다.

• 모든 클라이언트 검색에서 명시적 사용자 범위 전달: 인증된 요청 컨텍스트에서 user_id를 파생시키고 각 최상위 레벨 OracleAgentMemory.search() 또는 search_async() 호출에 제공합니다.

• 사용 사례를 충족하는 가장 좁은 범위 선호: 보다 민감한 데이터를 처리하는 워크플로우에 대해 정확히 일치하는 필터를 사용합니다.

• 스레드 간 검색을 의도적으로 검토: 광범위한 검색을 통해 세션 간 연속성을 개선할 수 있지만, 애플리케이션은 해당 접근 방식이 적합한 경우에만 사용으로 설정해야 합니다.

• 최종 결정이 아닌 검색된 콘텐츠로 검색 결과 처리: 반환된 메모리는 관련이 있을 수 있지만 애플리케이션은 표시 또는 작업 방법을 결정할 책임이 있습니다.

• 통합 경계에서 검색된 텍스트를 신뢰할 수 없는 콘텐츠로 취급: 검색된 레코드에는 호출자가 제공한 텍스트 또는 모델 파생 텍스트가 포함될 수 있습니다. 해당 컨텐트를 표시, 변환 또는 다운스트림 시스템으로 전달하기 전에 대상에 적합한 것으로 검증, 삭제 또는 이스케이프합니다.

애플리케이션 통합 및 호출자 신뢰 관련 고려 사항

에이전트 메모리는 최종 사용자가 직접 호출하지 않고 통합 애플리케이션 또는 다른 신뢰할 수 있는 백엔드 코드로 호출됩니다. 최종 사용자 대면 보안 경계가 아니며 최종 사용자 인증 또는 권한 부여를 자체적으로 수행하지 않습니다. 패키지는 호출자를 신뢰하여 각 작업에 대해 올바른 user_id, agent_id, thread_id 및 검색 범위를 제공합니다.

주: 통합 애플리케이션은 일반 사용자를 인증하고, 액세스 권한을 부여하고, 에이전트 메모리 API를 호출하기 전에 올바른 user_id 및 범위를 파생합니다. 호출자가 제공한 user_id는 ID 증명이 아닌 범위 지정 값입니다.

SDK를 에이전트 응용 프로그램에 통합하는 경우 다음 연습을 사용합니다.

• ''user_id''를 보안에 민감한 응용 프로그램 입력으로 처리: 일반 사용자가 임의의 값을 선택할 수 있도록 하는 대신 인증된 응용 프로그램 컨텍스트에서 user_id를 파생시킵니다.

• 모든 메모리 호출 전에 애플리케이션 권한 부여 적용: 통합 애플리케이션은 현재 요청에 적합한 user_id, agent_id, thread_id 및 검색 범위 값을 결정하고 의도한 테넌트 및 사용자 경계 내에서 읽기 및 쓰기를 유지해야 합니다.

• 최종 사용자에게 원시 메모리 API 노출 안함: add_memory 또는 검색 도우미와 같은 패키지 API는 호출자를 검증하고, 정책을 적용하고, 기록하거나 반환할 수 있는 데이터를 제어하는 애플리케이션 논리에 래핑되어야 합니다.

• 사용자 ID 검색 및 열거 권한 유지: 패키지가 user_id 값을 나열하거나 열거하기 위한 도우미를 추가하는 경우 이러한 도우미를 관리 기능으로만 취급하고 통합 애플리케이션을 통해 일반 사용자에게 노출하지 않습니다.

• 범위 재정의 주의 깊게 검토: 스레드 범위를 확장하고, 정확한 일치를 사용 안함으로 설정하거나, 하위 레벨 저장소 API로 삭제하는 모든 워크플로우는 신뢰할 수 있는 구성요소로 제한하고, 사용자 간 또는 테넌트 간 효과를 검토해야 합니다.

데이터베이스 액세스, 스키마 관리 및 암호 관련 고려 사항

에이전트 메모리는 호출자가 제공한 Oracle AI Database 연결 또는 풀을 사용합니다. 패키지는 데이터베이스 인증서 자체를 생성하거나 관리하지 않습니다. 또한 호출자 대신 데이터베이스 네트워크 암호화를 생성, 협상 또는 업그레이드하지 않습니다.

참고:

• 프로덕션 배치의 경우 에이전트 메모리에 전달하기 전에 암호화된 전송이 사용으로 설정된 Oracle AI Database 접속 또는 풀을 생성하십시오. 신뢰할 수 없는 네트워크, 공유 네트워크 또는 외부 네트워크에서 일반 텍스트 데이터베이스 연결을 사용하지 마십시오. python-oracledb를 사용할 때는 공식 섹션인 Securely Encrypting Network Traffic to Oracle AI Database를 따르고 연결 또는 풀 생성의 일부로 TLS 또는 승인된 암호화된 다른 전송을 구성합니다.

• 애플리케이션 코드, 체크인된 구성 또는 익스포트된 아티팩트에 직접 API 키, 비밀번호 또는 기타 암호를 포함하지 마십시오. 항상 보안 주입(Injection) 방식을 사용하고 자격 증명 액세스를 위한 최소 권한 원칙을 따릅니다.

권장되는 배치 방식은 다음과 같습니다.

• 필요한 권한만 가진 데이터베이스 사용자 사용: 선택한 배치 모델 및 스키마 정책에 필요한 항목만 부여합니다.

• 암호화된 데이터베이스 접속 및 풀 생성: 에이전트 메모리는 호출자가 제공한 그대로 접속 또는 풀을 사용합니다. python-oracledb의 경우 protocol=\"tcps\" 또는 동등한 TCPS DSN과 같은 TLS 사용 연결을 선호하고, 필요한 전자 지갑 또는 CA 자료를 구성하고, 서버 인증서 검증을 사용으로 유지하십시오.

• DDL 변경이 명시적으로 필요하지 않은 경우 기본 스키마 정책 유지: SchemaPolicy.REQUIRE_EXISTING는 기본값이며 표준 응용 프로그램을 시작하는 동안 스키마 객체를 생성, 수정 또는 삭제하지 않습니다.

• 파괴적 설정 모드 제한: SchemaPolicy.RECREATE은 설정, 테스트 또는 관리 워크플로우를 위한 것이며 표준 운용 경로에서 사용해서는 안됩니다.

• 애플리케이션 코드의 동적 SQL 어셈블리가 아닌 패키지 관리 SQL 경로에 의존: 관리형 DB 경로에서 레코드 값 및 검색 필터는 바인드 변수와 함께 전송되고, 관리형 객체 이름은 검증된 접두어에서 파생됩니다.

• 접속 및 제공자 자격 증명 보호: 데이터베이스, LLM을 저장하고, OCI Vault와 같은 암호 관리자에 자격 증명을 내장하고, 정기적으로 교체합니다.

• Thin 모드와 Thick 모드 모두에서 검증된 TLS 선호: 공식 python-oracledb 문서에서는 Thin 모드와 Thick 모드가 모두 TLS를 지원하며 Thick 모드는 승인된 표준인 Oracle Native Network Encryption을 사용할 수도 있습니다.

• 데이터베이스에 대한 보안 전송 사용: 데이터베이스 네트워크 보안, TLS 구성 및 인증 방법은 호출자가 제공한 연결에 따라 결정되며 조직의 표준을 따라야 합니다.

네트워크 통신 및 외부 끝점에 대한 고려 사항

에이전트 메모리는 배치가 원격 LLM 또는 임베딩 제공자를 구성할 때 외부 서비스와 통신할 수 있습니다. SDK는 구성된 클라이언트 경로를 통해 프롬프트 및 요청 매개변수를 전달하지만 주변 애플리케이션 및 배치는 이러한 연결 보안을 유지합니다.

다음을 권장합니다.

• 모델 끝점에 HTTPS를 사용하고 사용 가능한 경우 프라이빗 또는 제한된 네트워크 경로를 선호합니다.

• 예상치 않은 대상, 비정상적인 요청 볼륨 또는 비정상적인 토큰 소비에 대한 아웃바운드 트래픽 및 제공자 사용을 모니터링합니다.

• 규제 또는 민감한 워크플로우에서 활성 메모리 기능을 사용으로 설정하기 전에 규정 준수 및 레지던시 요구 사항에 맞는 공급자를 선택하십시오.

리소스 소진 벡터에 대한 고려 사항

메모리 워크플로는 시간 경과에 따라 데이터베이스 사용량, 임베딩 트래픽, LLM 토큰 사용량을 늘릴 수 있습니다. 이는 악의적인 과도한 사용과 지나치게 큰 메시지 또는 지나치게 광범위한 검색 패턴과 같은 무고한 구현 실수에 모두 해당됩니다.

생산 경화의 일부로 다음 컨트롤을 사용합니다.

• 실제 프롬프트 및 메시지 한도 설정: 워크로드 및 제공자 한도에 맞게 max_message_token_length 및 memory_extraction_token_limit과 같은 값을 구성합니다.

• 제한된 검색 크기: 애플리케이션 검색에 적합한 max_results 값 및 레코드 유형 필터를 사용합니다.

• SDK 외부에서 인프라 제한 적용: 주변 배포에서 데이터베이스 할당량, 연결 제한, 네트워크 제어, 엔드포인트 시간 초과 및 속도 제한을 사용합니다.

• 시간 경과에 따른 증가 모니터링: 저장된 메시지 양, 내구성 있는 메모리 증가, 공급자 사용량, 쿼리 대기 시간을 추적하여 안정성에 영향을 미치기 전에 보존 또는 튜닝 변경을 수행할 수 있습니다.