Introduzione alla memoria agente

Questo articolo guida l'utente nell'installazione della memoria agente e nell'esecuzione delle operazioni di memoria di base, inclusa la memorizzazione e il recupero del contesto utente.

Prerequisiti

Verificare di disporre dei dati elencati di seguito.

Installare l'SDK

Per installare la memoria dell'agente, eseguire:

pip install "oracleagentmemory==26.6.0"

L'installazione con pip estrae ruote binarie predefinite su piattaforme supportate.

Log e diagnosi

La memoria dell'agente Oracle AI emette messaggi di diagnostica tramite il log Python standard sotto i nomi dei logger che iniziano con oracleagentmemory. L'SDK non configura gli handler o i livelli di log; le applicazioni possono instradare questi log alla console, al file o alla pipeline di osservabilità esistente. Alcuni record di log utilizzano i campi extra del log Python per una diagnostica strutturata sicura, che può essere acquisita dagli handler di log strutturati.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

Per la risoluzione dei problemi in ambienti controllati, abilitare i log DEBUG:

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

Mantieni le distribuzioni di produzione a un livello non DEBUG. I log DEBUG sono destinati alla diagnostica di sviluppo e supporto e il testo dei messaggi di log non deve essere considerato come un'API pubblica stabile.

Inizializza istanza di memoria

Creare un'istanza OracleAgentMemory configurando l'embedder, l'LLM e la connessione al database.

import oracledb

from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(connection=db_pool, embedder=embedder, llm=llm)

Nota: per impostazione predefinita, gli schemi Oracle Database gestiti non impostano un periodo di conservazione per i messaggi e le memorie. Configurare le impostazioni Time To Live MemoryRetentionConfig o per record per utilizzare un periodo retention diverso. Per ulteriori informazioni, vedere Usa Time-to-Live per messaggi e memorie.

Memorizza voci memoria

Iniziare creando un thread, aggiungendo messaggi e memorizzando una voce di memoria per l'utente.

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

Recupera voci di memoria

Cerca le memorie utilizzando una query con ambito utente.

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

Output:

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

Nota: l'output mostrato è illustrativo. Le versioni future possono restituire tipi di risultati, campi o ordini aggiuntivi.

Compatibilità modello

A partire da aprile 2026, i seguenti modelli LLM (Large Language Models) e modelli di incorporamento sono compatibili con oracleagentmemory.

LLM

I seguenti LLM (Large Language Models) sono stati confermati come compatibili.

Modelli ospitati su OCI

OpenAI

LLM self-hosted

Antropico

Gemelli

Incorporamenti

I seguenti modelli di incorporamento sono stati confermati compatibili.

Modelli ospitati su OCI

OpenAI

Gemelli