A programming framework for agentic AI
Add process_until_idle; add tests for cascading scenario. (#136)
Eric Zhu8308c928cb20
diff --git a/python/examples/README.md b/python/examples/README.mdindex a691d5c42..9c10cc34e 100644--- a/python/examples/README.md+++ b/python/examples/README.md@@ -14,7 +14,7 @@ We provide examples to illustrate the core concepts of AGNext: agents, runtime,- [`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 direct communication.- [`inner_outer_direct.py`](core/inner_outer_direct.py): A simple example of how to create an agent that calls an inner agent using direct communication.-- [`two_agents_pub_sub_termination.py`](core/two_agents_pub_sub_termination.py): An example of how to create two agents that communicate using broadcast communication (i.e., pub/sub), and termination using an intervention handler.+- [`two_agents_pub_sub.py`](core/two_agents_pub_sub.py): An example of how to create two agents that communicate using broadcast communication (i.e., pub/sub).## Tool use examplesdiff --git a/python/examples/core/two_agents_pub_sub_termination.py b/python/examples/core/two_agents_pub_sub.pysimilarity index 73%rename from python/examples/core/two_agents_pub_sub_termination.pyrename to python/examples/core/two_agents_pub_sub.pyindex 4b42fc903..e27d395c3 100644--- a/python/examples/core/two_agents_pub_sub_termination.py+++ b/python/examples/core/two_agents_pub_sub.py@@ -7,15 +7,12 @@ interaction between two agents that use a chat completion model to respond to meand publishes the response.3. The Cathy agent receives the message, generates a response using a chat completion model,and publishes the response.-4. The conversation continues until a termination message is received by any agent, which-then publishes a termination message.-5. The termination handler listens for the termination message and when it is received,-it sets the termination flag to True, and the main function terminates the process.+4. The conversation continues until a message with termination word is received by any agent."""import asynciofrom dataclasses import dataclass-from typing import Any, List+from typing import Listfrom agnext.application import SingleThreadedAgentRuntimefrom agnext.components import TypeRoutedAgent, message_handler@@ -27,8 +24,7 @@ from agnext.components.models import (SystemMessage,UserMessage,)-from agnext.core import AgentId, CancellationToken-from agnext.core.intervention import DefaultInterventionHandler+from agnext.core import CancellationToken@dataclass@@ -37,11 +33,6 @@ 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.@@ -64,7 +55,6 @@ 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:- await self.publish_message(Termination())returnllm_messages: List[LLMMessage] = []for m in self._memory[-10:]:@@ -77,28 +67,9 @@ class ChatCompletionAgent(TypeRoutedAgent):await 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:- # Create the termination handler.- termination_handler = TerminationHandler()-- # Create the runtime with the termination handler.- runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)+ # Create the runtime.+ runtime = SingleThreadedAgentRuntime()# Register the agents.jack = runtime.register_and_get(@@ -128,9 +99,8 @@ async def main() -> None:message = Message(content="Can you tell me something fun about SF?", source="User")await runtime.send_message(message, jack)- # Process messages until termination.- while not termination_handler.terminated:- await runtime.process_next()+ # Process messages.+ await runtime.process_until_idle()if __name__ == "__main__":diff --git a/python/examples/patterns/coder_executor_pub_sub.py b/python/examples/patterns/coder_executor_pub_sub.pyindex 7d97f56b3..cf74561ac 100644--- a/python/examples/patterns/coder_executor_pub_sub.py+++ b/python/examples/patterns/coder_executor_pub_sub.py@@ -10,16 +10,13 @@ executes the code block, and publishes a code execution task result message.on the result: if the task is completed, it publishes a task completion message;otherwise, it generates a new code block and publishes a code execution task message.4. The process continues until the coder agent publishes a task completion message.-5. The termination handler listens for the task completion message and when it is-received, it sets the termination flag to True, and the main function-terminates the process."""import asyncioimport reimport uuidfrom dataclasses import dataclass-from typing import Any, Dict, List+from typing import Dict, Listfrom agnext.application import SingleThreadedAgentRuntimefrom agnext.components import TypeRoutedAgent, message_handler@@ -32,8 +29,7 @@ from agnext.components.models import (SystemMessage,UserMessage,)-from agnext.core import AgentId, CancellationToken-from agnext.core.intervention import DefaultInterventionHandler+from agnext.core import CancellationToken@dataclass@@ -121,6 +117,9 @@ Reply "TERMINATE" in the end when everything is done."""if "TERMINATE" in response.content:# If the task is completed, publish a message with the completion content.await self.publish_message(TaskCompletion(content=response.content), cancellation_token=cancellation_token)+ print("--------------------")+ print("Task completed:")+ print(response.content)return# Publish the code execution task.@@ -171,31 +170,9 @@ class Executor(TypeRoutedAgent):return code_blocks-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, TaskCompletion):- self._terminated = True- print("--------------------")- print("Task completed:")- print(message.content)- return message-- @property- def terminated(self) -> bool:- return self._terminated--async def main(task: str, temp_dir: str) -> None:- # Create the termination handler.- termination_handler = TerminationHandler()-# Create the runtime with the termination handler.- runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)+ runtime = SingleThreadedAgentRuntime()# Register the agents.runtime.register("coder", lambda: Coder(model_client=OpenAIChatCompletionClient(model="gpt-4-turbo")))@@ -204,9 +181,8 @@ async def main(task: str, temp_dir: str) -> None:# Publish the task message.await runtime.publish_message(TaskMessage(content=task), namespace="default")- # Run the runtime until the termination condition is met.- while not termination_handler.terminated:- await runtime.process_next()+ # Run the runtime until no more message.+ await runtime.process_until_idle()if __name__ == "__main__":diff --git a/python/examples/patterns/coder_reviewer_pub_sub.py b/python/examples/patterns/coder_reviewer_pub_sub.pyindex 09117d3b4..b730ef8b6 100644--- a/python/examples/patterns/coder_reviewer_pub_sub.py+++ b/python/examples/patterns/coder_reviewer_pub_sub.py@@ -9,9 +9,6 @@ and publishes a code review result message.if the code is approved, it publishes a code writing result message; otherwise, it generatesa new code block and publishes a code review task message.4. The process continues until the coder agent publishes a code writing result message.-5. The termination handler listens for the code writing result message and when it is-received, it sets the termination flag to True, and the main function-terminates the process."""import asyncio@@ -19,7 +16,7 @@ import jsonimport reimport uuidfrom dataclasses import dataclass-from typing import Any, Dict, List, Union+from typing import Dict, List, Unionfrom agnext.application import SingleThreadedAgentRuntimefrom agnext.components import TypeRoutedAgent, message_handler@@ -31,8 +28,7 @@ from agnext.components.models import (SystemMessage,UserMessage,)-from agnext.core import AgentId, CancellationToken-from agnext.core.intervention import DefaultInterventionHandler+from agnext.core import CancellationToken@dataclass@@ -199,6 +195,14 @@ Code: <Your code>review=message.review,))+ print("Code Writing Result:")+ print("-" * 80)+ print(f"Task:\n{review_request.code_writing_task}")+ print("-" * 80)+ print(f"Code:\n{review_request.code}")+ print("-" * 80)+ print(f"Review:\n{message.review}")+ print("-" * 80)else:# Create a list of LLM messages to send to the model.messages: List[LLMMessage] = [*self._system_messages]@@ -240,33 +244,8 @@ Code: <Your code>return None-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, CodeWritingResult):- self._terminated = True- print("Code Writing Result:")- print("-" * 80)- print(f"Task:\n{message.task}")- print("-" * 80)- print(f"Code:\n{message.code}")- print("-" * 80)- print(f"Review:\n{message.review}")- print("-" * 80)- return message-- @property- def terminated(self) -> bool:- return self._terminated--async def main() -> None:- termination_handler = TerminationHandler()- runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)+ runtime = SingleThreadedAgentRuntime()runtime.register("ReviewerAgent",lambda: ReviewerAgent(@@ -288,9 +267,8 @@ async def main() -> None:namespace="default",)- # Keep processing messages until termination.- while not termination_handler.terminated:- await runtime.process_next()+ # Keep processing messages until idle.+ await runtime.process_until_idle()if __name__ == "__main__":diff --git a/python/examples/patterns/group_chat_pub_sub.py b/python/examples/patterns/group_chat_pub_sub.pyindex f86dcf901..4453f8547 100644--- a/python/examples/patterns/group_chat_pub_sub.py+++ b/python/examples/patterns/group_chat_pub_sub.py@@ -9,12 +9,11 @@ in a round-robin fashion and sends a request to speak message to the selected sp2. Upon receiving a request to speak message, the speaker generates a responseto the last message in the memory and publishes the response.3. The conversation continues until the specified number of rounds is reached.-The group chat manager publishes a termination message to end the conversation."""import asynciofrom dataclasses import dataclass-from typing import Any, List+from typing import Listfrom agnext.application import SingleThreadedAgentRuntimefrom agnext.components import TypeRoutedAgent, message_handler@@ -27,7 +26,6 @@ from agnext.components.models import (UserMessage,)from agnext.core import AgentId, CancellationToken-from agnext.core.intervention import DefaultInterventionHandler@dataclass@@ -105,28 +103,9 @@ class GroupChatParticipant(TypeRoutedAgent):await 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)+ runtime = SingleThreadedAgentRuntime()# Register the participants.agent1 = runtime.register_and_get(@@ -167,9 +146,8 @@ async def main() -> None:# Start the conversation.await 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()+ # Run the runtime.+ await runtime.process_until_idle()if __name__ == "__main__":diff --git a/python/examples/patterns/mixture_of_agents_pub_sub.py b/python/examples/patterns/mixture_of_agents_pub_sub.pyindex 181f98200..68be63026 100644--- a/python/examples/patterns/mixture_of_agents_pub_sub.py+++ b/python/examples/patterns/mixture_of_agents_pub_sub.py@@ -10,13 +10,12 @@ The reference agents handle each task independently and return the results to thimport asyncioimport uuidfrom dataclasses import dataclass-from typing import Any, Dict, List+from typing import Dict, Listfrom agnext.application import SingleThreadedAgentRuntimefrom agnext.components import TypeRoutedAgent, message_handlerfrom agnext.components.models import ChatCompletionClient, OpenAIChatCompletionClient, SystemMessage, UserMessage-from agnext.core import AgentId, CancellationToken-from agnext.core.intervention import DefaultInterventionHandler+from agnext.core import CancellationToken@dataclass@@ -101,28 +100,11 @@ class AggregatorAgent(TypeRoutedAgent):task_result = AggregatorTaskResult(result=response.content)await self.publish_message(task_result)self._session_results.pop(message.session_id)---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, AggregatorTaskResult):- self._terminated = True- print(f"Aggregator result: {message.result}")- return message-- @property- def terminated(self) -> bool:- return self._terminated+ print(f"Aggregator result: {response.content}")async def main() -> None:- termination_handler = TerminationHandler()- runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)+ runtime = SingleThreadedAgentRuntime()# TODO: use different models for each agent.runtime.register("ReferenceAgent1",@@ -163,9 +145,8 @@ async def main() -> None:)await runtime.publish_message(AggregatorTask(task="What are something fun to do in SF?"), namespace="default")- # Keep processing messages until termination.- while not termination_handler.terminated:- await runtime.process_next()+ # Keep processing messages.+ await runtime.process_until_idle()if __name__ == "__main__":diff --git a/python/examples/patterns/multi_agent_debate_pub_sub.py b/python/examples/patterns/multi_agent_debate_pub_sub.pyindex 2d9faddec..477e204fc 100644--- a/python/examples/patterns/multi_agent_debate_pub_sub.py+++ b/python/examples/patterns/multi_agent_debate_pub_sub.py@@ -22,7 +22,6 @@ The pattern works as follows:4. Each solver agent again use the responses from other agents to refine its response, publish a new response.5. Repeat step 4 for a fixed number of rounds. In the final round, each solver agent publish a final response.6. The aggregator agent use majority voting to aggregate the final responses from all solver agents to get the final answer, and publishes the answer.-7. The main function uses a termination handler to listen for the final answer from the aggregator agent, and prints the result.To make the connection dense, modify SolverAgent's handle_response methodto consider all neighbors' responses to use.@@ -36,7 +35,7 @@ import loggingimport reimport uuidfrom dataclasses import dataclass-from typing import Any, Dict, List+from typing import Dict, Listfrom agnext.application import SingleThreadedAgentRuntimefrom agnext.components import TypeRoutedAgent, message_handler@@ -48,8 +47,7 @@ from agnext.components.models import (SystemMessage,UserMessage,)-from agnext.core import AgentId, CancellationToken-from agnext.core.intervention import DefaultInterventionHandler+from agnext.core import CancellationTokenlogger = logging.getLogger(__name__)logger.setLevel(logging.DEBUG)@@ -199,35 +197,12 @@ class MathAggregator(TypeRoutedAgent):await self.publish_message(Answer(content=majority_answer))# Clear the responses.self._responses.pop(message.session_id)---class TerminationHandler(DefaultInterventionHandler):- """A handler that listens for termination messages."""-- def __init__(self) -> None:- self._terminated = False- self._result: Answer | None = None-- async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:- if isinstance(message, Answer):- self._terminated = True- self._result = message- return message-- @property- def terminated(self) -> bool:- return self._terminated-- @property- def result(self) -> Any:- return self._result+ print(f"Aggregated answer: {majority_answer}")async def main(question: str) -> None:- # Create the termination handler.- termination_handler = TerminationHandler()# Create the runtime.- runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)+ runtime = SingleThreadedAgentRuntime()# Register the solver agents.# Create a sparse connection: each solver agent has two neighbors.# NOTE: to create a dense connection, each solver agent should be connected to all other solver agents.@@ -269,11 +244,8 @@ async def main(question: str) -> None:# Send a math problem to the aggregator agent.await runtime.publish_message(Question(content=question), namespace="default")- # Run the runtime until termination.- while not termination_handler.terminated:- await runtime.process_next()-- print(f"Aggregator result: {termination_handler.result.content}")+ # Run the runtime.+ await runtime.process_until_idle()if __name__ == "__main__":diff --git a/python/examples/tool-use/coding_two_agent_pub_sub.py b/python/examples/tool-use/coding_two_agent_pub_sub.pyindex 0f3a663c1..e9ac1d9f0 100644--- a/python/examples/tool-use/coding_two_agent_pub_sub.py+++ b/python/examples/tool-use/coding_two_agent_pub_sub.py@@ -9,16 +9,13 @@ the results back to the tool use agent.3. The tool use agent receives the tool results, and makes an inference using the model again.4. The process continues until the inference response is not a list of function calls.5. The tool use agent publishes a final response to the user.-6. The termination handler listens for the final response message and when it is-received, it sets the termination flag to True, and the main function-terminates the process."""import asyncioimport jsonimport uuidfrom dataclasses import dataclass-from typing import Any, Dict, List+from typing import Dict, Listfrom agnext.application import SingleThreadedAgentRuntimefrom agnext.components import FunctionCall, TypeRoutedAgent, message_handler@@ -34,8 +31,7 @@ from agnext.components.models import (UserMessage,)from agnext.components.tools import PythonCodeExecutionTool, Tool-from agnext.core import AgentId, CancellationToken-from agnext.core.intervention import DefaultInterventionHandler+from agnext.core import CancellationToken@dataclass@@ -126,6 +122,7 @@ class ToolUseAgent(TypeRoutedAgent):# If the response is a string, just publish the response.response_message = AgentResponse(content=response.content)await self.publish_message(response_message)+ print(f"AI Response: {response.content}")return# Handle the response as a list of function calls.@@ -169,6 +166,7 @@ class ToolUseAgent(TypeRoutedAgent):await self.publish_message(response_message)self._tool_results.pop(message.session_id)self._tool_counter.pop(message.session_id)+ print(f"AI Response: {response.content}")return# Handle the response as a list of function calls.assert isinstance(response.content, list) and all(isinstance(item, FunctionCall) for item in response.content)@@ -179,26 +177,8 @@ class ToolUseAgent(TypeRoutedAgent):await self.publish_message(task)-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, AgentResponse):- self._terminated = True- print(f"AI Response: {message.content}")- return message-- @property- def terminated(self) -> bool:- return self._terminated--async def main() -> None:- termination_handler = TerminationHandler()- runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)+ runtime = SingleThreadedAgentRuntime()# Define the tools.tools: List[Tool] = [PythonCodeExecutionTool(@@ -222,9 +202,8 @@ async def main() -> None:UserRequest("Run the following Python code: print('Hello, World!')"), namespace="default")- # Run the runtime until termination.- while not termination_handler.terminated:- await runtime.process_next()+ # Run the runtime.+ await runtime.process_until_idle()if __name__ == "__main__":diff --git a/python/src/agnext/application/_single_threaded_agent_runtime.py b/python/src/agnext/application/_single_threaded_agent_runtime.pyindex 58140d8a9..0f624f56a 100644--- a/python/src/agnext/application/_single_threaded_agent_runtime.py+++ b/python/src/agnext/application/_single_threaded_agent_runtime.py@@ -308,6 +308,8 @@ class SingleThreadedAgentRuntime(AgentRuntime):message_envelope.future.set_result(message_envelope.message)async def process_next(self) -> None:+ """Process the next message in the queue."""+if len(self._message_queue) == 0:# Yield control to the event loop to allow other tasks to runawait asyncio.sleep(0)@@ -371,6 +373,12 @@ class SingleThreadedAgentRuntime(AgentRuntime):# Yield control to the message loop to allow other tasks to runawait asyncio.sleep(0)+ async def process_until_idle(self) -> None:+ """Process messages until there is no unprocessed message and no message currently being processed."""++ while len(self.unprocessed_messages) > 0 or self.outstanding_tasks > 0:+ await self.process_next()+def agent_metadata(self, agent: AgentId) -> AgentMetadata:return self._get_agent(agent).metadatadiff --git a/python/tests/test_runtime.py b/python/tests/test_runtime.pyindex 8a663a56e..57f28a252 100644--- a/python/tests/test_runtime.py+++ b/python/tests/test_runtime.py@@ -1,8 +1,7 @@import pytest-from agnext.application import SingleThreadedAgentRuntimefrom agnext.core import AgentId, AgentRuntime-from test_utils import LoopbackAgent, MessageType, NoopAgent+from test_utils import CascadingAgent, CascadingMessageType, LoopbackAgent, MessageType, NoopAgent@pytest.mark.asyncio@@ -23,6 +22,7 @@ async def test_agent_names_must_be_unique() -> None:_agent1 = runtime.register_and_get("name3", NoopAgent)+@pytest.mark.asyncioasync def test_register_receives_publish() -> None:runtime = SingleThreadedAgentRuntime()@@ -30,8 +30,7 @@ async def test_register_receives_publish() -> None:runtime.register("name", LoopbackAgent)await runtime.publish_message(MessageType(), namespace="default")- while len(runtime.unprocessed_messages) > 0 or runtime.outstanding_tasks > 0:- await runtime.process_next()+ await runtime.process_until_idle()# Agent in default namespace should have received the messagelong_running_agent: LoopbackAgent = runtime._get_agent(runtime.get("name")) # type: ignore@@ -41,3 +40,29 @@ async def test_register_receives_publish() -> None:other_long_running_agent: LoopbackAgent = runtime._get_agent(runtime.get("name", namespace="other")) # type: ignoreassert other_long_running_agent.num_calls == 0++async def test_register_receives_publish_cascade() -> None:+ runtime = SingleThreadedAgentRuntime()+ num_agents = 5+ num_initial_messages = 5+ max_rounds = 5+ total_num_calls_expected = 0+ for i in range(0, max_rounds):+ total_num_calls_expected += num_initial_messages * ((num_agents - 1) ** i)++ # Register agents+ for i in range(num_agents):+ runtime.register(f"name{i}", lambda: CascadingAgent(max_rounds))++ # Publish messages+ for _ in range(num_initial_messages):+ await runtime.publish_message(CascadingMessageType(round=1), namespace="default")++ # Process until idle.+ await runtime.process_until_idle()++ # Check that each agent received the correct number of messages.+ for i in range(num_agents):+ agent: CascadingAgent = runtime._get_agent(runtime.get(f"name{i}")) # type: ignore+ assert agent.num_calls == total_num_calls_expecteddiff --git a/python/tests/test_utils/__init__.py b/python/tests/test_utils/__init__.pyindex 694bc19c2..69c81039f 100644--- a/python/tests/test_utils/__init__.py+++ b/python/tests/test_utils/__init__.py@@ -9,6 +9,10 @@ from agnext.core import CancellationToken, BaseAgentclass MessageType:...+@dataclass+class CascadingMessageType:+ round: int+class LoopbackAgent(TypeRoutedAgent):def __init__(self) -> None:super().__init__("A loop back agent.")@@ -20,9 +24,24 @@ class LoopbackAgent(TypeRoutedAgent):self.num_calls += 1return message++class CascadingAgent(TypeRoutedAgent):++ def __init__(self, max_rounds: int) -> None:+ super().__init__("A cascading agent.")+ self.num_calls = 0+ self.max_rounds = max_rounds++ @message_handler+ async def on_new_message(self, message: CascadingMessageType, cancellation_token: CancellationToken) -> None:+ self.num_calls += 1+ if message.round == self.max_rounds:+ return+ await self.publish_message(CascadingMessageType(round=message.round + 1))+class NoopAgent(BaseAgent):def __init__(self) -> None:super().__init__("A no op agent", [])async def on_message(self, message: Any, cancellation_token: CancellationToken) -> Any:- raise NotImplementedError\ No newline at end of file+ raise NotImplementedError