Considerações sobre Segurança

Escopo: Este documento abrange considerações de segurança relacionadas ao SDK Python de Memória do Agente do Oracle AI. Aplica-se a aplicativos que usam os recursos de memória ativa do SDK ou apenas a camada de armazenamento.

Por que é importante: o Oracle AI Agent Memory pode persistir registros de conteúdo e memória de thread no Oracle Database e, quando os recursos suportados por LLM estão ativados, enviar conteúdo para pontos finais de modelo configurados para resumo, extração de memória ou incorporações. Portanto, a implantação segura depende do tratamento cuidadoso dos dados do aplicativo, do escopo de recuperação, do acesso ao banco de dados, dos pontos finais do modelo externo e das políticas de retenção.

Considerações sobre o processamento de memória apoiado por LLM

O Oracle AI Agent Memory suporta recursos de memória ativa, como resumo de threads e extração automática de memória. Quando esses recursos estão ativados, o SDK pode enviar mensagens recentes, resumos de threads, memórias recuperadas ou texto de pesquisa para o LLM configurado ou o ponto final de incorporação.

Importante: só envie conteúdo para a Memória do Agente do Oracle AI apropriado para o ponto final do modelo configurado e suas políticas de implantação. Se a memória ativa estiver ativada para dados que parecem incluir segredos, credenciais ou dados confidenciais desnecessários, minimize ou oculte esse conteúdo antes que as mensagens entrem no pipeline de memória. Trate memórias extraídas, resumos, cartões de contexto e outros textos derivados de modelo como saída não confiável que deve ser revisada e tratada com segurança pelo aplicativo de integração.

Aviso: O texto derivado do modelo pode se tornar um estado de memória persistente. Quando recursos automáticos de extração, resumo ou cartão de contexto são ativados, um resumo, memória extraída ou registro recuperado pode ser inserido pelo SDK em prompts posteriores, como prompts de extração de memória, resumo, cartão de contexto ou agente, antes que o aplicativo possa revisar esse valor intermediário específico. Trate isso como um fluxo de dados de LLM não confiável normal: revise e valide as saídas que seu aplicativo consome e não permita que conteúdo derivado da memória autorize ações privilegiadas ou ignore a política.

Siga estas recomendações ao usar recursos de memória ativa:

Validar e minimizar dados do aplicativo: Verifique quais mensagens, metadados e IDs seu aplicativo envia para o SDK. Evite transmitir mais dados do que o fluxo de trabalho de memória precisa.
Usar pontos finais de modelo confiáveis: Configure LLM e pontos finais de incorporação que atendam aos seus requisitos de segurança de transporte, residência de dados, retenção e monitoramento operacional.
Tratar a memória gerada como dados da aplicação e saída não confiável: memórias extraídas, resumos e cartões de contexto são saídas derivadas. Revise como seu aplicativo os usa, especialmente antes que eles influenciem ações privilegiadas, chamadas de ferramentas externas ou decisões visíveis para o cliente.
Escolher extração assíncrona somente quando gravações derivadas atrasadas forem aceitáveis: No modo de segundo plano, as gravações de mensagens brutas podem ser concluídas antes que memórias derivadas, resumos ou estado de runtime relacionado sejam gravados. Se um workflow exigir revisão ou um limite de commit mais apertado antes que o estado derivado do modelo se torne durável, use a extração em linha ou desative a extração automática para esse workflow.
Conta para injeção de prompt persistente: O texto fornecido, recuperado ou derivado do modelo pelo chamador armazenado na memória pode ser repetido em prompts de resumo, extração, cartão de contexto ou agente posteriores. Delimitadores de prompt, instruções de escape e extração podem ajudar a estruturar a entrada do modelo, mas não são um limite de segurança. Revise memórias extraídas, resumos, cartões de contexto e outros textos intermediários persistidos ou vinculados a prompt antes de confiar neles. Se o seu fluxo de trabalho exigir revisão antes que o texto derivado do modelo possa influenciar a extração futura ou a construção do contexto, desative a extração automática e use gravações explícitas de memória ou outro portão de revisão controlado pelo aplicativo.
Sanitizar ou escapar de texto derivado para seu destino: Se memórias extraídas, resumos, cartões de contexto ou outro texto derivado de modelo forem renderizados em HTML, Markdown, modelos, logs ou outras superfícies de saída, aplique escape ou higienização apropriados ao contexto. Use o mesmo cuidado antes de reutilizar texto derivado em prompts downstream, entradas de ferramenta, comandos ou outros contextos semelhantes a interpretadores.
Escolha o modo operacional correto: Se seu aplicativo precisar ser revisado antes que o texto derivado do modelo possa influenciar a extração posterior ou a construção do contexto, considere o uso de gravações explícitas de memória, integrações somente para armazenamento ou memory_extraction_config=MemoryExtractionConfig(extract_memories=False) para workflows que não devem executar extração automática.

