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. Valide e minimize o conteúdo antes de entrar no pipeline de memória e evite incluir segredos, credenciais ou dados confidenciais desnecessários em mensagens ou memórias. 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.

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. Trate as memórias derivadas de um ciclo automático como não confiáveis até que seu aplicativo as revise.
Sanitizar ou escapar de texto derivado para seu destino: Antes de renderizar conteúdo derivado de modelo em HTML, Markdown, modelos, logs ou outras superfícies de saída, aplique escape ou sanitizaçã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 de operação correto: Se seu aplicativo precisar de controle total sobre o que se torna memória durável, considere o uso de gravações explícitas de memória, integrações somente de 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.
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 uma correspondência de usuário exata e user_id concreta. Eles rejeitam o escopo do usuário omitido, user_id=None e exact_user_match=False para que a API do cliente público não pesquise acidentalmente em vários usuários.

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: Deriva o user_id do contexto de solicitação autenticada e forneça-o em cada chamada de nível superior do OracleAgentMemory.search() ou search_async().
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 como conteúdo não confiável no limite de integração: Os registros recuperados podem incluir texto fornecido pelo chamador ou derivado do modelo. Valide, higienize ou escape desse conteúdo conforme apropriado para o destino antes de exibi-lo, transformá-lo ou transmiti-lo aos 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. 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.

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: Derive 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 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 com Segurança 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.
Criar conexões e pools de banco de dados criptografados: 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.
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.