Memoria agente

Questa pagina presenta l'implementazione concreta di Oracle AI Agent Memory.

Memoria agente Oracle

Nota: OracleAgentMemory.delete_thread() è il percorso supportato per il cleanup a catena con ambito thread. Rimuove il thread insieme ai messaggi associati, alle memorie permanenti e ai dati di recupero gestiti. Questo valore è più ampio di OracleThread.delete_message(), che elimina solo la riga del messaggio raw. L'eliminazione a livello di client attende l'estrazione in background precedente pertinente: l'eliminazione dei thread attende il thread, l'eliminazione della memoria attende il thread della destinazione memorizzata quando è presente e l'eliminazione dell'utente o dell'agente attende i thread di proprietà noti se è abilitata o meno la pulizia in cascata. Queste attese coprono solo il lavoro accettato dallo stesso cliente prima dell'inizio dell'attesa.

classe oracleagentmemory.core.OracleAgentMemory

Basi: IAgentMemory

Client di memoria agente supportato da Oracle DB o da un'area di memorizzazione fornita dal chiamante.

Creare un client di memoria.

Avvertenza: SchemaPolicy.CREATE_IF_NECESSARY può essere più costoso del normale avvio del client perché potrebbe applicare DDL dello schema gestito e riscrivere i dati con il massimo sforzo prima che l'inizializzazione abbia esito positivo. Pianificare la prima apertura di uno schema gestito meno recente come operazione di migrazione o manutenzione quando tale schema può contenere più righe.

Se l'impostazione dello schema deve creare il job di rimozione dei record scaduti gestiti, ma l'utente del database non dispone del privilegio scheduler-job, l'inizializzazione avverte e continua. I messaggi e le memorie scaduti rimangono nascosti dalle letture e dalle ricerche, ma non vengono rimossi fisicamente fino a quando il job non viene creato da un utente con CREATE JOB o un privilegio scheduler equivalente.

Quando SchemaPolicy.CREATE_IF_NECESSARY crea per la prima volta un indice ibrido gestito su uno schema esistente, Oracle analizza il testo di ricerca memorizzato e crea lo stato dell'indice ibrido gestito dal modello in-database configurato. L'avvio del client attende il completamento di tale DDL, quindi pianifica il primo aggiornamento ibrido come operazione di migrazione o manutenzione per schemi di grandi dimensioni. SearchIndexSyncMode controlla la manutenzione in corso dopo che l'indice esiste; non rende la prima build dell'indice asincrona.

Esempi

Per accedere a uno schema creato da un altro utente del database, configurare memory_rw_pool per l'utente DB dell'applicazione e impostare memory_schema_owner sul nome del database senza virgolette dell'utente proprietario.

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
pruned_search_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    pruner_llm=llm,
)
shared_client = OracleAgentMemory(
    connection=memory_rw_pool,
    embedder=embedder,
    llm=llm,
    schema_owner=memory_schema_owner,
)

Utilizzare un modello di incorporamento in DB per sfruttare la ricerca degli indici ibridi Oracle:

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
    memory_store_id=memory_store_id,
)

metodo add_agent

Aggiungere un record profilo agente al negozio.

Note

I record profilo agente vengono memorizzati nell'area di memorizzazione a livello di client e non hanno un ambito intenzionale. L'identificativo del record restituito è lo stesso identificativo pubblico utilizzato dall'applicazione come agent_id.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
)
'a1'

metodo add_agent_async (asincrono)

Aggiungere un record profilo agente all'area di memorizzazione in modo asincrono.

Note

I record profilo agente vengono memorizzati nell'area di memorizzazione a livello di client e non hanno un ambito intenzionale. L'identificativo del record restituito è lo stesso identificativo pubblico utilizzato dall'applicazione come agent_id.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
))
'a1'

metodo add_image

Aggiungere un record di immagine al client.

Esempi

image_id = client.add_image(
    b"image-bytes",
    description="Image description",
    mime_type=ImageMimeType.PNG,
    image_id="img-1",
    user_id="user-1",
)
image_id
'img-1'

metodo add_image_async (asincrono)

Rendi persistente un'immagine standalone tramite l'area di memorizzazione configurata.

Quando description viene omesso o None, l'LLM configurato genera una didascalia.

metodo add_memory

Aggiungere una memoria nel sistema di memoria, attribuita all'utente, all'agente e al thread indicati.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

metodo add_memory_async (asincrono)