Considerações sobre persistência e minimização de dados

O Oracle AI Agent Memory foi projetado para persistir mensagens, memórias, metadados e incorporações no Oracle Database quando o armazenamento suportado pelo BD é usado. Isso permite a recuperação durável e a memória entre sessões, mas também significa que o aplicativo deve planejar quais dados são apropriados para reter.

A seguinte orientação ajuda a manter as implantações alinhadas com práticas seguras de tratamento de dados:

Para uso somente de armazenamento, persista apenas o necessário: Projete seu aplicativo para que apenas conteúdo útil e apropriado para negócios seja gravado no armazenamento de memória.
Quando os recursos de memória ativa estão ativados, planeje registros derivados: além do conteúdo fornecido pelo chamador, como mensagens e metadados, um workflow também pode persistir memórias extraídas, resumos ou incorporações.
Tratar caminhos de memória com capacidade de gravação como confiáveis: Credenciais de banco de dados e caminhos de código de backend que podem gravar mensagens, resumos, memórias, metadados, incorporações ou estado de runtime de thread podem afetar futuros prompts e resultados de recuperação. Os recursos de memória ativa persistem intencionalmente o estado derivado do modelo; se isso não for apropriado para um fluxo de trabalho, desative a extração automática ou use uma integração de gravação manual/somente armazenamento com controles de aplicativo mais restritos.
Escolher o escopo de exclusão correto para o trabalho de retenção: delete_message() remove somente o registro de mensagem bruta. Memórias derivadas ou outros artefatos com escopo de thread downstream criados a partir dessa mensagem podem permanecer pesquisáveis porque as memórias extraídas não persistem atualmente por proveniência de mensagem. Quando você precisar de limpeza no escopo do thread que também remova memórias associadas e dados de recuperação gerenciados, use OracleAgentMemory.delete_thread().
Planejar em torno do limite de exclusão e shutdown para trabalho em segundo plano: delete_thread(), delete_user(cascade=True) e delete_agent(cascade=True) aguardam apenas a extração em segundo plano aceita anteriormente já conhecida por esse cliente quando a espera é iniciada. Eles não são uma barreira de simultaneidade global entre outros identificadores, componentes ou processos, e as gravações simultâneas durante a exclusão não são suportadas. Quando um limite de retenção ou shutdown exigir que a extração em segundo plano já aceita do cliente atual seja concluída primeiro, chame wait_for_memory_extraction() antes do shutdown do processo ou das operações administrativas relacionadas.
Definir políticas de retenção e exclusão antecipadamente: Se seu aplicativo oferecer compromissos de exclusão ou retenção, certifique-se de que eles abranjam mensagens brutas, memórias extraídas, metadados e outros registros relacionados criados pelo workflow. Escolha valores ttl_days por registro e o esquema memory_retention_config com base no tipo esperado de informações em cada registro, por que o aplicativo precisa retê-lo e quaisquer compromissos de retenção aplicáveis. Use a expiração automática quando os registros devem ser expurgados por idade e verifique se o job de expurgação gerenciado da Oracle está presente em implantações com suporte do BD, especialmente quando o usuário de configuração do esquema não tem privilégios de job do scheduler.
Planejar a carga do banco de dados de job de expurgação: O job de expurgação Oracle gerenciado é executado em uma programação e exclui linhas expiradas das tabelas gerenciadas pelo SDK em batches, em vez de como uma exclusão grande. Monitore seu tempo de execução, geração de redo/undo, histórico de execução ignorada e volume de linhas em ambientes com altas taxas de gravação ou grandes lotes de expiração e ajuste as configurações de retenção ou os planos de implantação operacional se a atividade de expurgação puder se sobrepor às cargas de trabalho de banco de dados sensíveis à latência. O job gerenciado define um schedule_limit de um dia para que as execuções atrasadas por muito tempo possam ser ignoradas, em vez de serem iniciadas arbitrariamente tarde.
Evite contar com a memória como fonte de verdade: as memórias armazenadas destinam-se a melhorar o contexto e a recuperação. As aplicações devem continuar a depender de sistemas autorizados para decisões importantes.

