Perguntas Frequentes (FAQs) e Solução de Problemas

Esta página aborda questões comuns de instalação, requisitos de banco de dados, acesso ao banco de dados e compatibilidade de pacotes para o Oracle AI Agent Memory.

Script/notebook Python para os trechos de código nesta página.

Instalação e atualização

Por que vejo "Nenhuma distribuição correspondente encontrada" durante a instalação?

O Oracle AI Agent Memory suporta o Python 3.10 a 3.14. Se você instalá-lo com o Python 3.9, o pip poderá reportar um erro genérico como este:

ERROR: Could not find a version that satisfies the requirement oracleagentmemory==26.8.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.8.0

Verifique se o mesmo interpretador Python é usado para python e pip:

python --version
python -m pip --version
python -m pip install oracleagentmemory

Se a versão for anterior ao Python 3.10, crie um novo ambiente com o Python 3.10, 3.11, 3.12, 3.13 ou 3.14 e instale novamente:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install oracleagentmemory

Requisitos do Banco de Dados

Quais versões e estratégias de pesquisa do Oracle AI Database são suportadas?

O Oracle Agent Memory requer o Oracle AI Database 23ai (23.4) ou posterior para seu armazenamento suportado pelo BD. SearchStrategy.HYBRID também requer a Atualização da Versão 23.6 ou posterior. Consulte Requisitos de recursos do Oracle AI Database para obter os requisitos completos de estratégia, incluindo a definição COMPATIBLE necessária para o Oracle AI Vector Search.

Como o banco de dados deve ser configurado para pesquisa vetorial?

O Oracle AI Agent Memory requer que a memória vetorial seja configurada no Oracle Database antes de usar a pesquisa vetorial ou esquemas com suporte de índice vetorial. Se a área de memória vetorial não estiver configurada ou for muito pequena, as operações do banco de dados poderão falhar com este erro:

ORA-51962: The vector memory area is out of space for the current container.

Consulte a ajuda de erro do Oracle AI Database para ORA-51962.

Peça a um DBA ou administrador privilegiado para dimensionar a memória vetorial para o contêiner raiz e o banco de dados plugável de destino. Os valores exatos dependem do seu banco de dados e da carga de trabalho; este exemplo configura 512M na raiz e 256M para o PDB:

ALTER SESSION SET CONTAINER = CDB$ROOT;
ALTER SYSTEM SET vector_memory_size = 512M SCOPE=SPFILE SID='*';
SHUTDOWN IMMEDIATE;
STARTUP;
ALTER PLUGGABLE DATABASE <PDB_NAME> OPEN;
ALTER SESSION SET CONTAINER = <PDB_NAME>;
ALTER SYSTEM SET vector_memory_size = 256M SCOPE=BOTH;
SELECT value FROM v$parameter WHERE name = 'vector_memory_size';

E se a configuração do esquema gerenciado falhar com o ORA-00054?

A configuração do esquema gerenciado pode criar índices de pesquisa vetorial, Oracle Text ou híbridos. Essas operações DDL fazem distinção entre bloqueios; portanto, um banco de dados ocupado pode ocasionalmente exibir um erro como este:

RuntimeError: Managed schema DDL failed (ORA-00054). Check that the database user has the
required schema privileges and quota to create, alter, and drop the SDK managed tables and
indexes. If those look correct, check for existing object-name conflicts or transient DDL
locks, then retry.

O Oracle AI Agent Memory já tenta novamente falhas transitórias em ORA-00054 durante a criação de índice vetorial gerenciado, índice de texto-palavra-chave e índice híbrido. Se o erro ainda persistir no seu ambiente, pergunte a um DBA ou a um administrador privilegiado se o aumento da sessão DDL_LOCK_TIMEOUT é apropriado para a conexão que executa a configuração do esquema. Essa definição afeta a DDL que aguarda toda a sessão do banco de dados, não apenas o Oracle AI Agent Memory.

Usuários e Privilégios do Banco de Dados

Um usuário do BD pode criar o esquema de memória enquanto outro usuário do BD o usa?

Use uma conta de proprietário privilegiada para criar o esquema gerenciado e, em seguida, conceda apenas os privilégios exigidos por cada usuário do BD do aplicativo. A inicialização normal do aplicativo deve usar SchemaPolicy.REQUIRE_EXISTING para que valide o esquema sem criar ou alterar objetos do BD.

Aqui, owner significa o usuário do Oracle AI Database que possui as tabelas e os índices gerenciados. Não está relacionado ao usuário ou agente no nível do aplicativo associado a um registro de memória. O cliente de runtime refere-se a este usuário do banco de dados como schema_owner.