Aggiungere una memoria nel sistema di memoria in modo asincrono.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "User likes pizza", memory_id="mem-1"
))
memory_id
'mem-1'

metodo add_user

Aggiungere un record profilo utente al negozio.

Note

I record del profilo utente vengono memorizzati nell'area di memorizzazione a livello di client e sono intenzionalmente senza ambito. L'identificativo del record restituito è lo stesso identificativo pubblico utilizzato dall'applicazione come user_id.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
)
'u1'

metodo add_user_async (asincrono)

Aggiungere un record profilo utente all'area di memorizzazione in modo asincrono.

Note

I record del profilo utente vengono memorizzati nell'area di memorizzazione a livello di client e sono intenzionalmente senza ambito. L'identificativo del record restituito è lo stesso identificativo pubblico utilizzato dall'applicazione come user_id.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
))
'u1'

metodo close

Chiudere il componente di memoria dell'agente.

La chiusura smette di accettare nuovi lavori in background, tra cui l'estrazione della memoria e la generazione della descrizione delle immagini, e attende che il lavoro in sospeso finisca fino al timeout configurato. Se il timeout scade, close() restituisce anche se alcuni lavori sono ancora incompiuti. Il metodo è idempotente.

Esempi

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

metodo close_async (asincrono)

Chiudere in modo asincrono il componente memoria agente.

Questo metodo segue lo stesso funzionamento di spegnimento di close(). Se il timeout scade, può tornare mentre il lavoro in background è ancora in esecuzione.

Esempi

import asyncio
asyncio.run(client.close_async())

metodo create_thread

Creare e registrare un thread.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

metodo create_thread_async (asincrono)

Creare e registrare un thread in modo asincrono.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(
    thread_id="c1", user_id="u1"
))
thread.thread_id
'c1'

metodo delete_agent

Eliminare un record profilo agente in base all'identificativo.

Note

Prima di eliminare il profilo, questo metodo attende fino a 300 secondi per l'estrazione in background precedente già accettata per i thread di proprietà noti tramite questo componente di memoria dell'agente. Questa attesa si applica se il cleanup a catena è abilitato o meno. Il cleanup a cascata viene pianificato ed eseguito all'interno del backing store come un'unica operazione. Il metodo non attende l'accettazione del lavoro dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo di memoria agente. L'uso con ambito attore concorrente durante l'eliminazione non è supportato.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

metodo delete_agent_async (asincrono)

Eliminare un record profilo agente in base all'identificativo in modo asincrono.

Note

Questo metodo segue il comportamento di attesa e concorrenza dell'estrazione in background documentato da delete_agent().

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async("a-delete", "Support assistant"))
'a-delete'
asyncio.run(client.delete_agent_async("a-delete"))
1

metodo delete_image

Eliminare un record immagine in base all'identificativo.

metodo delete_image_async (asincrono)

Eliminare un'immagine standalone tramite l'area di memorizzazione configurata.

metodo delete_memory

Eliminare un record simile alla memoria (ad esempio, una memoria, un fatto, una preferenza o una linea guida) in base all'identificativo.

Note

Prima di eliminare un record con ambito thread, questo metodo risolve il thread memorizzato e attende l'estrazione in background precedente accettata tramite questo componente di memoria agente. Non attende i thread non correlati, il lavoro accettato dopo l'inizio dell'attesa o il lavoro avviato da un altro componente o processo di memoria agente. I record senza un ambito di thread e identificativi sconosciuti non causano un'attesa di estrazione.

Esempi

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

metodo delete_memory_async (asincrono)

Eliminare un record simile alla memoria in modo asincrono.

Note

Questo metodo segue il comportamento di attesa e concorrenza mirato dell'estrazione in background documentato da delete_memory().

Esempi

import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "Temporary memory", memory_id="mem-delete"
))
asyncio.run(client.delete_memory_async(memory_id))
1

Eliminare una relazione per identificativo o tupla endpoint completa.

Quando non viene fornito alcun valore relation_id, fornire ogni argomento di origine, destinazione, tipo e etichetta di relazione nell'orientamento da origine a destinazione memorizzato.

Esempi

client.delete_record_link(relation_id="relation-id")
1

Elimina in modo asincrono una relazione per ID o una tupla completa dell'endpoint.

metodo delete_thread

Elimina tutti i record associati a un identificativo thread.

Note

