보안 고려사항

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

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

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

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

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

경고: 모델에서 파생된 텍스트는 영구 메모리 상태가 될 수 있습니다. 자동 추출, 요약 또는 컨텍스트 카드 기능이 사용으로 설정된 경우 요약, 추출된 메모리 또는 검색된 레코드를 SDK에서 메모리 추출, 요약, 컨텍스트 카드 또는 에이전트 프롬프트와 같은 이후 프롬프트에 삽입하여 애플리케이션이 특정 중간 값을 검토할 수 있습니다. 이를 일반적인 신뢰할 수 없는 LLM 데이터 플로우로 취급합니다. 애플리케이션이 소비하는 출력을 검토 및 검증하고, 메모리 파생 콘텐츠가 권한 있는 작업을 승인하거나 정책을 우회하지 않도록 합니다.

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

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

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

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

• 영구적 프롬프트 삽입 계정: 메모리에 저장된 호출자가 제공, 검색 또는 모델에서 파생된 텍스트를 나중에 요약, 추출, 컨텍스트 카드 또는 에이전트 프롬프트로 재생할 수 있습니다. 프롬프트 구분자, 이스케이프 및 추출 지침은 모델 입력을 구성하는 데 도움이 될 수 있지만 보안 경계는 아닙니다. 추출된 메모리, 요약, 컨텍스트 카드 및 기타 지속되거나 즉시 바인딩된 중간 텍스트를 검토한 후 해당 텍스트를 사용합니다. 모델 파생 텍스트가 이후 추출 또는 컨텍스트 구성에 영향을 미칠 수 있기 전에 워크플로우에 검토가 필요한 경우 자동 추출을 사용 안함으로 설정하고 명시적 메모리 쓰기 또는 다른 응용 프로그램 제어 검토 게이트를 사용합니다.

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

• 적합한 작동 모드 선택: 모델에서 파생된 텍스트가 나중에 추출 또는 컨텍스트 구성에 영향을 줄 수 있기 전에 응용 프로그램에 검토가 필요한 경우 자동 추출을 수행하지 않아야 하는 워크플로우에 명시적 메모리 쓰기, 저장소 전용 통합 또는 extract_memories=False를 사용하는 것이 좋습니다.

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

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

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

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

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

• 쓰기 가능 메모리 경로를 신뢰할 수 있는 것으로 처리: 메시지, 요약, 메모리, 메타데이터, 임베딩 또는 스레드 런타임 상태를 기록할 수 있는 데이터베이스 인증서 및 백엔드 코드 경로는 이후 프롬프트 및 검색 결과에 영향을 줄 수 있습니다. Active-memory 기능은 의도적으로 모델 파생 상태를 유지합니다. 워크플로우에 적합하지 않은 경우 자동 추출을 사용 안함으로 설정하거나 더 좁은 애플리케이션 제어로 저장소 전용/수동 쓰기 통합을 사용하십시오.

• 보존 작업에 적합한 삭제 범위 선택: delete_message()는 원시 메시지 레코드만 제거합니다. 추출된 메모리는 현재 메시지별 출처를 유지하지 않으므로 해당 메시지에서 생성된 파생된 메모리 또는 기타 다운스트림 스레드 범위의 아티팩트를 검색 가능한 상태로 유지할 수 있습니다. 연관된 메모리 및 관리되는 벡터/정크 데이터도 제거하는 스레드 범위의 정리가 필요한 경우 OracleAgentMemory.delete_thread()를 사용합니다.

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

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

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

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

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

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

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

• 모든 클라이언트 검색에서 명시적 사용자 범위 전달: 요청 JSON 또는 기타 호출자 제어 입력이 아닌 인증된 요청 컨텍스트에서 user_id을 파생시키고 각 최상위 레벨 OracleAgentMemory.search() 또는 search_async() 호출에 제공합니다. 범위가 지정되지 않은 레코드로 의도적으로 제한된 워크플로우의 경우에만 user_id=None을 사용합니다.

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

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

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

• 통합 경계에서 검색된 텍스트를 안전하게 처리: 검색된 레코드에는 호출자가 제공한 텍스트 또는 모델 파생 텍스트가 포함될 수 있습니다. 검색된 메모리 또는 기타 반환된 텍스트가 HTML, 마크다운, 템플리트, 로그 또는 기타 출력 서피스로 렌더링되는 경우 컨텍스트에 적합한 이스케이프 또는 sanitization을 표시, 변환, 로깅 또는 다운스트림 시스템으로 전달하기 전에 적용합니다.

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

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

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

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

• user_id를 보안에 민감한 애플리케이션 입력으로 처리: 통합 애플리케이션이 인증된 컨텍스트 대신 요청 JSON 또는 기타 호출자 제어 입력에서 user_id를 파생하는 경우 사용자 간 메모리 액세스를 허용할 수 있습니다. 일반 유저가 임의의 값을 선택할 수 있도록 하는 대신 인증된 응용 프로그램 컨텍스트에서 user_id을 파생시킵니다.

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

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

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

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

로깅 및 진단 관련 고려 사항

에이전트 메모리는 표준 Python 로깅을 사용하며 통합 애플리케이션에 대한 애플리케이션 로그 처리기 또는 로그 레벨을 구성하지 않습니다. 통합 애플리케이션이 SDK에 대해 DEBUG 로깅을 사용으로 설정하는 경우 디버그 로그에 추가 문제 해결 세부정보가 포함될 수 있습니다. 운용 중인 배치를 DEBUG 레벨이 아닌 레벨로 유지합니다. DEBUG 로깅은 제어된 개발 또는 지원 진단용으로만 사용되며 운용 중인 로그 수집에 적합하지 않습니다.

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

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

참고:

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

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

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

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

• 실제적인 경우 삭제 워크플로우에 별도의 데이터베이스 사용자 사용: 응용 프로그램에서 레코드를 제거해야 하는 경우 해당 경로에 대해 전용 연결 또는 풀을 선호하고 관리 에이전트 메모리 테이블에서 해당 데이터베이스 사용자에게만 DELETE을 부여합니다. 기본 런타임 연결을 정상적인 작업에 필요한 비삭제 권한으로 제한하여 우발적이거나 원치 않는 삭제의 경우 폭발 반경이 좁아지도록 합니다. 호출자가 DELETE 권한이 없는 연결을 통해 delete()를 호출하면 Oracle AI Database가 해당 명령문을 거부합니다.

• 암호화된 데이터베이스 접속 및 풀 생성: 운용 코드는 TLS 사용 Oracle AI Database 접속 또는 풀을 SDK에 전달해야 합니다. 에이전트 메모리는 호출자가 제공한 그대로 연결 또는 풀을 사용합니다. 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_message_token_length는 추출 워크플로우에 사용되는 프롬프트 시간 복사를 제한합니다. 저장된 메시지는 변경되지 않습니다.

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

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

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