Conceitos Básicos da Memória do Agente

Este artigo o orienta na instalação da Memória do Agente e na execução de operações básicas de memória, incluindo armazenamento e recuperação do contexto do usuário.

Pré-requisitos

Certifique-se de ter:

Instalar o SDK

Para instalar a Memória do Agente, execute:

pip install "oracleagentmemory==26.6.0"

A instalação com pip extrai rodas binárias predefinidas em plataformas suportadas.

Registro em Log e diagnóstico

O Oracle AI Agent Memory emite mensagens de diagnóstico por meio de log em Python padrão em nomes de logger que começam com oracleagentmemory. O SDK não configura handlers ou níveis de log; os aplicativos podem rotear esses logs para seu console, arquivo ou pipeline de observabilidade existente. Alguns registros de log usam os campos extra do log do Python para diagnóstico estruturado seguro, que pode ser capturado por handlers de log estruturado.

import logging

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

Para diagnosticar e solucionar problemas em ambientes controlados, ative os logs DEBUG:

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

Mantenha implantações de produção em um nível que não seja DEBUG. Os logs DEBUG se destinam ao desenvolvimento e ao diagnóstico de suporte, e o texto da mensagem de log não deve ser tratado como uma API pública estável.

Inicializar a Instância de Memória

Crie uma instância OracleAgentMemory configurando o incorporador, o LLM e a conexão de banco de dados.

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)

Observação: Por padrão, os esquemas gerenciados do Oracle Database não definem um período de retenção para mensagens e memórias. Configure as definições de tempo de vida MemoryRetentionConfig ou por registro para usar outro período de retenção. Para obter mais informações, consulte Usar o Tempo de Vida para Mensagens e Memórias.

Armazenar Entradas de Memória

Comece criando um thread, adicionando mensagens e armazenando uma entrada de memória para o usuário.

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.")

Recuperar Entradas de Memória

Pesquise memórias usando uma consulta no escopo do usuário.

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

Saída:

- [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.

Observação: A saída mostrada é ilustrativa. Versões futuras podem retornar tipos de resultado adicionais, campos ou prescrições.

Compatibilidade do Modelo

A partir de abril de 2026, os seguintes Modelos de Linguagem Grande (LLMs) e Modelos de Incorporação são compatíveis com o oracleagentmemory.

LMs

Os seguintes Large Language Models (LLMs) foram confirmados como compatíveis.

Modelos hospedados na OCI

OpenAI

LLMs hospedados automaticamente

Antrópico

Gêmeos

Incorporações

Os seguintes Modelos de Incorporação foram confirmados como compatíveis.

Modelos hospedados na OCI

OpenAI

Gêmeos