Utilizzare questa operazione quando è necessaria la rimozione completa della conservazione di un thread. L'area di memorizzazione di backup elimina il thread insieme ai messaggi con ambito thread associato, alle memorie permanenti e ai dati di recupero gestiti. Ciò è diverso da OracleThread.delete_message(), che rimuove solo il record di messaggio raw e non si applica alle memorie derivate create da tale messaggio. Prima di eliminare il thread, questo metodo attende l'estrazione in background precedente già accettata per tale thread tramite questo componente di memoria dell'agente. Non attende l'accettazione del lavoro in background dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo di memoria agente. L'uso concorrente dello stesso thread durante l'eliminazione non è supportato.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

metodo delete_thread_async (asincrono)

Elimina tutti i record associati a un identificativo thread in modo asincrono.

Note

Utilizzare questa operazione quando è necessaria la rimozione completa della conservazione di un thread. L'area di memorizzazione di backup elimina il thread insieme ai messaggi con ambito thread associato, alle memorie permanenti e ai dati di recupero gestiti. Ciò è diverso da OracleThread.delete_message(), che rimuove solo il record di messaggio raw e non si applica alle memorie derivate create da tale messaggio. Prima di eliminare il thread, questo metodo attende l'estrazione in background precedente già accettata per tale thread tramite questo componente di memoria dell'agente. Non attende l'accettazione del lavoro in background dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo di memoria agente. L'uso concorrente dello stesso thread durante l'eliminazione non è supportato.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(thread_id="c-delete"))
asyncio.run(client.delete_thread_async(thread.thread_id))
1

metodo delete_user

Eliminare un record profilo utente in base all'identificativo.

Note

Prima di eliminare il profilo, questo metodo attende fino a 300 secondi per l'estrazione in background precedente già accettata per i thread di proprietà noti tramite questo componente di memoria dell'agente. Questa attesa si applica se il cleanup a catena è abilitato o meno. Il cleanup a cascata viene pianificato ed eseguito all'interno del backing store come un'unica operazione. Il metodo non attende l'accettazione del lavoro dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo di memoria agente. L'uso con ambito attore concorrente durante l'eliminazione non è supportato.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
1

metodo delete_user_async (asincrono)

Eliminare un record profilo utente in base all'identificativo in modo asincrono.

Note

Questo metodo segue il comportamento di attesa e concorrenza dell'estrazione in background documentato da delete_user().

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async("u-delete", "Prefers concise answers."))
'u-delete'
asyncio.run(client.delete_user_async("u-delete"))
1

metodo get_thread

Recupera un thread creato in precedenza.

Note

Le sostituzioni esplicite per chiamata hanno la precedenza. Quando gli override runtime vengono omessi, i thread riaperti utilizzano la configurazione runtime persistente quando disponibile prima di tornare ai valori predefiniti dell'SDK.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c2", user_id="u1")
loaded = client.get_thread("c2")
loaded.user_id
'u1'

metodo get_thread_async (asincrono)

Recupera un thread creato in precedenza in modo asincrono.

Note

Le sostituzioni esplicite per chiamata hanno la precedenza. Quando gli override runtime vengono omessi, i thread riaperti utilizzano la configurazione runtime persistente quando disponibile prima di tornare ai valori predefiniti dell'SDK.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
created = asyncio.run(client.create_thread_async(
    thread_id="c2", user_id="u1"
))
loaded = asyncio.run(client.get_thread_async("c2"))
loaded.user_id
'u1'

Creare una relazione diretta tra due record memorizzati.

Attualmente, entrambi gli endpoint devono essere record simili alla memoria: "memory", "fact", "guideline" o "preference". I tipi di relazione incorporati sono "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") e "duplicates". "contradicts" e "duplicates" utilizzano la stessa etichetta al contrario.

È possibile memorizzare un solo orientamento per una coppia di endpoint. opposite_relation_type assegna un nome alla relazione quando si passa dalla destinazione all'origine. Ad esempio, se new "supersedes" old, la traversata inversa è old "is_superseded_by" new.

Esempi

client.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

Crea in modo asincrono una relazione tipizzata tra i record memorizzati.

Attualmente, entrambi gli endpoint devono essere record simili alla memoria: "memory", "fact", "guideline" o "preference". I tipi di relazione incorporati sono "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") e "duplicates". "contradicts" e "duplicates" utilizzano la stessa etichetta al contrario.

metodo list_agents

Elenca i record profilo agente persistenti.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant", metadata={"source": "catalog"})
'a1'
[record.id for record in client.list_agents(metadata_filter={"source": "catalog"})]
['a1']