Considerações sobre o escopo de recuperação e o controle de acesso

O Oracle AI Agent Memory usa valores user_id, agent_id e thread_id fornecidos pelo chamador para definir o escopo da recuperação. Este é um modelo de filtragem poderoso, mas não deve ser o único controle no qual seu aplicativo depende ao decidir como o conteúdo recuperado é usado ou mostrado.

Por padrão, a recuperação no escopo do thread usa correspondência exata para user_id e agent_id e uma correspondência mais ampla para thread_id para que os resultados relevantes possam abranger threads anteriores para o mesmo par usuário-agente. As chamadas de nível superior OracleAgentMemory.search() e search_async() também exigem escopo explícito do usuário e correspondência exata do usuário. Eles rejeitam o escopo do usuário omitido e o exact_user_match=False para que a API do cliente público não pesquise acidentalmente em vários usuários. A transmissão de user_id=None só é permitida com correspondência exata de usuários e destinos somente com registros sem escopo.

Use as seguintes práticas ao projetar recuperação:

Mapear regras de aplicativo para escopo de memória: Certifique-se de que os escopos que seu aplicativo passa para o SDK correspondam às suas regras de tenant, usuário e compartilhamento de dados.
Passar um escopo de usuário explícito em cada pesquisa de cliente: Derive o user_id do contexto de solicitação autenticada em vez de solicitar JSON ou outra entrada controlada por chamador e forneça-o em cada chamada OracleAgentMemory.search() ou search_async() de nível superior. Use user_id=None somente para workflows intencionalmente restritos a registros sem escopo.
Preferir o escopo mais restrito que satisfaz o caso de uso: Use filtros exatos de correspondência e mais rígidos para workflows que tratam de dados mais confidenciais.
Revisar a recuperação entre threads intencionalmente: A recuperação mais ampla pode melhorar a continuidade entre as sessões, mas os aplicativos só devem ativá-la quando esse comportamento for apropriado.
Tratar resultados de pesquisa como conteúdo recuperado, não decisões finais: As memórias retornadas podem ser relevantes, mas o aplicativo permanece responsável por decidir se e como elas devem ser mostradas ou atuadas.
Tratar o texto recuperado com segurança no limite de integração: Os registros recuperados podem incluir texto fornecido pelo chamador ou derivado do modelo. Se as memórias recuperadas ou outros textos retornados forem renderizados em HTML, Markdown, modelos, logs ou outras superfícies de saída, aplique escape ou higienização apropriados ao contexto antes de exibi-lo, transformá-lo ou transmiti-lo para sistemas downstream.

Considerações sobre integração de aplicativos e confiança do chamador

A Memória do Agente do Oracle AI deve ser chamada pelo aplicativo de integração ou outro código de backend confiável, não diretamente pelos usuários finais. Ele não é um limite de segurança voltado para o usuário final e não executa a autenticação ou autorização do usuário final por conta própria. O pacote confia no chamador para fornecer o escopo correto de user_id, agent_id, thread_id e recuperação para cada operação.

Importante: O aplicativo de integração é responsável por autenticar o usuário final, autorizar o acesso e derivar o user_id e o escopo corretos antes de chamar as APIs de Memória do Oracle AI Agent. Um user_id fornecido pelo chamador é um valor de escopo, não uma prova de identidade.

Use as seguintes práticas ao integrar o SDK em um aplicativo agentic:

