Skip to content

A programming framework for agentic AI

fix buffered memory; update documentation (#65)

Eric Zhu1b9f4641a7ea
diff --git a/examples/chat_room.py b/examples/chat_room.py
index 294b634d9..26f0477ca 100644
--- a/examples/chat_room.py
+++ b/examples/chat_room.py
@@ -66,17 +66,18 @@ Use the following JSON format to provide your thought on the latest message and
from_message = TextMessage(
content=json.dumps({"sender": message.source, "content": message.content}), source=message.source
)
- self._memory.add_message(from_message)
+ await self._memory.add_message(from_message)
# Get a response from the model.
raw_response = await self._client.create(
- self._system_messages + convert_messages_to_llm_messages(self._memory.get_messages(), self_name=self.name),
+ self._system_messages
+ + convert_messages_to_llm_messages(await self._memory.get_messages(), self_name=self.name),
json_output=True,
)
assert isinstance(raw_response.content, str)
# Save the response to memory.
- self._memory.add_message(ChatRoomMessage(source=self.name, content=raw_response.content))
+ await self._memory.add_message(ChatRoomMessage(source=self.name, content=raw_response.content))
# Parse the response.
data = json.loads(raw_response.content)
diff --git a/src/agnext/chat/agents/chat_completion_agent.py b/src/agnext/chat/agents/chat_completion_agent.py
index 5ad156d18..65521000f 100644
--- a/src/agnext/chat/agents/chat_completion_agent.py
+++ b/src/agnext/chat/agents/chat_completion_agent.py
@@ -31,6 +31,26 @@ from ..utils import convert_messages_to_llm_messages
class ChatCompletionAgent(TypeRoutedAgent):
+ """An agent implementation that uses the ChatCompletion API to gnenerate
+ 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.
+ model_client (ChatCompletionClient): The client to use for the
+ ChatCompletion API.
+ tools (Sequence[Tool], optional): The tools used by the agent. Defaults
+ to []. If no tools are provided, the agent cannot handle tool calls.
+ If tools are provided, and the response from the model is a list of
+ tool calls, the agent will call itselfs with the tool calls until it
+ gets a response that is not a list of tool calls, and then use that
+ response as the final response.
+ """
+
def __init__(
self,
name: str,
@@ -50,18 +70,23 @@ class ChatCompletionAgent(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 and
+ does not generate any message."""
# Add a user message.
- self._memory.add_message(message)
+ await self._memory.add_message(message)
@message_handler()
async def on_reset(self, message: Reset, cancellation_token: CancellationToken) -> None:
+ """Handle a reset message. This method clears the memory."""
# Reset the chat messages.
- self._memory.clear()
+ await self._memory.clear()
@message_handler()
async def on_respond_now(
self, message: RespondNow, cancellation_token: CancellationToken
) -> TextMessage | FunctionCallMessage:
+ """Handle a respond now message. This method generates a response and
+ returns it to the sender."""
# Generate a response.
with tqdm(desc=f"{self.name} is thinking...", bar_format="{desc}: {elapsed_s}") as pbar:
response = await self._generate_response(message.response_format, cancellation_token)
@@ -72,6 +97,8 @@ class ChatCompletionAgent(TypeRoutedAgent):
@message_handler()
async def on_publish_now(self, message: PublishNow, cancellation_token: CancellationToken) -> None:
+ """Handle a publish now message. This method generates a response and
+ publishes it."""
# Generate a response.
# TODO: refactor this to use message_handler decorator.
with tqdm(desc=f"{self.name} is thinking...", bar_format="{desc}: {elapsed_s}", leave=False) as pbar:
@@ -85,11 +112,13 @@ class ChatCompletionAgent(TypeRoutedAgent):
async def on_tool_call_message(
self, message: FunctionCallMessage, cancellation_token: CancellationToken
) -> FunctionExecutionResultMessage:
+ """Handle a tool call message. This method executes the tools and
+ returns the results."""
if len(self._tools) == 0:
raise ValueError("No tools available")
# Add a tool call message.
- self._memory.add_message(message)
+ await self._memory.add_message(message)
# Execute the tool calls.
results: List[FunctionExecutionResult] = []
@@ -126,7 +155,7 @@ class ChatCompletionAgent(TypeRoutedAgent):
tool_call_result_msg = FunctionExecutionResultMessage(content=results)
# Add tool call result message.
- self._memory.add_message(tool_call_result_msg)
+ await self._memory.add_message(tool_call_result_msg)
# Return the results.
return tool_call_result_msg
@@ -137,8 +166,9 @@ class ChatCompletionAgent(TypeRoutedAgent):
cancellation_token: CancellationToken,
) -> TextMessage | FunctionCallMessage:
# Get a response from the model.
+ hisorical_messages = await self._memory.get_messages()
response = await self._client.create(
- self._system_messages + convert_messages_to_llm_messages(self._memory.get_messages(), self.name),
+ self._system_messages + convert_messages_to_llm_messages(hisorical_messages, self.name),
tools=self._tools,
json_output=response_format == ResponseFormat.json_object,
)
@@ -158,8 +188,9 @@ class ChatCompletionAgent(TypeRoutedAgent):
cancellation_token=cancellation_token,
)
# Make an assistant message from the response.
+ hisorical_messages = await self._memory.get_messages()
response = await self._client.create(
- self._system_messages + convert_messages_to_llm_messages(self._memory.get_messages(), self.name),
+ self._system_messages + convert_messages_to_llm_messages(hisorical_messages, self.name),
tools=self._tools,
json_output=response_format == ResponseFormat.json_object,
)
@@ -175,7 +206,7 @@ class ChatCompletionAgent(TypeRoutedAgent):
raise ValueError(f"Unexpected response: {response.content}")
# Add the response to the chat messages.
- self._memory.add_message(final_response)
+ await self._memory.add_message(final_response)
return final_response
diff --git a/src/agnext/chat/agents/oai_assistant.py b/src/agnext/chat/agents/oai_assistant.py
index 9e652cd3c..423c33c18 100644
--- a/src/agnext/chat/agents/oai_assistant.py
+++ b/src/agnext/chat/agents/oai_assistant.py
@@ -10,6 +10,22 @@ from ..types import PublishNow, Reset, RespondNow, ResponseFormat, TextMessage
class OpenAIAssistantAgent(TypeRoutedAgent):
+ """An agent implementation that uses the OpenAI Assistant API to generate
+ 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.
+ assistant_id (str): The assistant ID to use for the OpenAI API.
+ thread_id (str): The thread ID to use for the OpenAI API.
+ assistant_event_handler_factory (Callable[[], AsyncAssistantEventHandler], optional):
+ A factory function to create an async assistant event handler. Defaults to None.
+ If provided, the agent will use the streaming mode with the event handler.
+ If not provided, the agent will use the blocking mode to generate responses.
+ """
+
def __init__(
self,
name: str,
@@ -28,6 +44,7 @@ class OpenAIAssistantAgent(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 thread."""
# Save the message to the thread.
_ = await self._client.beta.threads.messages.create(
thread_id=self._thread_id,
@@ -38,6 +55,7 @@ class OpenAIAssistantAgent(TypeRoutedAgent):
@message_handler()
async def on_reset(self, message: Reset, cancellation_token: CancellationToken) -> None:
+ """Handle a reset message. This method deletes all messages in the thread."""
# Get all messages in this thread.
all_msgs: List[str] = []
while True:
@@ -56,10 +74,12 @@ class OpenAIAssistantAgent(TypeRoutedAgent):
@message_handler()
async def on_respond_now(self, message: RespondNow, cancellation_token: CancellationToken) -> TextMessage:
+ """Handle a respond now message. This method generates a response and returns it to the sender."""
return await self._generate_response(message.response_format, cancellation_token)
@message_handler()
async def on_publish_now(self, message: PublishNow, cancellation_token: CancellationToken) -> None:
+ """Handle a publish now message. This method generates a response and publishes it."""
response = await self._generate_response(message.response_format, cancellation_token)
await self._publish_message(response)
diff --git a/src/agnext/chat/agents/user_proxy.py b/src/agnext/chat/agents/user_proxy.py
index db6d2cde9..d856fa566 100644
--- a/src/agnext/chat/agents/user_proxy.py
+++ b/src/agnext/chat/agents/user_proxy.py
@@ -6,15 +6,27 @@ from ..types import PublishNow, TextMessage
class UserProxyAgent(TypeRoutedAgent):
+ """An agent that proxies user input from the console. Override the `get_user_input`
+ 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.
+ """
+
def __init__(self, name: str, description: str, runtime: AgentRuntime, user_input_prompt: str) -> None:
super().__init__(name, description, runtime)
self._user_input_prompt = user_input_prompt
@message_handler()
async def on_publish_now(self, message: PublishNow, cancellation_token: CancellationToken) -> None:
+ """Handle a publish now message. This method prompts the user for input, then publishes it."""
user_input = await self.get_user_input(self._user_input_prompt)
await self._publish_message(TextMessage(content=user_input, source=self.name))
async def get_user_input(self, prompt: str) -> str:
+ """Get user input from the console. Override this method to customize how user input is retrieved."""
loop = asyncio.get_event_loop()
return await loop.run_in_executor(None, input, prompt)
diff --git a/src/agnext/chat/memory/__init__.py b/src/agnext/chat/memory/__init__.py
index 0cefbdef1..162d1732e 100644
--- a/src/agnext/chat/memory/__init__.py
+++ b/src/agnext/chat/memory/__init__.py
@@ -1,5 +1,4 @@
from ._base import ChatMemory
from ._buffered import BufferedChatMemory
-from ._full import FullChatMemory
-__all__ = ["ChatMemory", "FullChatMemory", "BufferedChatMemory"]
+__all__ = ["ChatMemory", "BufferedChatMemory"]
diff --git a/src/agnext/chat/memory/_base.py b/src/agnext/chat/memory/_base.py
index f22dc9a19..d2a2a2898 100644
--- a/src/agnext/chat/memory/_base.py
+++ b/src/agnext/chat/memory/_base.py
@@ -4,11 +4,15 @@ from ..types import Message
class ChatMemory(Protocol):
- def add_message(self, message: Message) -> None: ...
+ """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."""
- def get_messages(self) -> List[Message]: ...
+ async def add_message(self, message: Message) -> None: ...
- def clear(self) -> None: ...
+ async def get_messages(self) -> List[Message]: ...
+
+ async def clear(self) -> None: ...
def save_state(self) -> Mapping[str, Any]: ...
diff --git a/src/agnext/chat/memory/_buffered.py b/src/agnext/chat/memory/_buffered.py
index 2d2110f43..449f3696d 100644
--- a/src/agnext/chat/memory/_buffered.py
+++ b/src/agnext/chat/memory/_buffered.py
@@ -1,21 +1,38 @@
from typing import Any, List, Mapping
+from ...components.models import FunctionExecutionResultMessage
from ..types import Message
from ._base import ChatMemory
class BufferedChatMemory(ChatMemory):
+ """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.
+
+ Args:
+ buffer_size (int): The size of the buffer.
+
+ """
+
def __init__(self, buffer_size: int) -> None:
self._messages: List[Message] = []
self._buffer_size = buffer_size
- def add_message(self, message: Message) -> None:
+ async def add_message(self, message: Message) -> None:
+ """Add a message to the memory."""
self._messages.append(message)
- def get_messages(self) -> List[Message]:
- return self._messages[-self._buffer_size :]
-
- def clear(self) -> None:
+ async def get_messages(self) -> List[Message]:
+ """Get at most `buffer_size` recent messages."""
+ messages = self._messages[-self._buffer_size :]
+ # Handle the first message is a function call result message.
+ if messages and isinstance(messages[0], FunctionExecutionResultMessage):
+ # Remove the first message from the list.
+ messages = messages[1:]
+ return messages
+
+ async def clear(self) -> None:
+ """Clear the message memory."""
self._messages = []
def save_state(self) -> Mapping[str, Any]:
diff --git a/src/agnext/chat/memory/_full.py b/src/agnext/chat/memory/_full.py
deleted file mode 100644
index 166f40c39..000000000
--- a/src/agnext/chat/memory/_full.py
+++ /dev/null
@@ -1,24 +0,0 @@
-from typing import Any, List, Mapping
-
-from ..types import Message
-from ._base import ChatMemory
-
-
-class FullChatMemory(ChatMemory):
- def __init__(self) -> None:
- self._messages: List[Message] = []
-
- def add_message(self, message: Message) -> None:
- self._messages.append(message)
-
- def get_messages(self) -> List[Message]:
- return self._messages
-
- def clear(self) -> None:
- self._messages = []
-
- def save_state(self) -> Mapping[str, Any]:
- return {"messages": [message for message in self._messages]}
-
- def load_state(self, state: Mapping[str, Any]) -> None:
- self._messages = state["messages"]
diff --git a/src/agnext/chat/patterns/__init__.py b/src/agnext/chat/patterns/__init__.py
index e69de29bb..49019997f 100644
--- a/src/agnext/chat/patterns/__init__.py
+++ b/src/agnext/chat/patterns/__init__.py
@@ -0,0 +1,3 @@
+from .group_chat_manager import GroupChatManager
+
+__all__ = ["GroupChatManager"]
diff --git a/src/agnext/chat/patterns/group_chat_manager.py b/src/agnext/chat/patterns/group_chat_manager.py
index 7f66f7779..c29c9fe29 100644
--- a/src/agnext/chat/patterns/group_chat_manager.py
+++ b/src/agnext/chat/patterns/group_chat_manager.py
@@ -1,4 +1,4 @@
-from typing import Callable, List
+from typing import Any, Callable, List, Mapping
from ...components import TypeRoutedAgent, message_handler
from ...components.models import ChatCompletionClient
@@ -13,6 +13,23 @@ from .group_chat_utils import select_speaker
class GroupChatManager(TypeRoutedAgent):
+ """An agent that manages a group chat through event-driven orchestration.
+
+ Args:
+ name (str): The name of the agent.
+ description (str): The description of the agent.
+ runtime (AgentRuntime): The runtime to register the agent.
+ participants (List[Agent]): The list of participants in the group chat.
+ memory (ChatMemory): 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
+ according to the order given.
+ termination_word (str, optional): The word that terminates the group chat. Defaults to "TERMINATE".
+ on_message_received (Callable[[TextMessage], None], optional): A custom handler to call when a message is received.
+ Defaults to None.
+ """
+
def __init__(
self,
name: str,
@@ -33,10 +50,13 @@ class GroupChatManager(TypeRoutedAgent):
@message_handler()
async def on_reset(self, message: Reset, cancellation_token: CancellationToken) -> None:
- self._memory.clear()
+ """Handle a reset message. This method clears the memory."""
+ await self._memory.clear()
@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, selects the next speaker,
+ and sends a message to the selected speaker to publish a response."""
# Call the custom on_message_received handler if provided.
if self._on_message_received is not None:
self._on_message_received(message)
@@ -47,7 +67,7 @@ class GroupChatManager(TypeRoutedAgent):
return
# Save the message to chat memory.
- self._memory.add_message(message)
+ await self._memory.add_message(message)
# Select speaker.
if self._client is None:
@@ -68,3 +88,13 @@ class GroupChatManager(TypeRoutedAgent):
# Send the message to the selected speaker to ask it to publish a response.
await self._send_message(PublishNow(), speaker)
+
+ def save_state(self) -> Mapping[str, Any]:
+ return {
+ "memory": self._memory.save_state(),
+ "termination_word": self._termination_word,
+ }
+
+ def load_state(self, state: Mapping[str, Any]) -> None:
+ self._memory.load_state(state["memory"])
+ self._termination_word = state["termination_word"]
diff --git a/src/agnext/chat/patterns/group_chat_utils.py b/src/agnext/chat/patterns/group_chat_utils.py
index 7bfbcc1e1..3b8a184da 100644
--- a/src/agnext/chat/patterns/group_chat_utils.py
+++ b/src/agnext/chat/patterns/group_chat_utils.py
@@ -10,11 +10,12 @@ from ..types import TextMessage
async def select_speaker(memory: ChatMemory, client: ChatCompletionClient, agents: List[Agent]) -> Agent:
+ """Selects the next speaker in a group chat using a ChatCompletion client."""
# TODO: Handle multi-modal messages.
# Construct formated current message history.
history_messages: List[str] = []
- for msg in memory.get_messages():
+ for msg in await memory.get_messages():
assert isinstance(msg, TextMessage)
history_messages.append(f"{msg.source}: {msg.content}")
history = "\n".join(history_messages)