A programming framework for agentic AI
Add group chat pattern, create separate folder for patterns (#117)
Eric Zhu1e49aee8fcd5
diff --git a/python/examples/README.md b/python/examples/README.mdindex 44762c1ff..862be9537 100644--- a/python/examples/README.md+++ b/python/examples/README.md@@ -9,11 +9,7 @@ agents, runtime, and message passing APIs.- [`one_agent_direct.py`](core/one_agent_direct.py): A simple example of how to create a single agent powered by ChatCompletion model client. Communicate with the agent using async direct messaging API.- [`inner_outer_direct.py`](core/inner_outer_direct.py): A simple example of how to create an agent that calls an inner agent using async direct messaging API.-- [`two_agents_pub_sub.py`](core/two_agents_pub_sub.py): An example of how to create two agents that communicate using publish-subscribe API.-- [`mixture_of_agents_direct.py`](core/mixture_of_agents_direct.py): An example of how to create a [mixture of agents](https://github.com/togethercomputer/moa) that communicate using async direct messaging API.-- [`mixture_of_agents_pub_sub.py`](core/mixture_of_agents_pub_sub.py): An example of how to create a [mixture of agents](https://github.com/togethercomputer/moa) that communicate using publish-subscribe API.-- [`coder_reviewer_direct.py`](core/coder_reviewer_direct.py): An example of how to create a coder-reviewer reflection pattern using async direct messaging API.-- [`coder_reviewer_pub_sub.py`](core/coder_reviewer_pub_sub.py): An example of how to create a coder-reviewer reflection pattern using publish-subscribe API.+- [`two_agents_pub_sub_termination.py`](core/two_agents_pub_sub_termination.py): An example of how to create two agents that communicate using publish-subscribe API, and termination using an intervention handler.## Tool use examples@@ -24,6 +20,16 @@ We provide examples to illustrate how to use tools in AGNext:- [`coding_two_agent_pub_sub.py`](tool-use/coding_two_agent_pub_sub.py): a code execution example with two agents, one for calling tool and one for executing the tool, to demonstrate tool use and reflection on tool use. This example uses the publish-subscribe API.- [`custom_function_tool_one_agent_direct.py`](tool-use/custom_function_tool_one_agent_direct.py): a custom function tool example with one agent that calls and executes tools to demonstrate tool use and reflection on tool use. This example uses the async direct messaging API.+## Pattern examples++We provide examples to illustrate how multi-agent patterns can be implemented in AGNext:++- [`mixture_of_agents_direct.py`](pattern/mixture_of_agents_direct.py): An example of how to create a [mixture of agents](https://github.com/togethercomputer/moa) that communicate using async direct messaging API.+- [`mixture_of_agents_pub_sub.py`](pattern/mixture_of_agents_pub_sub.py): An example of how to create a [mixture of agents](https://github.com/togethercomputer/moa) that communicate using publish-subscribe API.+- [`coder_reviewer_direct.py`](pattern/coder_reviewer_direct.py): An example of how to create a coder-reviewer reflection pattern using async direct messaging API.+- [`coder_reviewer_pub_sub.py`](pattern/coder_reviewer_pub_sub.py): An example of how to create a coder-reviewer reflection pattern using publish-subscribe API.+- [`group_chat_pub_sub.py`](pattern/group_chat_pub_sub.py): An example of how to create a round-robin group chat among three agents using publish-subscribe API.+## DemosWe provide interactive demos that showcase applications that can be built using AGNext:diff --git a/python/examples/core/two_agents_pub_sub.py b/python/examples/core/two_agents_pub_sub_termination.pysimilarity index 73%rename from python/examples/core/two_agents_pub_sub.pyrename to python/examples/core/two_agents_pub_sub_termination.pyindex 6b8a28585..3db1ed526 100644--- a/python/examples/core/two_agents_pub_sub.py+++ b/python/examples/core/two_agents_pub_sub_termination.py@@ -1,6 +1,6 @@import asynciofrom dataclasses import dataclass-from typing import List+from typing import Any, Listfrom agnext.application import SingleThreadedAgentRuntimefrom agnext.components import TypeRoutedAgent, message_handler@@ -12,7 +12,8 @@ from agnext.components.models import (SystemMessage,UserMessage,)-from agnext.core import CancellationToken+from agnext.core import AgentId, CancellationToken+from agnext.core.intervention import DefaultInterventionHandler@dataclass@@ -21,10 +22,15 @@ class Message:content: str+@dataclass+class Termination:+ pass++class ChatCompletionAgent(TypeRoutedAgent):"""An agent that uses a chat completion model to respond to messages.It keeps a memory of the conversation and uses it to generate responses.- It terminates the conversation when the termination word is mentioned."""+ It publishes a termination message when the termination word is mentioned."""def __init__(self,@@ -43,6 +49,7 @@ class ChatCompletionAgent(TypeRoutedAgent):async def handle_message(self, message: Message, cancellation_token: CancellationToken) -> None:self._memory.append(message)if self._termination_word in message.content:+ self.publish_message(Termination())returnllm_messages: List[LLMMessage] = []for m in self._memory[-10:]:@@ -55,8 +62,30 @@ class ChatCompletionAgent(TypeRoutedAgent):self.publish_message(Message(content=response.content, source=self.metadata["name"]))+class TerminationHandler(DefaultInterventionHandler):+ """A handler that listens for termination messages."""++ def __init__(self) -> None:+ self._terminated = False++ async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:+ if isinstance(message, Termination):+ self._terminated = True+ return message++ @property+ def terminated(self) -> bool:+ return self._terminated++async def main() -> None:- runtime = SingleThreadedAgentRuntime()+ # Create the termination handler.+ termination_handler = TerminationHandler()++ # Create the runtime with the termination handler.+ runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)++ # Register the agents.jack = runtime.register_and_get("Jack",lambda: ChatCompletionAgent(@@ -84,8 +113,8 @@ async def main() -> None:message = Message(content="Can you tell me something fun about SF?", source="User")runtime.send_message(message, jack)- # Process messages until the agent responds.- while True:+ # Process messages until termination.+ while not termination_handler.terminated:await runtime.process_next()diff --git a/python/examples/core/coder_reviewer_direct.py b/python/examples/patterns/coder_reviewer_direct.pysimilarity index 100%rename from python/examples/core/coder_reviewer_direct.pyrename to python/examples/patterns/coder_reviewer_direct.pydiff --git a/python/examples/core/coder_reviewer_pub_sub.py b/python/examples/patterns/coder_reviewer_pub_sub.pysimilarity index 100%rename from python/examples/core/coder_reviewer_pub_sub.pyrename to python/examples/patterns/coder_reviewer_pub_sub.pydiff --git a/python/examples/patterns/group_chat_pub_sub.py b/python/examples/patterns/group_chat_pub_sub.pynew file mode 100644index 000000000..58666d6c4--- /dev/null+++ b/python/examples/patterns/group_chat_pub_sub.py@@ -0,0 +1,166 @@+import asyncio+from dataclasses import dataclass+from typing import Any, List++from agnext.application import SingleThreadedAgentRuntime+from agnext.components import TypeRoutedAgent, message_handler+from agnext.components.models import (+ AssistantMessage,+ ChatCompletionClient,+ LLMMessage,+ OpenAI,+ SystemMessage,+ UserMessage,+)+from agnext.core import AgentId, CancellationToken+from agnext.core.intervention import DefaultInterventionHandler+++@dataclass+class Message:+ source: str+ content: str+++@dataclass+class RequestToSpeak:+ pass+++@dataclass+class Termination:+ pass+++class RoundRobinGroupChatManager(TypeRoutedAgent):+ def __init__(+ self,+ description: str,+ participants: List[AgentId],+ num_rounds: int,+ ) -> None:+ super().__init__(description)+ self._participants = participants+ self._num_rounds = num_rounds+ self._round_count = 0++ @message_handler+ async def handle_message(self, message: Message, cancellation_token: CancellationToken) -> None:+ # Select the next speaker in a round-robin fashion+ speaker = self._participants[self._round_count % len(self._participants)]+ self._round_count += 1+ if self._round_count == self._num_rounds * len(self._participants):+ # End the conversation after the specified number of rounds.+ self.publish_message(Termination())+ return+ # Send a request to speak message to the selected speaker.+ self.send_message(RequestToSpeak(), speaker)+++class GroupChatParticipant(TypeRoutedAgent):+ def __init__(+ self,+ description: str,+ system_messages: List[SystemMessage],+ model_client: ChatCompletionClient,+ ) -> None:+ super().__init__(description)+ self._system_messages = system_messages+ self._model_client = model_client+ self._memory: List[Message] = []++ @message_handler+ async def handle_message(self, message: Message, cancellation_token: CancellationToken) -> None:+ self._memory.append(message)++ @message_handler+ async def handle_request_to_speak(self, message: RequestToSpeak, cancellation_token: CancellationToken) -> None:+ # Generate a response to the last message in the memory+ if not self._memory:+ return+ llm_messages: List[LLMMessage] = []+ for m in self._memory[-10:]:+ if m.source == self.metadata["name"]:+ llm_messages.append(AssistantMessage(content=m.content, source=self.metadata["name"]))+ else:+ llm_messages.append(UserMessage(content=m.content, source=m.source))+ response = await self._model_client.create(self._system_messages + llm_messages)+ assert isinstance(response.content, str)+ speach = Message(content=response.content, source=self.metadata["name"])+ self._memory.append(speach)+ self.publish_message(speach)+++class TerminationHandler(DefaultInterventionHandler):+ """A handler that listens for termination messages."""++ def __init__(self) -> None:+ self._terminated = False++ async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:+ if isinstance(message, Termination):+ self._terminated = True+ return message++ @property+ def terminated(self) -> bool:+ return self._terminated+++async def main() -> None:+ # Create the termination handler.+ termination_handler = TerminationHandler()++ # Create the runtime.+ runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)++ # Register the participants.+ agent1 = runtime.register_and_get(+ "DataScientist",+ lambda: GroupChatParticipant(+ description="A data scientist",+ system_messages=[SystemMessage("You are a data scientist.")],+ model_client=OpenAI(model="gpt-3.5-turbo"),+ ),+ )+ agent2 = runtime.register_and_get(+ "Engineer",+ lambda: GroupChatParticipant(+ description="An engineer",+ system_messages=[SystemMessage("You are an engineer.")],+ model_client=OpenAI(model="gpt-3.5-turbo"),+ ),+ )+ agent3 = runtime.register_and_get(+ "Artist",+ lambda: GroupChatParticipant(+ description="An artist",+ system_messages=[SystemMessage("You are an artist.")],+ model_client=OpenAI(model="gpt-3.5-turbo"),+ ),+ )++ # Register the group chat manager.+ runtime.register(+ "GroupChatManager",+ lambda: RoundRobinGroupChatManager(+ description="A group chat manager",+ participants=[agent1, agent2, agent3],+ num_rounds=3,+ ),+ )++ # Start the conversation.+ runtime.publish_message(Message(content="Hello, everyone!", source="Moderator"), namespace="default")++ # Run the runtime until termination.+ while not termination_handler.terminated:+ await runtime.process_next()+++if __name__ == "__main__":+ import logging++ logging.basicConfig(level=logging.WARNING)+ logging.getLogger("agnext").setLevel(logging.DEBUG)+ asyncio.run(main())diff --git a/python/examples/core/mixture_of_agents_direct.py b/python/examples/patterns/mixture_of_agents_direct.pysimilarity index 100%rename from python/examples/core/mixture_of_agents_direct.pyrename to python/examples/patterns/mixture_of_agents_direct.pydiff --git a/python/examples/core/mixture_of_agents_pub_sub.py b/python/examples/patterns/mixture_of_agents_pub_sub.pysimilarity index 100%rename from python/examples/core/mixture_of_agents_pub_sub.pyrename to python/examples/patterns/mixture_of_agents_pub_sub.py