Tratar user_id como entrada de aplicativo sensível à segurança: Se o aplicativo de integração deriva user_id da solicitação de entrada controlada por JSON ou outro chamador em vez de contexto autenticado, isso poderá permitir acesso à memória entre usuários. Derive o user_id do contexto do seu aplicativo autenticado em vez de permitir que os usuários finais escolham valores arbitrários.
Aplicar autorização de aplicativo antes de cada chamada de memória: O aplicativo de integração deve decidir quais valores de escopo user_id, agent_id, thread_id e de pesquisa são válidos para a solicitação atual e manter leituras e gravações dentro do tenant pretendido e do limite do usuário.
Não expor APIs de memória bruta aos usuários finais: APIs de Pacote como add_memory ou ajudantes de pesquisa devem ser encapsuladas na lógica do aplicativo que valida o chamador, impõe a política e controla quais dados podem ser gravados ou retornados.
Manter a descoberta do ID do usuário e a enumeração privilegiadas: Se o pacote adicionar ajudantes para listar ou enumerar valores de user_id, trate-os apenas como recursos administrativos e nunca exponha-os aos usuários finais por meio do aplicativo de integração.
Revisar substituições de escopo com cuidado: Qualquer workflow que amplie o escopo do thread, desative a correspondência exata ou desative as APIs de armazenamento de nível inferior deve ser restrito a componentes confiáveis e revisado para efeitos entre usuários ou entre tenants.

Considerações sobre logs e diagnósticos

O Oracle AI Agent Memory usa o registro em log Python padrão e não configura handlers de log de aplicativos ou níveis de log para o aplicativo de integração. Os aplicativos podem ativar o logger oracleagentmemory e rotear logs do SDK por meio de sua configuração de log existente.

Use as seguintes práticas ao consumir logs do SDK:

Manter implantações de produção em um nível não DEBUG: o registro em log DEBUG se destina apenas a diagnósticos controlados de desenvolvimento ou suporte e não é adequado para coleta de logs de produção.
Limitar o acesso a logs de diagnóstico: Armazene logs em sumidouros protegidos com políticas apropriadas de controle de acesso, retenção e compartilhamento. Revise os pacotes de suporte antes de enviar logs para fora do ambiente operacional.
Evite adicionar contexto confidencial em wrappers de log de aplicativos: Não enriqueça registros de log do SDK com prompts, conteúdo de memória, credenciais, metadados brutos, valores de linha do banco de dados ou identificadores controlados pelo chamador.
Tratar o texto do log como saída de diagnóstico, não uma interface de auditoria: As mensagens de log podem ajudar a diagnosticar e solucionar problemas de comportamento do SDK, mas os aplicativos devem usar seus próprios eventos de auditoria explícitos para workflows de segurança e conformidade.

Considerações sobre acesso ao banco de dados, gerenciamento de esquemas e segredos

A Memória do Oracle AI Agent usa uma conexão ou pool do Oracle Database fornecido pelo chamador. O pacote não cria nem gerencia as próprias credenciais do banco de dados. Ele também não cria, negocia ou atualiza a criptografia de rede do banco de dados em nome do chamador.

Importante: O código de produção deve passar uma conexão ou um pool do Oracle Database ativado para TLS na Memória do Oracle AI Agent. O SDK usa a conexão ou o pool fornecido pelo chamador no estado em que se encontra e não atualiza um DSN de texto simples. Não use conexões de banco de dados de texto sem formatação em redes não confiáveis, compartilhadas ou externas. Ao usar o python-oracledb, siga a seção oficial Criptografando Seguramente o Tráfego de Rede com o Oracle Database e configure o TLS ou outro transporte criptografado aprovado como parte da criação da conexão ou do pool.

Importante: Nunca incorpore chaves de API, senhas ou outros segredos diretamente no código do aplicativo, na configuração de check-in ou nos artefatos exportados. Sempre use mecanismos de injeção seguros e siga o princípio de privilégio mínimo para acesso a credenciais.

As seguintes práticas de implantação são recomendadas:

