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.pyindex 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 andfrom_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.pyindex 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_messagesclass 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_responsediff --git a/src/agnext/chat/agents/oai_assistant.py b/src/agnext/chat/agents/oai_assistant.pyindex 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, TextMessageclass 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.pyindex 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, TextMessageclass 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__.pyindex 0cefbdef1..162d1732e 100644--- a/src/agnext/chat/memory/__init__.py+++ b/src/agnext/chat/memory/__init__.py@@ -1,5 +1,4 @@from ._base import ChatMemoryfrom ._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.pyindex f22dc9a19..d2a2a2898 100644--- a/src/agnext/chat/memory/_base.py+++ b/src/agnext/chat/memory/_base.py@@ -4,11 +4,15 @@ from ..types import Messageclass 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.pyindex 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 FunctionExecutionResultMessagefrom ..types import Messagefrom ._base import ChatMemoryclass 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.pydeleted file mode 100644index 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__.pyindex 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.pyindex 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, Mappingfrom ...components import TypeRoutedAgent, message_handlerfrom ...components.models import ChatCompletionClient@@ -13,6 +13,23 @@ from .group_chat_utils import select_speakerclass 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.pyindex 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 TextMessageasync 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)