metodo list_agents_async (asincrono)

Elenca i record profilo agente persistenti in modo asincrono.

Esempi

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_agent_async(
        "a1",
        "Support assistant",
        metadata={"source": "catalog"},
    )
    records = await client.list_agents_async(metadata_filter={"source": "catalog"})
    return [record.id for record in records]
anyio.run(main)
['a1']

metodo list_images

Elenca i record immagine standalone persistenti.

Esempi

images = client.list_images(user_id="u1", limit=10)
[image.id for image in images]
['img-1']

metodo list_images_async (asincrono)

Elenca i record immagine standalone persistenti in modo asincrono.

Esempi

images = await client.list_images_async(
    user_id="u1",
    limit=10,
)
[image.id for image in images]
['img-1']

metodo list_memories

Elenca i record persistenti simili alla memoria.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_memory("User likes pizza.", user_id="u1", memory_id="mem-1")
'mem-1'
[record.id for record in client.list_memories(user_id="u1", limit=10)]
['mem-1']

metodo list_memories_async (asincrono)

Elenca i record persistenti simili alla memoria in modo asincrono.

Esempi

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_memory_async("User likes pizza.", user_id="u1", memory_id="mem-1")
    records = await client.list_memories_async(user_id="u1", limit=10)
    return [record.id for record in records]
anyio.run(main)
['mem-1']

metodo list_messages

Elenca i record dei messaggi di chat persistenti.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
message_id = thread.add_messages([{"role": "user", "content": "Hello"}])[0]
[record.id for record in client.list_messages(thread_id="c1", limit=10)] == [message_id]
True

metodo list_messages_async (asincrono)

Elenca i record dei messaggi di chat persistenti in modo asincrono.

Esempi

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    thread = await client.create_thread_async(thread_id="c1", user_id="u1")
    message_ids = await thread.add_messages_async(
        [{"role": "user", "content": "Hello"}]
    )
    records = await client.list_messages_async(thread_id="c1", limit=10)
    return [record.id for record in records] == message_ids
anyio.run(main)
True

metodo list_threads

Elenca i thread della conversazione persistenti.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.create_thread(thread_id="c1", user_id="u1").thread_id
'c1'
[record.thread_id for record in client.list_threads(user_id="u1", limit=10)]
['c1']

metodo list_threads_async (asincrono)

Elenca i thread della conversazione persistenti in modo asincrono.

Esempi

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.create_thread_async(thread_id="c1", user_id="u1")
    records = await client.list_threads_async(user_id="u1", limit=10)
    return [record.thread_id for record in records]
anyio.run(main)
['c1']

metodo list_users

Elenca i record profilo utente persistenti.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.", metadata={"source": "crm"})
'u1'
[record.id for record in client.list_users(metadata_filter={"source": "crm"})]
['u1']

metodo list_users_async (asincrono)

Elenca i record profilo utente persistenti in modo asincrono.

Esempi

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_user_async(
        "u1",
        "Prefers concise answers.",
        metadata={"source": "crm"},
    )
    records = await client.list_users_async(metadata_filter={"source": "crm"})
    return [record.id for record in records]
anyio.run(main)
['u1']

Cercare in modo sincrono i record pertinenti a un'interrogazione.

Note

I valori espliciti dell'ambito None seguono ancora le regole di corrispondenza esatta risolte: exact_*_match=False lascia la dimensione non vincolata, mentre exact_*_match=True corrisponde solo ai record senza ambito su tale dimensione.

metodo search_async (asincrono)

Cercare in modo asincrono i record pertinenti a un'interrogazione.

Note

I valori espliciti dell'ambito None seguono ancora le regole di corrispondenza esatta risolte: exact_*_match=False lascia la dimensione non vincolata, mentre exact_*_match=True corrisponde solo ai record senza ambito su tale dimensione.

metodo update_image

Aggiornare un record immagine memorizzato in base all'identificativo.

Note

I campi omessi rimangono invariati. Aggiornamenti dell'ambito non supportati da questa API. La sostituzione dei metadati è una sostituzione dell'intero oggetto, non un'unione JSON ricorsiva.

metodo update_image_async (asincrono)

Aggiornare un'immagine standalone tramite l'area di memorizzazione configurata.

Omettere image per conservare i byte esistenti. Se viene fornito image, è necessario fornire mime_type. Omettere description per conservare la descrizione esistente. Passare None per generare una nuova descrizione con l'LLM configurato; una descrizione non nulla la sostituisce direttamente. I metadati, l'indicatore orario e le impostazioni di scadenza vengono aggiornati quando vengono forniti.

