Usar Memória do Agente com o WayFlow

Neste artigo, você aprenderá a conectar a Memória do Agente a um agente do WayFlow para que o agente possa reutilizar fatos duráveis entre as sessões.

Dica: Para configurar o pacote, consulte Conceitos Básicos da Memória do Agente. Se você precisar de um Oracle AI Database local para este exemplo, consulte Executar o Oracle AI Database Localmente. Para saber mais sobre o WayFlow, consulte https://github.com/oracle/wayflow.

Configurar Memória do Agente e WayFlow

Crie um thread de Memória do Agente para o usuário, exponha uma ferramenta search_memory ao WayFlow e construa o WayFlow Agent com uma OpenAIModel. A ferramenta search_memory consulta a API de Memória do Agente por usuário e ID do agente para que ele possa recuperar fatos duráveis de sessões anteriores, em vez de se limitar ao thread atual. O cliente de Memória do Agente também usa seu próprio LLM para extrair periodicamente memórias duráveis de mensagens de thread recentes, enquanto o WayFlow Agent continua a usar seu próprio OpenAIModel para respostas e chamadas de ferramenta.

from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from wayflowcore.agent import Agent
from wayflowcore.models import OpenAIModel
from wayflowcore.tools import tool

embedder = Embedder(
    model="YOUR_EMBEDDING_MODEL",
    api_base="YOUR_EMBEDDING_API_BASE",
    api_key="YOUR_EMBEDDING_API_KEY",
)
llm = Llm(
    model="gpt-4.1-mini",
    api_key="YOUR_OPENAI_API_KEY",
)
db_pool = ...  #an oracledb connection or connection pool
wayflow_llm = OpenAIModel(
    model_id="gpt-4.1-mini",
    api_key="YOUR_OPENAI_API_KEY",
)


#Keep these identifiers stable for the same assistant and end user so memory
#is scoped consistently across threads and sessions.
agent_id = "support_agent"
user_id = "user_123"
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_thread = memory.create_thread(
    thread_id="wayflow_memory_demo",
    user_id=user_id,
    agent_id=agent_id,
)

from typing import Annotated


@tool
def search_memory(
    query: Annotated[str, "Question to search in Oracle Agent Memory"],
) -> Annotated[str, "Top matching memory content"]:
    """Search Oracle Agent Memory for durable user facts relevant to the current request."""
    results = memory.search(
        query=query,
        user_id=user_id,
        agent_id=agent_id,
        max_results=1,
        record_types=["memory"],
    )
    if not results:
        return "No relevant memory found."
    return results[0].content

assistant = Agent(
    llm=wayflow_llm,
    agent_id=agent_id,
    custom_instruction=(
        "You are a support agent. When the user asks about durable facts from "
        "prior sessions, call the search_memory tool before answering."
    ),
    tools=[search_memory],
)

Persistir Contexto do Usuário Após uma Sessão

Após cada sessão do WayFlow, anexe as mensagens trocadas à Memória do Agente e armazene qualquer fato durável que deva ser reutilizado posteriormente.

session_1 = assistant.start_conversation()
user_message = (
    "I am John, a Python developer and I need help debugging a payment service."
)
session_1.append_user_message(user_message)
session_1.execute()
assistant_reply = session_1.get_last_message().content

print(assistant_reply)
#I can help with that. What error are you seeing?

#add_messages will add messages to the DB and extract memories automatically
memory_thread.add_messages(
    [
        {"role": "user", "content": user_message},
        {"role": "assistant", "content": assistant_reply},
    ]
)
#add_memory adds memory to the DB
memory_thread.add_memory("The user is John, a Python developer.")

Reutilizar Memória em uma Nova Sessão do WayFlow

Quando uma sessão posterior for iniciada, reabra o mesmo thread de Memória do Agente e deixe que o agente do WayFlow chame search_memory para recuperar o contexto anterior do usuário.

memory_thread = memory.get_thread("wayflow_memory_demo")
assistant = Agent(
    llm=wayflow_llm,
    agent_id=agent_id,
    custom_instruction=(
        "You are a support agent. When the user asks about durable facts from "
        "prior sessions, call the search_memory tool before answering."
    ),
    tools=[search_memory],
)

session_2 = assistant.start_conversation()
session_2.append_user_message("Who am I?")
session_2.execute()
remembered_reply = session_2.get_last_message().content

print(remembered_reply)

Saída:

The user is John, a Python developer.

Uso Avançado

Para uma integração mais rígida, você pode registrar um listener de eventos do WayFlow que armazena as entradas ConversationMessageAddedEvent e as grava na Memória do Agente no final de uma execução. Isso mantém o caminho de atualização da Memória do Agente desacoplado do código do thread principal enquanto persiste as mensagens finais trocadas.

from wayflowcore.events.event import ConversationMessageAddedEvent
from wayflowcore.events.eventlistener import GenericEventListener, register_event_listeners

pending_messages: list[dict[str, str]] = []


def _buffer_thread_message(event: ConversationMessageAddedEvent) -> None:
    if event.streamed:
        return
    pending_messages.append(
        {
            "role": event.message.role,
            "content": event.message.content,
        }
    )


message_listener = GenericEventListener(
    [ConversationMessageAddedEvent],
    _buffer_thread_message,
)

with register_event_listeners([message_listener]):
    session_3 = assistant.start_conversation()
    session_3.append_user_message("Please remember that I prefer concise code reviews.")
    session_3.execute()

if pending_messages:
    memory_thread.add_messages(pending_messages)

Desativar extração automática

Se você quiser apenas persistir mensagens e adicionar memórias duráveis manualmente, crie o cliente Memória do Agente com extract_memories=False e insira as linhas de memória duráveis você mesmo.

manual_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)
manual_memory_thread = manual_memory.create_thread(
    thread_id="wayflow_manual_memory_demo",
    user_id=user_id,
    agent_id=agent_id,
)
manual_memory_thread.add_messages(
    [
        {
            "role": "user",
            "content": "Please remember that I prefer concise code reviews.",
        },
        {
            "role": "assistant",
            "content": "Understood. I will keep responses concise.",
        },
    ]
)
manual_memory_thread.add_memory("The user prefers concise code reviews.")

Conclusão

Neste artigo, aprendemos a conectar a Memória do Agente a um agente do WayFlow, persistir mensagens trocadas e memórias duráveis após cada sessão e reutilizar o contexto anterior do usuário em execuções posteriores.

Dica: Depois de aprender a integrar a Memória do Agente ao WayFlow, você também pode se interessar em Integrar Memória do Agente ao LangGraph.

Código Inteiro

#Copyright © 2026 Oracle and/or its affiliates.
#isort:skip_file
#fmt: off
#Agent Memory Code Example - Integration with WayFlow
#-----------------------------------------------------

#How to use:
#Create a new Python virtual environment and install the latest oracleagentmemory version.

#You can now run the script
#1. As a Python file:
#```bash
#python integration_with_wayflow.py
#```
#2. As a Notebook (in VSCode):
#When viewing the file,
#- press the keys Ctrl + Enter to run the selected cell
#- or Shift + Enter to run the selected cell and move to the cell below


##Configure Oracle Memory and WayFlow

#%%
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from wayflowcore.agent import Agent
from wayflowcore.models import OpenAIModel
from wayflowcore.tools import tool

embedder = Embedder(
    model="YOUR_EMBEDDING_MODEL",
    api_base="YOUR_EMBEDDING_API_BASE",
    api_key="YOUR_EMBEDDING_API_KEY",
)
llm = Llm(
    model="gpt-4.1-mini",
    api_key="YOUR_OPENAI_API_KEY",
)
db_pool = ...  #an oracledb connection or connection pool
wayflow_llm = OpenAIModel(
    model_id="gpt-4.1-mini",
    api_key="YOUR_OPENAI_API_KEY",
)

#Keep these identifiers stable for the same assistant and end user so memory
#is scoped consistently across threads and sessions.
agent_id = "support_agent"
user_id = "user_123"
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_thread = memory.create_thread(
    thread_id="wayflow_memory_demo",
    user_id=user_id,
    agent_id=agent_id,
)

from typing import Annotated


@tool
def search_memory(
    query: Annotated[str, "Question to search in Oracle Agent Memory"],
) -> Annotated[str, "Top matching memory content"]:
    """Search Oracle Agent Memory for durable user facts relevant to the current request."""
    results = memory.search(
        query=query,
        user_id=user_id,
        agent_id=agent_id,
        max_results=1,
        record_types=["memory"],
    )
    if not results:
        return "No relevant memory found."
    return results[0].content

assistant = Agent(
    llm=wayflow_llm,
    agent_id=agent_id,
    custom_instruction=(
        "You are a support agent. When the user asks about durable facts from "
        "prior sessions, call the search_memory tool before answering."
    ),
    tools=[search_memory],
)


##Persist user context after a session

#%%
session_1 = assistant.start_conversation()
user_message = (
    "I am John, a Python developer and I need help debugging a payment service."
)
session_1.append_user_message(user_message)
session_1.execute()
assistant_reply = session_1.get_last_message().content

print(assistant_reply)
#I can help with that. What error are you seeing?

memory_thread.add_messages(
    [
        {"role": "user", "content": user_message},
        {"role": "assistant", "content": assistant_reply},
    ]
)
memory_thread.add_memory("The user is John, a Python developer.")


##Reuse memory in a new WayFlow session

#%%
memory_thread = memory.get_thread("wayflow_memory_demo")
assistant = Agent(
    llm=wayflow_llm,
    agent_id=agent_id,
    custom_instruction=(
        "You are a support agent. When the user asks about durable facts from "
        "prior sessions, call the search_memory tool before answering."
    ),
    tools=[search_memory],
)

session_2 = assistant.start_conversation()
session_2.append_user_message("Who am I?")
session_2.execute()
remembered_reply = session_2.get_last_message().content

print(remembered_reply)
#The user is John, a Python developer.


##Advanced use event listeners

#%%
from wayflowcore.events.event import ConversationMessageAddedEvent
from wayflowcore.events.eventlistener import GenericEventListener, register_event_listeners

pending_messages: list[dict[str, str]] = []


def _buffer_thread_message(event: ConversationMessageAddedEvent) -> None:
    if event.streamed:
        return
    pending_messages.append(
        {
            "role": event.message.role,
            "content": event.message.content,
        }
    )


message_listener = GenericEventListener(
    [ConversationMessageAddedEvent],
    _buffer_thread_message,
)

with register_event_listeners([message_listener]):
    session_3 = assistant.start_conversation()
    session_3.append_user_message("Please remember that I prefer concise code reviews.")
    session_3.execute()

if pending_messages:
    memory_thread.add_messages(pending_messages)


##Disable automatic memory extraction

#%%
manual_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)
manual_memory_thread = manual_memory.create_thread(
    thread_id="wayflow_manual_memory_demo",
    user_id=user_id,
    agent_id=agent_id,
)
manual_memory_thread.add_messages(
    [
        {
            "role": "user",
            "content": "Please remember that I prefer concise code reviews.",
        },
        {
            "role": "assistant",
            "content": "Understood. I will keep responses concise.",
        },
    ]
)
manual_memory_thread.add_memory("The user prefers concise code reviews.")