Considerações sobre Segurança

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

Por que é importante: A Memória do Agente pode persistir o conteúdo do thread e os registros de memória no Oracle AI Database e, quando os recursos suportados por LLM estiverem 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 Suportado por LLM

A Memória do Agente suporta recursos de memória ativa, como resumo de thread 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.

Observação: só envie conteúdo para a Memória do Agente que seja 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 do modelo como uma 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 de extração automática, 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.

• 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 extract_memories=False para workflows que não devem executar extração automática.

Considerações sobre Persistência e Minimização de Dados

A Memória do Agente foi projetada para persistir mensagens, memórias, metadados e incorporações no Oracle AI 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 vetores/pedaços gerenciados, use OracleAgentMemory.delete_thread().

• 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.

• 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

A Memória do Agente usa valores user_id, agent_id e thread_id fornecidos pelo chamador para recuperar o escopo. 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 essa abordagem for apropriada.

• 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 sanitização apropriados ao contexto antes de exibi-lo, transformá-lo, registrá-lo ou transmiti-lo para sistemas downstream.

Considerações sobre Integração de Aplicativos e Confiança do Chamador

A Memória do Agente deve ser chamada pelo aplicativo de integração ou outro código de backend confiável, não diretamente pelos usuários finais. As APIs de memória bruta não são um limite de segurança voltado para o usuário final e não executam 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.

Observação: 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 APIs de Memória do Agente. 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 Log e Diagnóstico

A Memória do Agente usa o log padrão do Python e não configura handlers de log do aplicativo ou níveis de log para o aplicativo de integração. Se o aplicativo de integração ativar o registro em log do DEBUG para o SDK, os logs de depuração poderão incluir detalhes adicionais da solução de problemas. Mantenha as implantações de produção em um nível que não seja DEBUG; o registro em log DEBUG se destina apenas a diagnósticos controlados de desenvolvimento ou suporte e não é adequado para a coleta de logs de produção.

Considerações Sobre Acesso ao Banco de Dados, Gerenciamento de Esquema e Segredos

A Memória do Agente usa uma conexão ou pool do Oracle AI 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.

Observação:

• Para implantações de produção, crie a conexão ou o pool do Oracle AI Database com transporte criptografado ativado antes de transmiti-lo para a Memória do Agente. 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 para o Oracle AI Database e configure o TLS ou outro transporte criptografado aprovado como parte da conexão ou da criação do pool.

• Nunca incorpore chaves de API, senhas ou outros segredos diretamente no código do aplicativo, na configuração de check-in ou em 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 de Memória do Agente gerenciadas 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 AI 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 AI Database ativado para TLS para o SDK. A Memória do Agente usa a conexão ou o pool exatamente como fornecido pelo chamador. Para python-oracledb, prefira conexões ativadas por TLS, como protocol="tcps" ou um TCPS DSN 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 de 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 do aplicativo padrão.

• 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 padrão.

• 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

A Memória do Agente 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.