Configure uma conexão ou pool para o proprietário do esquema e outra para o usuário do BD do aplicativo:

import os

from oracleagentmemory.core.embedders import Embedder
from oracleagentmemory.core.llms import Llm
import oracledb

DB_CONNECT_STRING = os.environ.get("ORACLE_MEMORY_DB_CONNECT_STRING", "localhost:1521/FREEPDB1")
OWNER_DB_USER = os.environ.get("ORACLE_MEMORY_OWNER_DB_USER", "memory_owner")
RUNTIME_DB_USER = os.environ.get("ORACLE_MEMORY_RUNTIME_DB_USER", "memory_r")
MEMORY_STORE_ID = "APP_MEMORY"

owner_pool = oracledb.SessionPool(
    user=OWNER_DB_USER,
    password=os.environ["ORACLE_MEMORY_OWNER_DB_PASSWORD"],
    dsn=DB_CONNECT_STRING,
)
runtime_pool = oracledb.SessionPool(
    user=RUNTIME_DB_USER,
    password=os.environ["ORACLE_MEMORY_RUNTIME_DB_PASSWORD"],
    dsn=DB_CONNECT_STRING,
)

Os exemplos abaixo pressupõem que embedder e llm já estão configurados para seu aplicativo. Eles também definem memory_store_id="APP_MEMORY", que usa o prefixo de nome de objeto APP_MEMORY_. A tabela AGENT_MEMORY_STORES compartilhada não tem prefixo; os usuários do aplicativo precisam de SELECT para que possam ler a configuração salva do armazenamento. Ele contém linhas para cada loja neste esquema proprietário, de modo que a concessão também permite a leitura dessas linhas de registro. Consulte o aviso na seção de exibições abaixo para ver as implicações de visibilidade.

Inicialize o esquema como proprietário:

from oracleagentmemory.core import (
    OracleAgentMemory,
    SchemaPolicy,
)

owner_memory = OracleAgentMemory(
    connection=owner_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_EMPTY,
    memory_store_id=MEMORY_STORE_ID,
)

Essa inicialização é executada enquanto conectada como o proprietário do esquema. Se necessário, ele cria as tabelas do banco de dados e o código do banco de dados interno (pacote PL/SQL) que o Oracle Agent Memory usa nesse esquema. Execute-o antes que os clientes do aplicativo se conectem ao schema_owner.

Se as tabelas de banco de dados existentes ou o código do banco de dados interno não corresponderem ao pacote Python instalado, a inicialização normal não as substituirá. Conecte-se como proprietário do esquema e use SchemaPolicy.RECREATE somente quando a substituição do armazenamento nomeado for aceitável. Caso contrário, peça ao administrador do banco de dados para atualizar o esquema do proprietário antes que os clientes do aplicativo se reconectem.

Em vez disso, use SchemaPolicy.CREATE_IF_NECESSARY quando quiser que a conta do proprietário aplique upgrades não destrutivos suportados para um esquema gerenciado mais antigo. Trate isso como uma operação de manutenção coordenada: execute uma conexão de proprietário de esquema, interrompa as instâncias do aplicativo que gravam nas tabelas gerenciadas e não permita que vários clientes executem o upgrade simultaneamente. Após a conclusão bem-sucedida do upgrade, reinicie as instâncias do aplicativo com SchemaPolicy.REQUIRE_EXISTING. Essa restrição é importante porque os upgrades gerenciados podem executar backfills de dados e o Oracle AI Database faz commit de instruções DDL implicitamente, de modo que um upgrade pode expor temporariamente formas de tabelas intermediárias.

Se um upgrade for interrompido, resolva o problema reportado do banco de dados e execute novamente a mesma operação do proprietário do esquema. As etapas de upgrade suportadas reconhecem seus estados intermediários documentados e podem ser retomadas sem reiniciar.

Trate as operações do ciclo de vida do esquema (criação, reparo, upgrade, recriação e exclusão) como um trabalho de manutenção coordenado. Para um determinado armazenamento de memória, execute apenas uma operação de ciclo de vida por vez em uma conexão do proprietário do esquema. Não misture a administração do pacote Python de Memória do Agente Oracle com a administração manual do banco de dados para o mesmo armazenamento e não altere as tabelas do banco de dados gerenciado ou o código do banco de dados interno enquanto uma operação de ciclo de vida estiver em andamento. Os clientes normais do aplicativo devem usar SchemaPolicy.REQUIRE_EXISTING.

