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

Este artigo 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.

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.13. 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.4.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.4.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 ou 3.13 e instale novamente:

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

O Python 3.14 não é suportado no momento porque o pacote segue a faixa Python suportada de sua dependência LiteLLM.

Requisitos do Banco de Dados

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

A Memória do Oracle AI Agent 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 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';

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 de runtime. A inicialização normal do aplicativo deve usar SchemaPolicy.REQUIRE_EXISTING para que valide o esquema sem criar ou alterar objetos do BD.

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

import os

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_; se você omitir esse argumento, use os nomes de objetos gerenciados não fixos em suas concessões.

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,
)

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.

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 de runtime 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.APP_MEMORY_ORACLEAGENTMEMORY_SCHEMA_META 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 de runtime que cria threads, adiciona mensagens, adiciona memórias, atualiza registros ou exclui registros, concede o privilégio de conexão e o DML nas tabelas gerenciadas.

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.APP_MEMORY_ORACLEAGENTMEMORY_SCHEMA_META 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 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,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
)

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 runtime 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,
)

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?

A memória do Oracle AI Agent 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.6.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: