Skip to content

A programming framework for agentic AI

Move ChatMemory protocol to components.memory; rename files to use "_" convention for implementations. (#101)

Eric Zhu51dde2916fe5
diff --git a/python/examples/assistant.py b/python/examples/assistant.py
index 5a1eda194..2cd35cfe5 100644
--- a/python/examples/assistant.py
+++ b/python/examples/assistant.py
@@ -11,9 +11,9 @@ from typing import List
import aiofiles
import openai
from agnext.application import SingleThreadedAgentRuntime
-from agnext.chat.agents.oai_assistant import OpenAIAssistantAgent
+from agnext.chat.agents import OpenAIAssistantAgent
from agnext.chat.memory import BufferedChatMemory
-from agnext.chat.patterns.group_chat_manager import GroupChatManager
+from agnext.chat.patterns._group_chat_manager import GroupChatManager
from agnext.chat.types import PublishNow, TextMessage
from agnext.components import TypeRoutedAgent, message_handler
from agnext.core import AgentId, AgentRuntime, CancellationToken
diff --git a/python/examples/chat_room.py b/python/examples/chat_room.py
index 32e1df0a1..b0ffb13eb 100644
--- a/python/examples/chat_room.py
+++ b/python/examples/chat_room.py
@@ -5,28 +5,30 @@ import logging
import os
import sys
-sys.path.append(os.path.abspath(os.path.dirname(__file__)))
-
from agnext.application import SingleThreadedAgentRuntime
-from agnext.chat.memory import BufferedChatMemory, ChatMemory
-from agnext.chat.types import TextMessage
+from agnext.chat.memory import BufferedChatMemory
+from agnext.chat.types import Message, TextMessage
from agnext.chat.utils import convert_messages_to_llm_messages
from agnext.components import TypeRoutedAgent, message_handler
+from agnext.components.memory import ChatMemory
from agnext.components.models import ChatCompletionClient, OpenAI, SystemMessage
from agnext.core import AgentRuntime, CancellationToken
+
+sys.path.append(os.path.abspath(os.path.dirname(__file__)))
+
from utils import TextualChatApp, TextualUserAgent, start_runtime
# Define a custom agent that can handle chat room messages.
-class ChatRoomAgent(TypeRoutedAgent): # type: ignore
- def __init__( # type: ignore
+class ChatRoomAgent(TypeRoutedAgent):
+ def __init__(
self,
name: str,
description: str,
background_story: str,
- memory: ChatMemory, # type: ignore
- model_client: ChatCompletionClient, # type: ignore
- ) -> None: # type: ignore
+ memory: ChatMemory[Message],
+ model_client: ChatCompletionClient,
+ ) -> None:
super().__init__(description)
system_prompt = f"""Your name is {name}.
Your background story is:
@@ -46,8 +48,8 @@ Use the following JSON format to provide your thought on the latest message and
self._memory = memory
self._client = model_client
- @message_handler() # type: ignore
- async def on_chat_room_message(self, message: TextMessage, cancellation_token: CancellationToken) -> None: # type: ignore
+ @message_handler()
+ async def on_chat_room_message(self, message: TextMessage, cancellation_token: CancellationToken) -> None:
# Save the message to memory as structured JSON.
from_message = TextMessage(
content=json.dumps({"sender": message.source, "content": message.content}), source=message.source
@@ -75,16 +77,16 @@ Use the following JSON format to provide your thought on the latest message and
await self.publish_message(TextMessage(source=self.metadata["name"], content=str(response)))
-class ChatRoomUserAgent(TextualUserAgent): # type: ignore
+class ChatRoomUserAgent(TextualUserAgent):
"""An agent that is used to receive messages from the runtime."""
- @message_handler # type: ignore
- async def on_chat_room_message(self, message: TextMessage, cancellation_token: CancellationToken) -> None: # type: ignore
+ @message_handler
+ async def on_chat_room_message(self, message: TextMessage, cancellation_token: CancellationToken) -> None:
await self._app.post_runtime_message(message)
# Define a chat room with participants -- the runtime is the chat room.
-def chat_room(runtime: AgentRuntime, app: TextualChatApp) -> None: # type: ignore
+def chat_room(runtime: AgentRuntime, app: TextualChatApp) -> None:
runtime.register(
"User",
lambda: ChatRoomUserAgent(
@@ -99,7 +101,7 @@ def chat_room(runtime: AgentRuntime, app: TextualChatApp) -> None: # type: igno
description="Alice in the chat room.",
background_story="Alice is a software engineer who loves to code.",
memory=BufferedChatMemory(buffer_size=10),
- model_client=OpenAI(model="gpt-4-turbo"), # type: ignore
+ model_client=OpenAI(model="gpt-4-turbo"),
),
)
bob = runtime.register_and_get_proxy(
@@ -109,7 +111,7 @@ def chat_room(runtime: AgentRuntime, app: TextualChatApp) -> None: # type: igno
description="Bob in the chat room.",
background_story="Bob is a data scientist who loves to analyze data.",
memory=BufferedChatMemory(buffer_size=10),
- model_client=OpenAI(model="gpt-4-turbo"), # type: ignore
+ model_client=OpenAI(model="gpt-4-turbo"),
),
)
charlie = runtime.register_and_get_proxy(
@@ -119,7 +121,7 @@ def chat_room(runtime: AgentRuntime, app: TextualChatApp) -> None: # type: igno
description="Charlie in the chat room.",
background_story="Charlie is a designer who loves to create art.",
memory=BufferedChatMemory(buffer_size=10),
- model_client=OpenAI(model="gpt-4-turbo"), # type: ignore
+ model_client=OpenAI(model="gpt-4-turbo"),
),
)
app.welcoming_notice = f"""Welcome to the chat room demo with the following participants:
diff --git a/python/examples/chess_game.py b/python/examples/chess_game.py
index 0e6b52dda..76141709e 100644
--- a/python/examples/chess_game.py
+++ b/python/examples/chess_game.py
@@ -8,9 +8,9 @@ import logging
from typing import Annotated, Literal
from agnext.application import SingleThreadedAgentRuntime
-from agnext.chat.agents.chat_completion_agent import ChatCompletionAgent
+from agnext.chat.agents._chat_completion_agent import ChatCompletionAgent
from agnext.chat.memory import BufferedChatMemory
-from agnext.chat.patterns.group_chat_manager import GroupChatManager
+from agnext.chat.patterns._group_chat_manager import GroupChatManager
from agnext.chat.types import TextMessage
from agnext.components.models import OpenAI, SystemMessage
from agnext.components.tools import FunctionTool
diff --git a/python/examples/coder_reviewer.py b/python/examples/coder_reviewer.py
index 649792a4f..0b6929e4e 100644
--- a/python/examples/coder_reviewer.py
+++ b/python/examples/coder_reviewer.py
@@ -5,14 +5,15 @@ import logging.handlers
import os
import sys
-sys.path.append(os.path.abspath(os.path.dirname(__file__)))
-
from agnext.application import SingleThreadedAgentRuntime
from agnext.chat.agents import ChatCompletionAgent
from agnext.chat.memory import BufferedChatMemory
from agnext.chat.patterns import GroupChatManager
from agnext.components.models import OpenAI, SystemMessage
from agnext.core import AgentRuntime
+
+sys.path.append(os.path.abspath(os.path.dirname(__file__)))
+
from utils import TextualChatApp, TextualUserAgent, start_runtime
diff --git a/python/examples/illustrator_critics.py b/python/examples/illustrator_critics.py
index 4cf0976f1..db5bb2ad1 100644
--- a/python/examples/illustrator_critics.py
+++ b/python/examples/illustrator_critics.py
@@ -4,19 +4,20 @@ import logging
import os
import sys
-sys.path.append(os.path.abspath(os.path.dirname(__file__)))
-
import openai
from agnext.application import SingleThreadedAgentRuntime
from agnext.chat.agents import ChatCompletionAgent, ImageGenerationAgent
from agnext.chat.memory import BufferedChatMemory
-from agnext.chat.patterns.group_chat_manager import GroupChatManager
+from agnext.chat.patterns._group_chat_manager import GroupChatManager
from agnext.components.models import OpenAI, SystemMessage
from agnext.core import AgentRuntime
+
+sys.path.append(os.path.abspath(os.path.dirname(__file__)))
+
from utils import TextualChatApp, TextualUserAgent, start_runtime
-def illustrator_critics(runtime: AgentRuntime, app: TextualChatApp) -> str: # type: ignore
+def illustrator_critics(runtime: AgentRuntime, app: TextualChatApp) -> None:
runtime.register(
"User",
lambda: TextualUserAgent(
diff --git a/python/examples/orchestrator.py b/python/examples/orchestrator.py
index 77ffa3537..ab4272e0f 100644
--- a/python/examples/orchestrator.py
+++ b/python/examples/orchestrator.py
@@ -9,18 +9,16 @@ import openai
from agnext.application import (
SingleThreadedAgentRuntime,
)
-from agnext.chat.agents.chat_completion_agent import ChatCompletionAgent
-from agnext.chat.agents.oai_assistant import OpenAIAssistantAgent
+from agnext.chat.agents._chat_completion_agent import ChatCompletionAgent
+from agnext.chat.agents._oai_assistant import OpenAIAssistantAgent
from agnext.chat.memory import BufferedChatMemory
-from agnext.chat.patterns.orchestrator_chat import OrchestratorChat
+from agnext.chat.patterns._orchestrator_chat import OrchestratorChat
from agnext.chat.types import TextMessage
from agnext.components.models import OpenAI, SystemMessage
from agnext.components.tools import BaseTool
-from agnext.core import Agent, AgentRuntime, CancellationToken
-from agnext.core.intervention import DefaultInterventionHandler, DropMessage
+from agnext.core import AgentRuntime, CancellationToken
from pydantic import BaseModel, Field
from tavily import TavilyClient # type: ignore
-from typing_extensions import Any, override
logging.basicConfig(level=logging.WARNING)
logging.getLogger("agnext").setLevel(logging.DEBUG)
@@ -52,32 +50,6 @@ class SearchTool(BaseTool[SearchQuery, SearchResult]):
return SearchResult(result="No results found.")
-class LoggingHandler(DefaultInterventionHandler): # type: ignore
- send_color = "\033[31m"
- response_color = "\033[34m"
- reset_color = "\033[0m"
-
- @override
- async def on_send(self, message: Any, *, sender: Agent | None, recipient: Agent) -> Any | type[DropMessage]: # type: ignore
- if sender is None:
- print(f"{self.send_color}Sending message to {recipient.metadata['name']}:{self.reset_color} {message}")
- else:
- print(
- f"{self.send_color}Sending message from {sender.metadata['name']} to {recipient.metadata['name']}:{self.reset_color} {message}"
- )
- return message
-
- @override
- async def on_response(self, message: Any, *, sender: Agent, recipient: Agent | None) -> Any | type[DropMessage]: # type: ignore
- if recipient is None:
- print(f"{self.response_color}Received response from {sender.metadata['name']}:{self.reset_color} {message}")
- else:
- print(
- f"{self.response_color}Received response from {sender.metadata['name']} to {recipient.metadata['name']}:{self.reset_color} {message}"
- )
- return message
-
-
def software_development(runtime: AgentRuntime) -> OrchestratorChat: # type: ignore
developer = runtime.register_and_get_proxy(
"Developer",
@@ -153,7 +125,7 @@ def software_development(runtime: AgentRuntime) -> OrchestratorChat: # type: ig
async def run(message: str, user: str, scenario: Callable[[AgentRuntime], OrchestratorChat]) -> None: # type: ignore
- runtime = SingleThreadedAgentRuntime(before_send=LoggingHandler())
+ runtime = SingleThreadedAgentRuntime()
chat = scenario(runtime)
response = runtime.send_message(TextMessage(content=message, source=user), chat.id)
while not response.done():
diff --git a/python/examples/software_consultancy.py b/python/examples/software_consultancy.py
index c247d6a48..d695d07de 100644
--- a/python/examples/software_consultancy.py
+++ b/python/examples/software_consultancy.py
@@ -13,21 +13,22 @@ import logging
import os
import sys
-sys.path.append(os.path.abspath(os.path.dirname(__file__)))
-
import aiofiles
import aiohttp
import openai
from agnext.application import SingleThreadedAgentRuntime
from agnext.chat.agents import ChatCompletionAgent
from agnext.chat.memory import HeadAndTailChatMemory
-from agnext.chat.patterns.group_chat_manager import GroupChatManager
+from agnext.chat.patterns._group_chat_manager import GroupChatManager
from agnext.components.models import OpenAI, SystemMessage
from agnext.components.tools import FunctionTool
from agnext.core import AgentRuntime
from markdownify import markdownify # type: ignore
from tqdm import tqdm
from typing_extensions import Annotated
+
+sys.path.append(os.path.abspath(os.path.dirname(__file__)))
+
from utils import TextualChatApp, TextualUserAgent, start_runtime
diff --git a/python/src/agnext/chat/agents/__init__.py b/python/src/agnext/chat/agents/__init__.py
index be8abe3af..85857ac51 100644
--- a/python/src/agnext/chat/agents/__init__.py
+++ b/python/src/agnext/chat/agents/__init__.py
@@ -1,6 +1,11 @@
-from .chat_completion_agent import ChatCompletionAgent
-from .image_generation_agent import ImageGenerationAgent
-from .oai_assistant import OpenAIAssistantAgent
-from .user_proxy import UserProxyAgent
+from ._chat_completion_agent import ChatCompletionAgent
+from ._image_generation_agent import ImageGenerationAgent
+from ._oai_assistant import OpenAIAssistantAgent
+from ._user_proxy import UserProxyAgent
-__all__ = ["ChatCompletionAgent", "OpenAIAssistantAgent", "UserProxyAgent", "ImageGenerationAgent"]
+__all__ = [
+ "ChatCompletionAgent",
+ "OpenAIAssistantAgent",
+ "UserProxyAgent",
+ "ImageGenerationAgent",
+]
diff --git a/python/src/agnext/chat/agents/chat_completion_agent.py b/python/src/agnext/chat/agents/_chat_completion_agent.py
similarity index 98%
rename from python/src/agnext/chat/agents/chat_completion_agent.py
rename to python/src/agnext/chat/agents/_chat_completion_agent.py
index 86ac1a6f8..e3bf7363b 100644
--- a/python/src/agnext/chat/agents/chat_completion_agent.py
+++ b/python/src/agnext/chat/agents/_chat_completion_agent.py
@@ -7,6 +7,7 @@ from ...components import (
TypeRoutedAgent,
message_handler,
)
+from ...components.memory import ChatMemory
from ...components.models import (
ChatCompletionClient,
FunctionExecutionResult,
@@ -15,7 +16,6 @@ from ...components.models import (
)
from ...components.tools import Tool
from ...core import AgentId, CancellationToken
-from ..memory import ChatMemory
from ..types import (
FunctionCallMessage,
Message,
@@ -36,12 +36,11 @@ class ChatCompletionAgent(TypeRoutedAgent):
responses and execute tools.
Args:
- name (str): The name of the agent.
description (str): The description of the agent.
runtime (AgentRuntime): The runtime to register the agent.
system_messages (List[SystemMessage]): The system messages to use for
the ChatCompletion API.
- memory (ChatMemory): The memory to store and retrieve messages.
+ memory (ChatMemory[Message]): The memory to store and retrieve messages.
model_client (ChatCompletionClient): The client to use for the
ChatCompletion API.
tools (Sequence[Tool], optional): The tools used by the agent. Defaults
@@ -61,7 +60,7 @@ class ChatCompletionAgent(TypeRoutedAgent):
self,
description: str,
system_messages: List[SystemMessage],
- memory: ChatMemory,
+ memory: ChatMemory[Message],
model_client: ChatCompletionClient,
tools: Sequence[Tool] = [],
tool_approver: AgentId | None = None,
diff --git a/python/src/agnext/chat/agents/image_generation_agent.py b/python/src/agnext/chat/agents/_image_generation_agent.py
similarity index 70%
rename from python/src/agnext/chat/agents/image_generation_agent.py
rename to python/src/agnext/chat/agents/_image_generation_agent.py
index 08c6ea183..2378c93bc 100644
--- a/python/src/agnext/chat/agents/image_generation_agent.py
+++ b/python/src/agnext/chat/agents/_image_generation_agent.py
@@ -7,9 +7,10 @@ from ...components import (
TypeRoutedAgent,
message_handler,
)
+from ...components.memory import ChatMemory
from ...core import CancellationToken
-from ..memory import ChatMemory
from ..types import (
+ Message,
MultiModalMessage,
PublishNow,
Reset,
@@ -18,10 +19,20 @@ from ..types import (
class ImageGenerationAgent(TypeRoutedAgent):
+ """An agent that generates images using DALL-E models. It publishes the
+ generated images as MultiModalMessage.
+
+ Args:
+ description (str): The description of the agent.
+ memory (ChatMemory[Message]): The memory to store and retrieve messages.
+ client (openai.AsyncClient): The client to use for the OpenAI API.
+ model (Literal["dall-e-2", "dall-e-3"], optional): The DALL-E model to use. Defaults to "dall-e-2".
+ """
+
def __init__(
self,
description: str,
- memory: ChatMemory,
+ memory: ChatMemory[Message],
client: openai.AsyncClient,
model: Literal["dall-e-2", "dall-e-3"] = "dall-e-2",
):
@@ -32,6 +43,7 @@ class ImageGenerationAgent(TypeRoutedAgent):
@message_handler
async def on_text_message(self, message: TextMessage, cancellation_token: CancellationToken) -> None:
+ """Handle a text message. This method adds the message to the memory."""
await self._memory.add_message(message)
@message_handler
@@ -40,6 +52,10 @@ class ImageGenerationAgent(TypeRoutedAgent):
@message_handler
async def on_publish_now(self, message: PublishNow, cancellation_token: CancellationToken) -> None:
+ """Handle a publish now message. This method generates an image using a DALL-E model with
+ a prompt. The prompt is a concatenation of all TextMessages in the memory. The generated
+ image is published as a MultiModalMessage."""
+
response = await self._generate_response(cancellation_token)
self.publish_message(response)
diff --git a/python/src/agnext/chat/agents/oai_assistant.py b/python/src/agnext/chat/agents/_oai_assistant.py
similarity index 99%
rename from python/src/agnext/chat/agents/oai_assistant.py
rename to python/src/agnext/chat/agents/_oai_assistant.py
index dd82ead18..d6f87fa95 100644
--- a/python/src/agnext/chat/agents/oai_assistant.py
+++ b/python/src/agnext/chat/agents/_oai_assistant.py
@@ -14,7 +14,6 @@ class OpenAIAssistantAgent(TypeRoutedAgent):
responses.
Args:
- name (str): The name of the agent.
description (str): The description of the agent.
runtime (AgentRuntime): The runtime to register the agent.
client (openai.AsyncClient): The client to use for the OpenAI API.
diff --git a/python/src/agnext/chat/agents/user_proxy.py b/python/src/agnext/chat/agents/_user_proxy.py
similarity index 97%
rename from python/src/agnext/chat/agents/user_proxy.py
rename to python/src/agnext/chat/agents/_user_proxy.py
index 4f6024d25..dd32e93e8 100644
--- a/python/src/agnext/chat/agents/user_proxy.py
+++ b/python/src/agnext/chat/agents/_user_proxy.py
@@ -10,7 +10,6 @@ class UserProxyAgent(TypeRoutedAgent):
method to customize how user input is retrieved.
Args:
- name (str): The name of the agent.
description (str): The description of the agent.
runtime (AgentRuntime): The runtime to register the agent.
user_input_prompt (str): The console prompt to show to the user when asking for input.
diff --git a/python/src/agnext/chat/memory/__init__.py b/python/src/agnext/chat/memory/__init__.py
index aae28d6d7..b9d2a601c 100644
--- a/python/src/agnext/chat/memory/__init__.py
+++ b/python/src/agnext/chat/memory/__init__.py
@@ -1,5 +1,4 @@
-from ._base import ChatMemory
from ._buffered import BufferedChatMemory
from ._head_and_tail import HeadAndTailChatMemory
-__all__ = ["ChatMemory", "BufferedChatMemory", "HeadAndTailChatMemory"]
+__all__ = ["BufferedChatMemory", "HeadAndTailChatMemory"]
diff --git a/python/src/agnext/chat/memory/_base.py b/python/src/agnext/chat/memory/_base.py
deleted file mode 100644
index d2a2a2898..000000000
--- a/python/src/agnext/chat/memory/_base.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from typing import Any, List, Mapping, Protocol
-
-from ..types import Message
-
-
-class ChatMemory(Protocol):
- """A protocol for defining the interface of a chat memory. A chat memory
- lets agents to store and retrieve messages. It can be implemented with
- different memory recall strategies."""
-
- async def add_message(self, message: Message) -> None: ...
-
- async def get_messages(self) -> List[Message]: ...
-
- async def clear(self) -> None: ...
-
- def save_state(self) -> Mapping[str, Any]: ...
-
- def load_state(self, state: Mapping[str, Any]) -> None: ...
diff --git a/python/src/agnext/chat/memory/_buffered.py b/python/src/agnext/chat/memory/_buffered.py
index 449f3696d..e18656c00 100644
--- a/python/src/agnext/chat/memory/_buffered.py
+++ b/python/src/agnext/chat/memory/_buffered.py
@@ -1,11 +1,11 @@
from typing import Any, List, Mapping
+from ...components.memory import ChatMemory
from ...components.models import FunctionExecutionResultMessage
from ..types import Message
-from ._base import ChatMemory
-class BufferedChatMemory(ChatMemory):
+class BufferedChatMemory(ChatMemory[Message]):
"""A buffered chat memory that keeps a view of the last n messages,
where n is the buffer size. The buffer size is set at initialization.
diff --git a/python/src/agnext/chat/memory/_head_and_tail.py b/python/src/agnext/chat/memory/_head_and_tail.py
index 0492f2a4e..93a54a0a7 100644
--- a/python/src/agnext/chat/memory/_head_and_tail.py
+++ b/python/src/agnext/chat/memory/_head_and_tail.py
@@ -1,11 +1,11 @@
from typing import Any, List, Mapping
+from ...components.memory import ChatMemory
from ...components.models import FunctionExecutionResultMessage
from ..types import FunctionCallMessage, Message, TextMessage
-from ._base import ChatMemory
-class HeadAndTailChatMemory(ChatMemory):
+class HeadAndTailChatMemory(ChatMemory[Message]):
"""A chat memory that keeps a view of the first n and last m messages,
where n is the head size and m is the tail size. The head and tail sizes
are set at initialization.
diff --git a/python/src/agnext/chat/patterns/__init__.py b/python/src/agnext/chat/patterns/__init__.py
index 49019997f..0e33adbb1 100644
--- a/python/src/agnext/chat/patterns/__init__.py
+++ b/python/src/agnext/chat/patterns/__init__.py
@@ -1,3 +1,4 @@
-from .group_chat_manager import GroupChatManager
+from ._group_chat_manager import GroupChatManager
+from ._orchestrator_chat import OrchestratorChat
-__all__ = ["GroupChatManager"]
+__all__ = ["GroupChatManager", "OrchestratorChat"]
diff --git a/python/src/agnext/chat/patterns/group_chat_manager.py b/python/src/agnext/chat/patterns/_group_chat_manager.py
similarity index 97%
rename from python/src/agnext/chat/patterns/group_chat_manager.py
rename to python/src/agnext/chat/patterns/_group_chat_manager.py
index 6ce821b39..ba18472ad 100644
--- a/python/src/agnext/chat/patterns/group_chat_manager.py
+++ b/python/src/agnext/chat/patterns/_group_chat_manager.py
@@ -2,16 +2,17 @@ import logging
from typing import Any, Callable, List, Mapping
from ...components import TypeRoutedAgent, message_handler
+from ...components.memory import ChatMemory
from ...components.models import ChatCompletionClient
from ...core import AgentId, AgentProxy, AgentRuntime, CancellationToken
-from ..memory import ChatMemory
from ..types import (
+ Message,
MultiModalMessage,
PublishNow,
Reset,
TextMessage,
)
-from .group_chat_utils import select_speaker
+from ._group_chat_utils import select_speaker
logger = logging.getLogger("agnext.events")
@@ -24,7 +25,7 @@ class GroupChatManager(TypeRoutedAgent):
description (str): The description of the agent.
runtime (AgentRuntime): The runtime to register the agent.
participants (List[AgentId]): The list of participants in the group chat.
- memory (ChatMemory): The memory to store and retrieve messages.
+ memory (ChatMemory[Message]): The memory to store and retrieve messages.
model_client (ChatCompletionClient, optional): The client to use for the model.
If provided, the agent will use the model to select the next speaker.
If not provided, the agent will select the next speaker from the list of participants
@@ -44,7 +45,7 @@ class GroupChatManager(TypeRoutedAgent):
description: str,
runtime: AgentRuntime,
participants: List[AgentId],
- memory: ChatMemory,
+ memory: ChatMemory[Message],
model_client: ChatCompletionClient | None = None,
termination_word: str = "TERMINATE",
transitions: Mapping[AgentId, List[AgentId]] = {},
diff --git a/python/src/agnext/chat/patterns/group_chat_utils.py b/python/src/agnext/chat/patterns/_group_chat_utils.py
similarity index 94%
rename from python/src/agnext/chat/patterns/group_chat_utils.py
rename to python/src/agnext/chat/patterns/_group_chat_utils.py
index 1a3804ef2..966181282 100644
--- a/python/src/agnext/chat/patterns/group_chat_utils.py
+++ b/python/src/agnext/chat/patterns/_group_chat_utils.py
@@ -3,13 +3,13 @@
import re
from typing import Dict, List
+from ...components.memory import ChatMemory
from ...components.models import ChatCompletionClient, SystemMessage
from ...core import AgentProxy
-from ..memory import ChatMemory
-from ..types import TextMessage
+from ..types import Message, TextMessage
-async def select_speaker(memory: ChatMemory, client: ChatCompletionClient, agents: List[AgentProxy]) -> int:
+async def select_speaker(memory: ChatMemory[Message], client: ChatCompletionClient, agents: List[AgentProxy]) -> int:
"""Selects the next speaker in a group chat using a ChatCompletion client."""
# TODO: Handle multi-modal messages.
diff --git a/python/src/agnext/chat/patterns/orchestrator_chat.py b/python/src/agnext/chat/patterns/_orchestrator_chat.py
similarity index 100%
rename from python/src/agnext/chat/patterns/orchestrator_chat.py
rename to python/src/agnext/chat/patterns/_orchestrator_chat.py
diff --git a/python/src/agnext/components/memory/__init__.py b/python/src/agnext/components/memory/__init__.py
new file mode 100644
index 000000000..d50383821
--- /dev/null
+++ b/python/src/agnext/components/memory/__init__.py
@@ -0,0 +1,3 @@
+from ._base import ChatMemory
+
+__all__ = ["ChatMemory"]
diff --git a/python/src/agnext/components/memory/_base.py b/python/src/agnext/components/memory/_base.py
new file mode 100644
index 000000000..0363ac73b
--- /dev/null
+++ b/python/src/agnext/components/memory/_base.py
@@ -0,0 +1,19 @@
+from typing import List, Mapping, Protocol, TypeVar
+
+T = TypeVar("T")
+
+
+class ChatMemory(Protocol[T]):
+ """A protocol for defining the interface of a chat memory. A chat memory
+ lets agents store and retrieve messages. It can be implemented with
+ different memory recall strategies."""
+
+ async def add_message(self, message: T) -> None: ...
+
+ async def get_messages(self) -> List[T]: ...
+
+ async def clear(self) -> None: ...
+
+ def save_state(self) -> Mapping[str, T]: ...
+
+ def load_state(self, state: Mapping[str, T]) -> None: ...