metodo update_memory

Aggiorna un record memorizzato come memoria in base all'identificativo.

Note

I campi omessi vengono conservati dal record memorizzato. L'ambito memorizzato rimane invariato. La sostituzione dei metadati è una sostituzione dell'intero oggetto, non un'unione JSON ricorsiva.

metodo update_memory_async (asincrono)

Aggiorna un record memorizzato simile alla memoria in base all'identificativo in modo asincrono.

Note

I campi omessi vengono conservati dal record memorizzato. L'ambito memorizzato rimane invariato. La sostituzione dei metadati è una sostituzione dell'intero oggetto, non un'unione JSON ricorsiva.

Esempi

import asyncio
memory_id = asyncio.run(client.add_memory_async("Original memory"))
(
    asyncio.run(client.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

Aggiorna i campi modificabili di una relazione memorizzata.

I valori omessi vengono conservati. Quando relation_type passa a un tipo di relazione di memoria incorporata, l'etichetta inversa fissa sostituisce opposite_relation_type. Passare None per timestamp o metadata per cancellare il valore.

Esempi

client.update_record_link("relation-id", relation_type="supports")
1

Aggiorna in modo asincrono una relazione memorizzata.

metodo update_thread

Rendi persistenti i metadati del thread e gli aggiornamenti della configurazione di runtime permanente.

Note

La configurazione runtime viene risolta dal thread di conversazione memorizzato più le sostituzioni esplicite passate a questa chiamata, facendo corrispondere la semantica get_thread prima di rendere persistente il risultato. I metadati omessi e gli aggiornamenti di configurazione runtime vengono risolti dai dati memorizzati, non da alcuna istanza OracleThread caricata in precedenza e vengono riscritti solo gli aggiornamenti dei metadati forniti in modo esplicito o le sostituzioni durature di configurazione runtime. La sostituzione dei metadati è una sostituzione dell'intero oggetto, non un'unione JSON ricorsiva. La proprietà del thread non è modificabile tramite questa API, pertanto user_id e agent_id rimangono invariati. Lo stato di runtime modificabile, ad esempio i contatori di estrazione, non viene modificato.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

metodo update_thread_async (asincrono)

Rendi persistenti i metadati del thread aggiornati e la configurazione di runtime permanente in modo asincrono.

metodo wait_for_memory_extraction

Attendere l'avvio dell'estrazione della memoria di background precedente da parte di questo client.

Questo metodo attende l'estrazione in background già avviata tramite questa istanza OracleAgentMemory, in tutti i thread di proprietà di questo componente di memoria dell'agente. Non attende l'avvio dell'estrazione dopo l'inizio di questa attesa, l'estrazione avviata da un altro componente di memoria agente o l'esecuzione dell'estrazione in un altro processo. Conteggio degli errori di estrazione completati per questa attesa.

Esempi

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

metodo wait_for_memory_extraction_async (asincrono)

Attendere in modo asincrono l'estrazione della memoria in background precedente.

Questo metodo segue lo stesso funzionamento di wait_for_memory_extraction().

Esempi

import asyncio
asyncio.run(client.wait_for_memory_extraction_async(timeout=10))

Limiti di input immagine

classe oracleagentmemory.core.ImageInputLimitConfig

Basi: object

Configurare i limiti di immagine raw e di richiesta di immagine LLM.

I campi omessi ereditano dall'ambito di configurazione più ampio successivo. I campi client ereditano le impostazioni predefinite dell'SDK, mentre i campi per thread ereditano la configurazione del client. Impossibile disabilitare la convalida e i valori risolti non possono superare i valori massimi assoluti dell'SDK.

Esempi

from oracleagentmemory.core import ImageInputLimitConfig
config = ImageInputLimitConfig(
    max_raw_image_bytes=16 * 1024 * 1024,
    max_images_per_llm_request=200,
)

Estrazione memoria

classe oracleagentmemory.core.MemoryExtractionImageContext

Basi: str, Enum

Selezionare la modalità di partecipazione delle immagini all'estrazione automatica della memoria.

DISABLED omette immagini e descrizioni di immagini dai prompt di estrazione. IMAGE invia parti originali dell'immagine. CAPTION invia le descrizioni delle immagini come testo e richiede che ogni immagine selezionata abbia una descrizione non vuota.

CAPTION = 'CAPTION'

Includere le descrizioni come testo e richiederne una per ogni immagine selezionata.

DISABILITATO = 'disabilitato'

Non includere immagini o descrizioni di immagini nei prompt di estrazione.

IMMAGINE = 'immagine'

Includi parti originali dell'immagine nei prompt di estrazione.

MEMORY = 'memoria'

L'estrazione della memoria specifica dell'immagine non è attualmente supportata.

classe oracleagentmemory.core.MemoryExtractionConfig

Basi: object

Impostazioni raggruppate per l'estrazione automatica della memoria.

Passa questo oggetto a OracleAgentMemory, create_thread, get_thread o update_thread per configurare l'estrazione automatica. extraction_mode e le impostazioni della coda in background controllano anche la generazione automatica della descrizione delle immagini. Ogni campo viene risolto in modo indipendente. Un valore fornito per un'operazione ha la precedenza, seguito da un valore thread salvato, il valore client e il valore predefinito SDK. I thread nuovi e standalone non hanno un valore di thread salvato.

Esempi

from oracleagentmemory.core import (
    MemoryExtractionImageContext,
    MemoryExtractionConfig,
    MemoryExtractionMode,
    MemoryLinkExtractionMode,
)
config = MemoryExtractionConfig(
    extract_memories=True,
    memory_extraction_image_context=MemoryExtractionImageContext.CAPTION,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
    memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
    memory_link_extraction_token_limit=8_000,
)

Cosa fare quando l'estrazione o le descrizioni delle immagini non possono accodarsi immediatamente.

I valori omessi vengono risolti in DROP.

Numero massimo di secondi di attesa di lavoro in background per la capacità della coda in modalità di attesa.

I valori omessi vengono risolti in 300.0 secondi.

Messaggi dopo l'ultimo riepilogo valido prima dell'aggiornamento automatico.

Valori inferiori o uguali all'aggiornamento 0 a ogni controllo.

Indica se OAM gestisce i riepiloghi di contesto per le letture dei thread e i prompt di estrazione.

Indica se le descrizioni delle immagini e delle estrazioni vengono eseguite in linea o in background.

I valori omessi vengono risolti in BACKGROUND.

Messaggi tra le esecuzioni di estrazione; valori inferiori all'estrazione 0 dopo ogni aggiunta.

Rappresentazione dell'immagine; l'omissione viene risolta in thread, client, quindi DISABLED.

Metadati del messaggio di origine copiati nelle memorie estratte.

Budget del token di input per i prompt. I valori inferiori a 1 disabilitano il limite.

Finestra di messaggio recente utilizzata per i prompt di estrazione. -1 utilizza solo nuovi messaggi.

Istruzioni di chiamata facoltative aggiunte ai prompt di risoluzione automatica dei collegamenti.

Come vengono risolti i collegamenti automatici per i ricordi estratti.

I valori omessi vengono risolti in POST_EXTRACTION.

Budget token di input totale per la risoluzione del collegamento POST_EXTRACTION.

I valori al di sotto di 1 disabilitano il limite.

classe oracleagentmemory.core.MemoryExtractionMode

Basi: str, Enum

Controlla quando vengono eseguite l'estrazione automatica e le descrizioni delle immagini.

INLINE completa il lavoro derivato prima che venga restituito il metodo di scrittura. BACKGROUND restituisce dopo che la scrittura raw ha avuto esito positivo e tenta di inserire la coda. Il lavoro di sfondo è il miglior sforzo: le descrizioni generate e i ricordi derivati possono apparire più tardi o non possono mai essere scritti se non possono essere completati.

SFONDO = 'SFONDO'

Tornare dopo la scrittura raw ed eseguire il lavoro derivato in background.

IN LINEA = "IN LINEA"

Estrazione completa e descrizioni delle immagini prima che la scrittura ritorni.

classe oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Basi: str, Enum

Controlla cosa accade quando il lavoro in background configurato non può fare la coda in tempo.

Nonostante il nome specifico dell'estrazione, questa impostazione si applica anche alla generazione automatica della descrizione dell'immagine in modalità sfondo.

ELIMINA = 'ELIMINA'

Registrare un avviso e continuare immediatamente quando la capacità della coda non è disponibile.

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

Attendere la capacità della coda fino al timeout configurato, quindi registrare un'avvertenza e continuare.

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

Attendere la capacità della coda fino al timeout configurato, quindi attivare TimeoutError.