Usar usuários de banco de dados com apenas os privilégios necessários: Conceda somente o que é necessário para o modelo de implantação e a política de esquema selecionados.
Usar um usuário de banco de dados separado para workflows de exclusão, quando prático: Se seu aplicativo precisar remover registros, prefira uma conexão ou um pool dedicado para esses caminhos e conceda DELETE nas tabelas gerenciadas do Oracle AI Agent Memory somente a esse usuário do banco de dados. Mantenha a conexão de runtime principal limitada aos privilégios de não exclusão necessários para suas operações normais, de modo que as exclusões acidentais ou indesejadas tenham um raio de explosão mais estreito. Se um chamador chamar delete() por meio de uma conexão que não tenha a permissão DELETE, o Oracle Database rejeitará a instrução.
Criar conexões e pools de banco de dados criptografados: O código de produção deve passar uma conexão ou pool do Oracle Database ativado para TLS para o SDK. O Oracle AI Agent Memory usa a conexão ou o pool fornecido pelo chamador exatamente conforme fornecido, portanto, para python-oracledb, prefira conexões ativadas por TLS, como protocol="tcps" ou um DSN TCPS equivalente, configure a wallet ou o material da CA necessário e mantenha a validação do certificado do servidor ativada.
Manter a política de esquema padrão, a menos que você precise explicitamente de alterações DDL: SchemaPolicy.REQUIRE_EXISTING é o padrão e evita a criação, modificação ou eliminação de objetos de esquema durante a inicialização normal do aplicativo.
Restringir modos de configuração destrutivos: O SchemaPolicy.RECREATE destina-se a workflows de configuração, teste ou administrativos e não deve ser usado em caminhos de produção normais.
Confie em caminhos SQL gerenciados por pacote, não na montagem SQL dinâmica no código do aplicativo: Nos caminhos do banco de dados gerenciado, os valores de registro e os filtros de pesquisa são enviados com variáveis de bind, e os nomes de objetos gerenciados são derivados de prefixos validados.
Proteger credenciais de conexão e provedor: Armazene o banco de dados, o LLM e incorpore credenciais em um gerenciador de segredos, como o OCI Vault, e gire-as regularmente.
Preferir TLS validado no modo Fino e Grosso: Os documentos oficiais do python-oracledb observam que os modos Fino e Grosso suportam TLS, e o modo Grosso também pode usar a Criptografia de Rede Nativa da Oracle, onde esse é seu padrão aprovado.
Usar transporte seguro para o banco de dados: A segurança de rede do banco de dados, a configuração de TLS e o método de autenticação são determinados pela conexão fornecida pelo chamador e devem seguir os padrões da sua organização.

Considerações sobre comunicação de rede e pontos finais externos

O Oracle AI Agent Memory pode se comunicar com serviços externos quando a implantação configura provedores remotos de LLM ou incorporação. O SDK encaminha prompts e solicita parâmetros por meio do caminho do cliente configurado, mas o aplicativo e a implantação adjacentes permanecem responsáveis por proteger essas conexões.

Recomendamos o seguinte:

Use HTTPS para pontos finais de modelo e prefira caminhos de rede privados ou restritos quando disponíveis.
Monitore o tráfego de saída e o uso do provedor para destinos inesperados, volume de solicitação incomum ou consumo de token anômalo.
Escolha provedores que atendam às suas necessidades de conformidade e residência antes de ativar recursos de memória ativa em fluxos de trabalho regulamentados ou confidenciais.

Considerações sobre os vetores de exaustão de recursos

Os fluxos de trabalho de memória podem aumentar o uso do banco de dados, incorporar tráfego e consumo de token de LLM ao longo do tempo. Isso é verdade tanto para o uso excessivo malicioso quanto para erros inocentes de implementação, como mensagens de grandes dimensões ou padrões de recuperação excessivamente amplos.

Use estes controles como parte de sua proteção de produção:

Definir limites práticos de prompt e mensagem: Configure valores como max_message_token_length e memory_extraction_token_limit para se ajustar aos limites da carga de trabalho e do provedor. max_message_token_length limita a cópia de prompt usada pelos workflows de extração; as mensagens armazenadas permanecem inalteradas.
Tamanhos de recuperação vinculados: Use valores max_results razoáveis e filtros de tipo de registro para pesquisas de aplicativos.
Aplicar limites de infraestrutura fora do SDK: Use cotas de banco de dados, limites de conexão, controles de rede, timeouts de ponto final e limitação de taxa na implantação circundante.
Monitorar o crescimento ao longo do tempo: Acompanhe o volume de mensagens armazenadas, o crescimento durável da memória, o uso do provedor e a latência de consultas para que as alterações de retenção ou ajuste possam ser feitas antes que afetem a confiabilidade.