Por que a configuração do esquema do proprietário falha antes de criar um armazenamento de memória?

Antes de criar ou abrir um armazenamento de mesmo esquema, o pacote Python de Memória do Agente Oracle pode precisar criar as tabelas de banco de dados e o código de banco de dados interno que ele usa na conta do proprietário do esquema. O proprietário precisa de CREATE TABLE e CREATE PROCEDURE, juntamente com os privilégios exigidos pelos recursos de armazenamento selecionados. Por exemplo, a memória vinculada precisa de CREATE TRIGGER e CREATE PROPERTY GRAPH. Consulte Conceitos Básicos da Memória do Agente para obter os privilégios específicos do recurso.

Uma conexão de aplicativo que usa schema_owner não tem permissão para preparar ou alterar as tabelas do banco de dados do proprietário ou o código do banco de dados interno. Conecte-se como proprietário para executar operações de ciclo de vida do esquema e reconecte os clientes do aplicativo com SchemaPolicy.REQUIRE_EXISTING.

Quais privilégios devo conceder a um usuário de runtime somente para leitura?

Peça a um DBA ou a um administrador privilegiado que conceda ao usuário do BD do aplicativo o privilégio de banco de dados normal necessário para estabelecer conexão, como CREATE SESSION. Em seguida, conceda SELECT nos objetos gerenciados do proprietário do esquema. Isso permite que o usuário pesquise as memórias existentes sem escrever mensagens, memórias, tópicos ou perfis.

Execute isso como DBA ou administrador privilegiado:

GRANT CREATE SESSION TO memory_r;

Em seguida, execute essas concessões como memory_owner. Os nomes de objetos incluem o prefixo APP_MEMORY_ usado nos exemplos Python acima:

GRANT SELECT ON memory_owner.AGENT_MEMORY_STORES TO memory_r;
GRANT EXECUTE ON memory_owner.DBMS_AGENT_MEMORY_STORE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_THREAD TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_ACTOR_PROFILE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_MESSAGE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_MEMORY TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_RECORD_CHUNKS TO memory_r;

Quais privilégios devo conceder a um usuário de runtime de leitura/gravação?

Para um usuário do BD de aplicativos que cria threads, adiciona mensagens, adiciona memórias, atualiza registros ou exclui registros, use o usuário do banco de dados que possui o esquema gerenciado e conceda a ele o privilégio de conexão exigido pelo banco de dados.

Execute isso como DBA ou administrador privilegiado:

GRANT CREATE SESSION TO memory_rw;

Em seguida, execute estas concessões como memory_owner:

GRANT SELECT ON memory_owner.AGENT_MEMORY_STORES TO memory_rw;
GRANT EXECUTE ON memory_owner.DBMS_AGENT_MEMORY_STORE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_THREAD TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_ACTOR_PROFILE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_MESSAGE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_MEMORY TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_RECORD_CHUNKS TO memory_rw;

Como eu concedo a um usuário de banco de dados de aplicativo acesso a um modelo de incorporação no banco de dados?

Ao usar OracleDBEmbedder com seu provider="database" padrão, o SDK executa o VECTOR_EMBEDDING como o usuário do banco de dados conectado. Os privilégios do usuário nas tabelas de Memória do Agente não concedem acesso ao modelo de incorporação. A conta que executa o SQL de incorporação também deve ter permissão para aplicar esse modelo.

Se o usuário do banco de dados possuir o modelo, nenhuma concessão extra será necessária. Se outro esquema possuir o modelo, o proprietário do modelo ou um DBA deverá conceder ao usuário de runtime permissão para usá-lo:

GRANT SELECT ON MINING MODEL memory_owner.DOC_MODEL TO memory_rw;

Como a conexão de runtime usa memory_rw, forneça ao incorporador o nome completo do modelo:

from oracleagentmemory.core.embedders import OracleDBEmbedder

db_embedder = OracleDBEmbedder(
    connection=runtime_pool,
    model="MEMORY_OWNER.DOC_MODEL",
    embedding_dimension=384,
)

O SELECT ANY MINING MODEL é uma opção mais ampla para aplicativos que precisam usar modelos em muitos esquemas. Para um modelo conhecido, use a concessão específica acima. Consulte o modelo de segurança DBMS_DATA_MINING da Oracle para obter os detalhes do privilégio do modelo.

Posso usar views em vez de schema_owner?

Sim, mas esta é uma opção de implantação secundária. Prefira schema_owner quando o usuário do banco de dados do aplicativo puder receber concessões nos objetos do esquema do proprietário; as views adicionam um requisito de manutenção e outra camada à configuração do banco de dados. Se você usar views, depois que o esquema do proprietário existir e o usuário do BD do aplicativo tiver as concessões de objeto direto necessárias, crie views com o mesmo nome no esquema do usuário do BD do aplicativo. Use views simples que expõem os objetos gerenciados completos; essas views devem ser atualizáveis para usuários do banco de dados do aplicativo que precisam gravar registros. Execute o seguinte como usuário do banco de dados do aplicativo ou por meio de um DBA com o privilégio de criação de view necessário:

Os exemplos usam o prefixo APP_MEMORY_ derivado de memory_store_id="APP_MEMORY" anteriormente; substitua-o por seu próprio prefixo ao usar outro ID.

CREATE VIEW AGENT_MEMORY_STORES AS
   SELECT * FROM memory_owner.AGENT_MEMORY_STORES;
CREATE VIEW APP_MEMORY_THREAD AS
   SELECT * FROM memory_owner.APP_MEMORY_THREAD;
CREATE VIEW APP_MEMORY_ACTOR_PROFILE AS
   SELECT * FROM memory_owner.APP_MEMORY_ACTOR_PROFILE;
CREATE VIEW APP_MEMORY_MESSAGE AS
   SELECT * FROM memory_owner.APP_MEMORY_MESSAGE;
CREATE VIEW APP_MEMORY_MEMORY AS
   SELECT * FROM memory_owner.APP_MEMORY_MEMORY;
CREATE VIEW APP_MEMORY_RECORD_CHUNKS AS
   SELECT * FROM memory_owner.APP_MEMORY_RECORD_CHUNKS;

Ao usar essas views, omita schema_owner e abra o cliente com SchemaPolicy.REQUIRE_EXISTING. O SDK valida as views como o esquema gerenciado existente e deixa índices e outros objetos pertencentes ao esquema no esquema proprietário. Só há suporte para essa solução alternativa em esquemas de modo vetorial; use schema_owner para pesquisa de palavra-chave ou híbrida. O usuário do banco de dados do aplicativo é responsável por manter as views alinhadas com o esquema gerenciado: sempre que uma nova versão do OAM adicionar uma tabela gerenciada ou alterar as colunas necessárias, crie ou atualize a view correspondente antes de abrir o cliente em relação a esse esquema.

Aviso: Esta configuração não isola os usuários do aplicativo uns dos outros. memory_owner.AGENT_MEMORY_STORES tem uma linha para cada armazenamento pertencente a memory_owner. A view expõe todas essas linhas. Por exemplo, se o proprietário tiver armazenamentos SALES e SUPPORT, um usuário de aplicativo que possa consultar essa view poderá ler os detalhes do registro de ambos os armazenamentos.

O OWNER_ID permanece como memory_owner; nunca se torna o ID do usuário do aplicativo. O mesmo se aplica ao usar schema_owner. Um usuário de aplicativo com acesso SELECT pode ler todo o registro, não apenas o armazenamento que ele abre. Para isolamento, coloque os armazenamentos em diferentes esquemas de banco de dados e conceda acesso separadamente.

Como eu estabeleço conexão com o usuário de runtime após concessões?

No runtime, construa o cliente com SchemaPolicy.REQUIRE_EXISTING usando o usuário do banco de dados que possui o esquema gerenciado:

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
    #Schema owner of the tables; this avoids ALTER SESSION
    #SET CURRENT_SCHEMA for the runtime connection.
    schema_owner=OWNER_DB_USER,
)

Os usuários somente leitura podem chamar APIs de pesquisa em relação aos registros existentes. Eles não podem usar APIs de gravação, como create_thread(), add_messages(), add_memory(), update() ou delete(), a menos que também recebam os privilégios DML correspondentes.

Um usuário de BD de aplicativo de leitura/gravação pode usar o mesmo padrão de conexão e, em seguida, chamar as APIs normais de gravação e pesquisa:

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
)

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    "concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

Compatibilidade do pacote

Como resolvo conflitos de dependência de pacote?

O Oracle AI Agent Memory depende do LiteLLM para integração modelo-fornecedor. Versões mais antigas do Oracle AI Agent Memory, incluindo a versão 26.4.0, usavam um limite superior LiteLLM mais apertado que poderia entrar em conflito com outros frameworks de agentes ou pacotes de integração quando precisavam de versões openai ou python-dotenv mais recentes.

O Oracle AI Agent Memory 26.8.0 usa o litellm>=1.84.0,<2, que permite versões openai e python-dotenv compatíveis mais recentes. Se o resolvedor relatar um conflito: