Usa memoria dell'agente Oracle con Oracle Autonomous AI Database

Questa guida mostra come connettere oracleagentmemory a Oracle Autonomous Database (ADB).

In questa guida imparerai come:

Preparare un utente dello schema ADB per la memoria di Oracle Agent.
Connettersi con TLS walletless o con un wallet mTLS.
Inizializzare lo schema della memoria gestita e memorizzare e cercare una memoria.

Suggerimento: per l'impostazione dei package, vedere Introduzione alla memoria dell'agente. Per eseguire la memoria dell'agente Oracle su un database locale containerizzato, seguire Eseguire Oracle AI Database localmente.

Prerequisiti

Hai bisogno di un Oracle Autonomous AI Database disponibile che supporti Oracle AI Vector Search (Oracle AI Database 23ai o versioni successive), un amministratore ADB in grado di creare un utente del database e un ambiente Python con oracleagentmemory installato. Se non hai ancora un database, segui la Guida al provisioning di Autonomous AI Database di Oracle.

La memoria dell'agente Oracle utilizza la connessione o il pool fornito dall'applicazione; non configura la sicurezza del trasporto del database. ADB supporta due opzioni di connessione sicura:

TLS senza wallet è adatto alla maggior parte delle nuove applicazioni. Utilizza le credenziali del database e cifra la connessione. Prima di utilizzarlo, configurare una lista di inclusione IP (ACL, IP allowlist) o un endpoint privato in modo che l'applicazione possa raggiungere il database. TLS protegge la connessione; l'ACL o l'endpoint privato controlla le reti che possono raggiungere il database.
Mutual TLS (mTLS) con un wallet è adatto quando ADB richiede mTLS o quando l'organizzazione richiede l'autenticazione con certificato client.

Usa utenti di database separati in produzione

Utilizzare due utenti del database ADB in una distribuzione di produzione:

Il proprietario dello schema crea, aggiorna e possiede le tabelle e gli indici della memoria di Oracle Agent.
L'utente applicazione si connette quando l'applicazione legge e scrive le memorie. Concedere a questo utente solo le autorizzazioni necessarie per gli oggetti del proprietario dello schema.

Non utilizzare le credenziali del proprietario dello schema per eseguire l'applicazione. Utilizzarli solo durante l'impostazione o l'aggiornamento dello schema gestito. In questa guida viene creato il proprietario dello schema. Dopo l'impostazione, configurare l'utente dell'applicazione con SchemaPolicy.REQUIRE_EXISTING. Nella guida alla risoluzione dei problemi sono elencate le autorizzazioni oggetto necessarie a un utente dell'applicazione.

Eseguire la creazione o l'aggiornamento di ogni schema come singola operazione di manutenzione prima di avviare le istanze dell'applicazione che scrivono nelle tabelle gestite. Utilizzare una connessione schema-proprietario per l'operazione; non consentire l'esecuzione contemporanea di SchemaPolicy.CREATE_IF_NECESSARY da parte di più client. Una volta completata la procedura, le istanze dell'applicazione devono utilizzare SchemaPolicy.REQUIRE_EXISTING.

Creare un utente di schema ADB

Utilizzare un utente di database ADB dedicato per essere proprietario dello schema di memoria dell'agente Oracle. In OCI Console, aprire Azioni database, connettersi come ADMIN e aprire il foglio di lavoro SQL. Creare un utente con una password sicura, concedere i privilegi utilizzati dall'impostazione dello schema gestito e impostare una quota di storage limitata per l'utente:

CREATE USER oam_owner IDENTIFIED BY "CHOOSE_A_STRONG_PASSWORD";
GRANT DWROLE TO oam_owner;
ALTER USER oam_owner QUOTA 1G ON DATA;

DWROLE include i normali privilegi di creazione degli oggetti utilizzati da Oracle Agent Memory, tra cui CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE e CREATE JOB. CREATE JOB consente a Oracle Agent Memory di creare un job pianificato che elimina definitivamente i record alla scadenza.

La quota 1G è un limite iniziale per questa guida, non un suggerimento per il dimensionamento della produzione. Selezionare un limite in base alla quantità di memoria che si prevede di memorizzare e ai criteri di conservazione. Monitora l'uso dello storage e aumenta la quota quando necessario; le scritture non riescono quando l'utente raggiunge la quota. ADB gestisce le tablespace, pertanto questa guida non ne crea una.

Connetti con TLS senza wallet

In OCI Console aprire la pagina dei dettagli ADB. In Network, configurare un'ACL che consenta l'indirizzo IP in uscita dell'applicazione o utilizzare un endpoint privato. Modificare quindi Mutual TLS (mTLS) Authentication, deselezionare Require mutual TLS (mTLS) Authentication e attendere che il database torni a Available.

Aprire Connessione al database, selezionare TLS in Autenticazione TLS e selezionare uno dei servizi di connessione elencati. I servizi in genere hanno nomi quali myadb_low, myadb_medium e myadb_high e selezionano il modo in cui ADB condivide le risorse del database tra le connessioni. Iniziare con il livello di servizio consigliato dall'amministratore del database per il carico di lavoro dell'applicazione, quindi copiarne la stringa di connessione. Memorizzarlo e le credenziali del database nel sistema di gestione dei segreti:

export ORACLE_MEMORY_DB_USER='oam_owner'
export ORACLE_MEMORY_DB_PASSWORD='<database-user-password>'
export ORACLE_MEMORY_DB_DSN='<copied TLS connection string>'

Utilizzare il descrittore TLS esattamente come copiato. Un descrittore mTLS non funziona senza un wallet.

Nell'esempio viene creato un connection pool, che è un gruppo riutilizzabile di connessioni al database. Se il file ORACLE_MEMORY_ADB_USE_MTLS non è true, tali connessioni utilizzano TLS. Utilizza SchemaPolicy.CREATE_IF_NECESSARY per la prima impostazione; utilizzare SchemaPolicy.REQUIRE_EXISTING nell'avvio normale dell'applicazione dopo che lo schema è pronto.

import os

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
)
from oracleagentmemory.core.embedders import Embedder


def create_adb_tls_pool() -> oracledb.ConnectionPool:
    """Create an ADB TLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ.get("ORACLE_MEMORY_DB_USER", "YOUR DB USER"),
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        #Set ORACLE_MEMORY_DB_DSN to the TLS descriptor copied from the ADB console.
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        min=1,
        max=5,
        increment=1,
    )


embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
MEMORY_STORE_ID = "APP_MEMORY"

L'estrazione automatica della memoria è disabilitata solo per mantenere attivo questo esempio di connessione. Configura un LLM e abilita l'estrazione quando l'applicazione richiede l'estrazione automatica della memoria permanente.

Riferimento API: OracleAgentMemory

Criterio schema

Connettersi a un wallet mTLS

Utilizzare questa opzione se la configurazione di rete ADB richiede mTLS. In OCI Console, aprire Connessione al database, selezionare un wallet dell'istanza e scaricarlo. Estrarre il wallet in una directory protetta non sottoposta a check-in nel controllo dell'origine. La documentazione Oracle consiglia autorizzazioni di file restrittive per i file wallet (ad esempio, utilizzare chmod 600 su Linux o Unix).

Esportare le credenziali del database, la directory del wallet e la password di download del wallet. ORACLE_MEMORY_WALLET_PASSWORD è la password fornita quando è stato scaricato il file ZIP del wallet; non è la password dell'utente del database. Impostare ORACLE_MEMORY_DB_DSN sull'alias di servizio nel file tnsnames.ora del wallet, ad esempio myadb_low. Non utilizzare la stringa di connessione TLS lunga della console ADB per questa configurazione del wallet:

export ORACLE_MEMORY_DB_USER='oam_owner'
export ORACLE_MEMORY_DB_PASSWORD='<database-user-password>'
export ORACLE_MEMORY_DB_DSN='myadb_low'
export ORACLE_MEMORY_WALLET_DIR='/secure/path/to/wallet'
export ORACLE_MEMORY_WALLET_PASSWORD='<wallet-download-password>'
export ORACLE_MEMORY_ADB_USE_MTLS='true'

In modalità Thin python-oracledb, la directory del wallet richiede tnsnames.ora e ewallet.pem. L'impostazione di ORACLE_MEMORY_ADB_USE_MTLS su true fa sì che l'esempio crei il pool mTLS prima che inizializzi OracleAgentMemory.

def create_adb_mtls_pool() -> oracledb.ConnectionPool:
    """Create an ADB mTLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ["ORACLE_MEMORY_DB_USER"],
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        config_dir=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_location=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_password=os.environ["ORACLE_MEMORY_WALLET_PASSWORD"],
        min=1,
        max=5,
        increment=1,
    )



if os.environ.get("ORACLE_MEMORY_ADB_USE_MTLS", "false").lower() == "true":
    db_pool = create_adb_mtls_pool()
else:
    db_pool = create_adb_tls_pool()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=MEMORY_STORE_ID,
)

Memoria in memoria e ricerca in ADB

Una volta configurato il client di memoria dell'agente Oracle con uno dei due pool, creare un thread, aggiungere una memoria permanente e cercarlo di nuovo.

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

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

for result in results:
    print(result.content)

Riferimento API: OracleAgentMemory

OracleThread

Risultati ricerca Oracle

Conclusione

In questa guida viene illustrato come preparare un utente ADB, selezionare TLS o mTLS senza wallet, connettere la memoria dell'agente Oracle a un pool python-oracledb e verificare che una memoria possa essere memorizzata e recuperata da ADB.

→ Dopo aver connesso la memoria dell'agente Oracle ad ADB, ora è possibile passare a Memorizza e cerca memoria.

Codice completo

L'esempio completo è incluso in questa guida per la copia e l'esecuzione.

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Oracle Autonomous AI Database
#-------------------------------------------------------------

##Configure an Autonomous AI Database TLS connection pool

import os

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
)
from oracleagentmemory.core.embedders import Embedder


def create_adb_tls_pool() -> oracledb.ConnectionPool:
    """Create an ADB TLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ.get("ORACLE_MEMORY_DB_USER", "YOUR DB USER"),
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        #Set ORACLE_MEMORY_DB_DSN to the TLS descriptor copied from the ADB console.
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        min=1,
        max=5,
        increment=1,
    )


embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
MEMORY_STORE_ID = "APP_MEMORY"



##Configure an Autonomous AI Database mTLS connection pool

def create_adb_mtls_pool() -> oracledb.ConnectionPool:
    """Create an ADB mTLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ["ORACLE_MEMORY_DB_USER"],
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        config_dir=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_location=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_password=os.environ["ORACLE_MEMORY_WALLET_PASSWORD"],
        min=1,
        max=5,
        increment=1,
    )



if os.environ.get("ORACLE_MEMORY_ADB_USE_MTLS", "false").lower() == "true":
    db_pool = create_adb_mtls_pool()
else:
    db_pool = create_adb_tls_pool()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=MEMORY_STORE_ID,
)



##Store and search memory in Autonomous AI Database

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

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

for result in results:
    print(result.content)