A programming framework for agentic AI
Add coder-executor example; document the examples; clarify pub-sub as broadcast communication (#132)
Eric Zhu6d149fe728da
diff --git a/python/docs/src/core-concepts/agent.md b/python/docs/src/core-concepts/agent.mdindex 605d82d52..f5655fe95 100644--- a/python/docs/src/core-concepts/agent.md+++ b/python/docs/src/core-concepts/agent.md@@ -40,8 +40,8 @@ An important part of designing an agent or choosing which agents to use is underThere are two forms of communication in AGNext:-- **Direct communication**: An agent sends a message to another agent.-- **Broadcast communication**: An agent publishes a message to all agents.+- **Direct communication**: An agent sends a direct message to another agent.+- **Broadcast communication**: An agent publishes a message to all agents in the same namespace.### Message Handling@@ -55,7 +55,8 @@ To send a message to an agent outside of agent handling a message the message sh### Broadcast Communication-As part of the agent's implementation it must advertise the message types that it would like to receive when published ({py:attr}`agnext.core.Agent.subscriptions`). If one of these messages is published, the agent's message handler will be invoked. The key difference between direct and broadcast communication is that broadcast communication is not a request/response pattern. When an agent publishes a message it is one way, it is not expecting a response from any other agent. In fact, they cannot respond to the message.+Broadcast communication is effectively the publish-subscribe model.+As part of the agent's implementation it must advertise the message types that it would like to receive when published ({py:attr}`agnext.core.Agent.subscriptions`). If one of these messages is published, the agent's message handler will be invoked. The key difference between direct and broadcast communication is that broadcast communication is not a request/response model. When an agent publishes a message it is one way, it is not expecting a response from any other agent. In fact, they cannot respond to the message.To publish a message to all agents, use the {py:meth}`agnext.core.BaseAgent.publish_message` method. This call must still be awaited to allow the runtime to deliver the message to all agents, but it will always return `None`. If an agent raises an exception while handling a published message, this will be logged but will not be propagated back to the publishing agent.diff --git a/python/examples/README.md b/python/examples/README.mdindex d1bf676ec..568b7974c 100644--- a/python/examples/README.md+++ b/python/examples/README.md@@ -10,31 +10,30 @@ This directory contains examples and demos of how to use AGNext.## Core examples-We provide examples to illustrate the core concepts of AGNext:-agents, runtime, and message passing APIs.+We provide examples to illustrate the core concepts of AGNext: agents, runtime, and message passing.-- [`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_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.+- [`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.## Tool use examplesWe provide examples to illustrate how to use tools in AGNext:-- [`coding_one_agent_direct.py`](tool-use/coding_one_agent_direct.py): a code execution 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.-- [`coding_two_agent_direct.py`](tool-use/coding_two_agent_direct.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 async direct messaging API.-- [`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.+- [`coding_one_agent_direct.py`](tool-use/coding_one_agent_direct.py): a code execution example with one agent that calls and executes tools to demonstrate tool use and reflection on tool use. This example uses direct communication.+- [`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 broadcast communication.+- [`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 direct communication.## Pattern examplesWe provide examples to illustrate how multi-agent patterns can be implemented in AGNext:-- [`mixture_of_agents_direct.py`](patterns/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`](patterns/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`](patterns/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`](patterns/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`](patterns/group_chat_pub_sub.py): An example of how to create a round-robin group chat among three agents using publish-subscribe API.+- [`coder_executor_pub_sub.py`](patterns/coder_executor_pub_sub.py): An example of how to create a coder-executor reflection pattern using broadcast communication. This example creates a plot of stock prices using the Yahoo Finance API.+- [`coder_reviewer_direct.py`](patterns/coder_reviewer_direct.py): An example of how to create a coder-reviewer reflection pattern using direct communication.+- [`coder_reviewer_pub_sub.py`](patterns/coder_reviewer_pub_sub.py): An example of how to create a coder-reviewer reflection pattern using broadcast communication.+- [`group_chat_pub_sub.py`](patterns/group_chat_pub_sub.py): An example of how to create a round-robin group chat among three agents using broadcast communication.+- [`mixture_of_agents_direct.py`](patterns/mixture_of_agents_direct.py): An example of how to create a [mixture of agents](https://github.com/togethercomputer/moa) using direct communication.+- [`mixture_of_agents_pub_sub.py`](patterns/mixture_of_agents_pub_sub.py): An example of how to create a [mixture of agents](https://github.com/togethercomputer/moa) using broadcast communication.## Demosdiff --git a/python/examples/core/inner_outer_direct.py b/python/examples/core/inner_outer_direct.pyindex 63daa7b6b..c657aa3a3 100644--- a/python/examples/core/inner_outer_direct.py+++ b/python/examples/core/inner_outer_direct.py@@ -1,3 +1,11 @@+"""+This example shows how to use direct messaging to implement+a simple interaction between an inner and an outer agent.+1. The outer agent receives a message, sends a message to the inner agent.+2. The inner agent receives the message, processes it, and sends a response to the outer agent.+3. The outer agent receives the response and processes it, and returns the final response.+"""+import asyncioimport loggingfrom dataclasses import dataclassdiff --git a/python/examples/core/one_agent_direct.py b/python/examples/core/one_agent_direct.pyindex 61ad4706d..576f04eda 100644--- a/python/examples/core/one_agent_direct.py+++ b/python/examples/core/one_agent_direct.py@@ -1,3 +1,10 @@+"""+This example shows how to use direct messaging to implement+a simple chat completion agent.+The agent receives a message from the main function, sends it to the+chat completion model, and returns the response to the main function.+"""+import asynciofrom dataclasses import dataclassdiff --git a/python/examples/core/two_agents_pub_sub_termination.py b/python/examples/core/two_agents_pub_sub_termination.pyindex 31da9136f..05a0e68f6 100644--- a/python/examples/core/two_agents_pub_sub_termination.py+++ b/python/examples/core/two_agents_pub_sub_termination.py@@ -1,3 +1,18 @@+"""+This example shows how to use publish-subscribe to implement a simple+interaction between two agents that use a chat completion model to respond to messages.++1. The main function sends a message to Jack to start the conversation.+2. The Jack agent receives the message, generates a response using a chat completion model,+and 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.+"""+import asynciofrom dataclasses import dataclassfrom typing import Any, Listdiff --git a/python/examples/patterns/coder_executor_pub_sub.py b/python/examples/patterns/coder_executor_pub_sub.pynew file mode 100644index 000000000..27a4b4960--- /dev/null+++ b/python/examples/patterns/coder_executor_pub_sub.py@@ -0,0 +1,221 @@+"""+This example shows how to use publish-subscribe to implement+a simple interaction between a coder and an executor agent.+1. The coder agent receives a task message, generates a code block,+and publishes a code execution+task message.+2. The executor agent receives the code execution task message,+executes the code block, and publishes a code execution task result message.+3. The coder agent receives the code execution task result message, depending+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 asyncio+import re+import uuid+from dataclasses import dataclass+from typing import Any, Dict, List++from agnext.application import SingleThreadedAgentRuntime+from agnext.components import TypeRoutedAgent, message_handler+from agnext.components.code_executor import CodeBlock, CodeExecutor, LocalCommandLineCodeExecutor+from agnext.components.models import (+ AssistantMessage,+ ChatCompletionClient,+ LLMMessage,+ OpenAIChatCompletionClient,+ SystemMessage,+ UserMessage,+)+from agnext.core import AgentId, CancellationToken+from agnext.core.intervention import DefaultInterventionHandler+++@dataclass+class TaskMessage:+ content: str+++@dataclass+class TaskCompletion:+ content: str+++@dataclass+class CodeExecutionTask:+ session_id: str+ content: str+++@dataclass+class CodeExecutionTaskResult:+ session_id: str+ output: str+ exit_code: int+++class Coder(TypeRoutedAgent):+ """An agent that writes code."""++ def __init__(+ self,+ model_client: ChatCompletionClient,+ ) -> None:+ super().__init__(description="A Python coder assistant.")+ self._model_client = model_client+ self._system_messages = [+ SystemMessage(+ """You are a helpful AI assistant.+Solve tasks using your coding and language skills.+In the following cases, suggest python code (in a python coding block) or shell script (in a sh coding block) for the user to execute.+ 1. When you need to collect info, use the code to output the info you need, for example, browse or search the web, download/read a file, print the content of a webpage or a file, get the current date/time, check the operating system. After sufficient info is printed and the task is ready to be solved based on your language skill, you can solve the task by yourself.+ 2. When you need to perform some task with code, use the code to perform the task and output the result. Finish the task smartly.+Solve the task step by step if you need to. If a plan is not provided, explain your plan first. Be clear which step uses code, and which step uses your language skill.+When using code, you must indicate the script type in the code block. The user cannot provide any other feedback or perform any other action beyond executing the code you suggest. The user can't modify your code. So do not suggest incomplete code which requires users to modify. Don't use a code block if it's not intended to be executed by the user.+If you want the user to save the code in a file before executing it, put # filename: <filename> inside the code block as the first line. Don't include multiple code blocks in one response. Do not ask users to copy and paste the result. Instead, use 'print' function for the output when relevant. Check the execution result returned by the user.+If the result indicates there is an error, fix the error and output the code again. Suggest the full code instead of partial code or code changes. If the error can't be fixed or if the task is not solved even after the code is executed successfully, analyze the problem, revisit your assumption, collect additional info you need, and think of a different approach to try.+When you find an answer, verify the answer carefully. Include verifiable evidence in your response if possible.+Reply "TERMINATE" in the end when everything is done."""+ )+ ]+ # A dictionary to store the messages for each task session.+ self._session_memory: Dict[str, List[LLMMessage]] = {}++ @message_handler+ async def handle_task(self, message: TaskMessage, cancellation_token: CancellationToken) -> None:+ # Create a new session.+ session_id = str(uuid.uuid4())+ self._session_memory.setdefault(session_id, []).append(UserMessage(content=message.content, source="user"))++ # Make an inference to the model.+ response = await self._model_client.create(self._system_messages + self._session_memory[session_id])+ assert isinstance(response.content, str)+ self._session_memory[session_id].append(+ AssistantMessage(content=response.content, source=self.metadata["name"])+ )++ # Publish the code execution task.+ self.publish_message(+ CodeExecutionTask(content=response.content, session_id=session_id), cancellation_token=cancellation_token+ )++ @message_handler+ async def handle_code_execution_result(+ self, message: CodeExecutionTaskResult, cancellation_token: CancellationToken+ ) -> None:+ # Store the code execution output.+ self._session_memory[message.session_id].append(UserMessage(content=message.output, source="user"))++ # Make an inference to the model -- reflection on the code execution output happens here.+ response = await self._model_client.create(self._system_messages + self._session_memory[message.session_id])+ assert isinstance(response.content, str)+ self._session_memory[message.session_id].append(+ AssistantMessage(content=response.content, source=self.metadata["name"])+ )++ if "TERMINATE" in response.content:+ # If the task is completed, publish a message with the completion content.+ self.publish_message(TaskCompletion(content=response.content), cancellation_token=cancellation_token)+ return++ # Publish the code execution task.+ self.publish_message(+ CodeExecutionTask(content=response.content, session_id=message.session_id),+ cancellation_token=cancellation_token,+ )+++class Executor(TypeRoutedAgent):+ """An agent that executes code."""++ def __init__(self, executor: CodeExecutor) -> None:+ super().__init__(description="A code executor agent.")+ self._executor = executor++ @message_handler+ async def handle_code_execution(self, message: CodeExecutionTask, cancellation_token: CancellationToken) -> None:+ # Extract the code block from the message.+ code_blocks = self._extract_code_blocks(message.content)+ if not code_blocks:+ # If no code block is found, publish a message with an error.+ self.publish_message(+ CodeExecutionTaskResult(+ output="Error: no Markdown code block found.", exit_code=1, session_id=message.session_id+ ),+ cancellation_token=cancellation_token,+ )+ return+ # Execute code blocks.+ future = asyncio.get_event_loop().run_in_executor(None, self._executor.execute_code_blocks, code_blocks)+ cancellation_token.link_future(future)+ result = await future+ # Publish the code execution result.+ self.publish_message(+ CodeExecutionTaskResult(output=result.output, exit_code=result.exit_code, session_id=message.session_id),+ cancellation_token=cancellation_token,+ )++ def _extract_code_blocks(self, markdown_text: str) -> List[CodeBlock]:+ pattern = re.compile(r"```(?:\s*([\w\+\-]+))?\n([\s\S]*?)```")+ matches = pattern.findall(markdown_text)+ code_blocks: List[CodeBlock] = []+ for match in matches:+ language = match[0].strip() if match[0] else ""+ code_content = match[1]+ code_blocks.append(CodeBlock(code=code_content, language=language))+ 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)++ # Register the agents.+ runtime.register("coder", lambda: Coder(model_client=OpenAIChatCompletionClient(model="gpt-4-turbo")))+ runtime.register("executor", lambda: Executor(executor=LocalCommandLineCodeExecutor(work_dir=temp_dir)))++ # Publish the task message.+ 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()+++if __name__ == "__main__":+ import logging+ from datetime import datetime++ logging.basicConfig(level=logging.WARNING)+ logging.getLogger("agnext").setLevel(logging.DEBUG)++ task = f"Today is {datetime.today()}, create a plot of NVDA and TSLA stock prices YTD using yfinance."++ asyncio.run(main(task, "."))diff --git a/python/examples/patterns/coder_reviewer_direct.py b/python/examples/patterns/coder_reviewer_direct.pyindex 9203c7e4c..d10b61f61 100644--- a/python/examples/patterns/coder_reviewer_direct.py+++ b/python/examples/patterns/coder_reviewer_direct.py@@ -1,3 +1,17 @@+"""+This example shows how to use direct messaging to implement+a simple interaction between a coder and a reviewer agent.+1. The coder agent receives a code writing task message, generates a code block,+and sends a code review task message to the reviewer agent.+2. The reviewer agent receives the code review task message, reviews the code block,+and sends a code review result message to the coder agent.+3. The coder agent receives the code review result message, depending on the result:+if the code is approved, it sends a code writing result message; otherwise, it generates+a new code block and sends a code review task message.+4. The process continues until the coder agent receives an approved code review result message.+5. The main function prints the code writing result.+"""+import asyncioimport jsonimport rediff --git a/python/examples/patterns/coder_reviewer_pub_sub.py b/python/examples/patterns/coder_reviewer_pub_sub.pyindex dde558978..d6f18ce7b 100644--- a/python/examples/patterns/coder_reviewer_pub_sub.py+++ b/python/examples/patterns/coder_reviewer_pub_sub.py@@ -1,3 +1,19 @@+"""+This example shows how to use publish-subscribe to implement+a simple interaction between a coder and a reviewer agent.+1. The coder agent receives a code writing task message, generates a code block,+and publishes a code review task message.+2. The reviewer agent receives the code review task message, reviews the code block,+and publishes a code review result message.+3. The coder agent receives the code review result message, depending on the result:+if the code is approved, it publishes a code writing result message; otherwise, it generates+a 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 asyncioimport jsonimport re@@ -46,11 +62,6 @@ class CodeReviewResult:approved: bool-@dataclass-class Termination:- pass--class ReviewerAgent(TypeRoutedAgent):"""An agent that performs code review tasks."""@@ -236,8 +247,16 @@ class TerminationHandler(DefaultInterventionHandler):self._terminated = Falseasync def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:- if isinstance(message, Termination):+ 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@@ -245,26 +264,6 @@ class TerminationHandler(DefaultInterventionHandler):return self._terminated-class DisplayAgent(TypeRoutedAgent):- """An agent that displays code writing result to the console and- publishes termination message."""-- @message_handler- async def handle_code_writing_result(- self, message: CodeWritingResult, cancellation_token: CancellationToken- ) -> None:- 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)- # Publish a termination message to the runtime.- self.publish_message(Termination())--async def main() -> None:termination_handler = TerminationHandler()runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)@@ -282,10 +281,6 @@ async def main() -> None:model_client=OpenAIChatCompletionClient(model="gpt-3.5-turbo"),),)- runtime.register(- "DisplayAgent",- lambda: DisplayAgent(description="Display Agent"),- )runtime.publish_message(message=CodeWritingTask(task="Write a function to find the directory with the largest number of files using multi-processing."diff --git a/python/examples/patterns/group_chat_pub_sub.py b/python/examples/patterns/group_chat_pub_sub.pyindex cc70026e2..74da99ad0 100644--- a/python/examples/patterns/group_chat_pub_sub.py+++ b/python/examples/patterns/group_chat_pub_sub.py@@ -1,3 +1,17 @@+"""+This example shows how to use publish-subscribe to implement+a simple round-robin group chat among multiple agents:+each agent in the group chat takes turns speaking in a round-robin fashion.+The conversation ends after a specified number of rounds.++1. Upon receiving a message, the group chat manager selects the next speaker+in a round-robin fashion and sends a request to speak message to the selected speaker.+2. Upon receiving a request to speak message, the speaker generates a response+to 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 dataclassfrom typing import Any, Listdiff --git a/python/examples/patterns/mixture_of_agents_direct.py b/python/examples/patterns/mixture_of_agents_direct.pyindex 84774fd23..bc8c8e3f5 100644--- a/python/examples/patterns/mixture_of_agents_direct.py+++ b/python/examples/patterns/mixture_of_agents_direct.py@@ -1,6 +1,12 @@-"""This example demonstrates the mixture of agents implemented using direct+"""+This example demonstrates the mixture of agents implemented using directmessaging and async gathering of results.-Mixture of agents: https://github.com/togethercomputer/moa"""+Mixture of agents: https://github.com/togethercomputer/moa++The example consists of two types of agents: reference agents and an aggregator agent.+The aggregator agent distributes tasks to reference agents and aggregates the results.+The reference agents handle each task independently and return the results to the aggregator agent.+"""import asynciofrom dataclasses import dataclassdiff --git a/python/examples/patterns/mixture_of_agents_pub_sub.py b/python/examples/patterns/mixture_of_agents_pub_sub.pyindex 5cebb60eb..181f98200 100644--- a/python/examples/patterns/mixture_of_agents_pub_sub.py+++ b/python/examples/patterns/mixture_of_agents_pub_sub.py@@ -1,5 +1,11 @@-"""This example demonstrates the mixture of agents implemented using pub/sub messaging.-Mixture of agents: https://github.com/togethercomputer/moa"""+"""+This example demonstrates the mixture of agents implemented using pub/sub.+Mixture of agents: https://github.com/togethercomputer/moa++The example consists of two types of agents: reference agents and an aggregator agent.+The aggregator agent distributes tasks to reference agents and aggregates the results.+The reference agents handle each task independently and return the results to the aggregator agent.+"""import asyncioimport uuid@@ -35,11 +41,6 @@ class AggregatorTaskResult:result: str-@dataclass-class Termination:- pass--class ReferenceAgent(TypeRoutedAgent):"""The reference agent that handles each task independently."""@@ -109,8 +110,9 @@ class TerminationHandler(DefaultInterventionHandler):self._terminated = Falseasync def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:- if isinstance(message, Termination):+ if isinstance(message, AggregatorTaskResult):self._terminated = True+ print(f"Aggregator result: {message.result}")return message@property@@ -118,19 +120,6 @@ class TerminationHandler(DefaultInterventionHandler):return self._terminated-class DisplayAgent(TypeRoutedAgent):- """An agent that displays code writing result to the console and- publishes a termination message to the runtime."""-- @message_handler- async def handle_code_writing_result(- self, message: AggregatorTaskResult, cancellation_token: CancellationToken- ) -> None:- print("Aggregator Task Result:", message.result)- # Terminate the runtime.- await self.publish_message(Termination())--async def main() -> None:termination_handler = TerminationHandler()runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)@@ -172,10 +161,6 @@ async def main() -> None:num_references=3,),)- runtime.register(- "DisplayAgent",- lambda: DisplayAgent(description="Display Agent"),- )await runtime.publish_message(AggregatorTask(task="What are something fun to do in SF?"), namespace="default")# Keep processing messages until termination.diff --git a/python/examples/tool-use/coding_one_agent_direct.py b/python/examples/tool-use/coding_one_agent_direct.pyindex a0d318a5c..f2739d3bb 100644--- a/python/examples/tool-use/coding_one_agent_direct.py+++ b/python/examples/tool-use/coding_one_agent_direct.py@@ -1,3 +1,15 @@+"""+This example implements a tool-enabled agent that uses tools to perform tasks.+1. The agent receives a user message, and makes an inference using a model.+If the response is a list of function calls, the agent executes the tools by+sending tool execution task to itself.+2. The agent executes the tools and sends the results back to itself, and+makes an inference using the model again.+3. The agent keeps executing the tools until the inference response is not a+list of function calls.+4. The agent returns the final response to the user.+"""+import asyncioimport jsonfrom dataclasses import dataclassdiff --git a/python/examples/tool-use/coding_two_agent_direct.py b/python/examples/tool-use/coding_two_agent_direct.pydeleted file mode 100644index 1e3dbedf7..000000000--- a/python/examples/tool-use/coding_two_agent_direct.py+++ /dev/null@@ -1,160 +0,0 @@-import asyncio-import json-from dataclasses import dataclass-from typing import List--from agnext.application import SingleThreadedAgentRuntime-from agnext.components import FunctionCall, TypeRoutedAgent, message_handler-from agnext.components.code_executor import LocalCommandLineCodeExecutor-from agnext.components.models import (- AssistantMessage,- ChatCompletionClient,- FunctionExecutionResult,- FunctionExecutionResultMessage,- LLMMessage,- OpenAIChatCompletionClient,- SystemMessage,- UserMessage,-)-from agnext.components.tools import PythonCodeExecutionTool, Tool-from agnext.core import AgentId, CancellationToken---@dataclass-class ToolExecutionTask:- function_call: FunctionCall---@dataclass-class ToolExecutionTaskResult:- result: FunctionExecutionResult---@dataclass-class UserRequest:- content: str---@dataclass-class AIResponse:- content: str---class ToolExecutorAgent(TypeRoutedAgent):- """An agent that executes tools."""-- def __init__(self, description: str, tools: List[Tool]) -> None:- super().__init__(description)- self._tools = tools-- @message_handler- async def handle_tool_call(- self, message: ToolExecutionTask, cancellation_token: CancellationToken- ) -> ToolExecutionTaskResult:- """Handle a tool execution task. This method executes the tool and publishes the result."""- # Find the tool- tool = next((tool for tool in self._tools if tool.name == message.function_call.name), None)- if tool is None:- result_as_str = f"Error: Tool not found: {message.function_call.name}"- else:- try:- arguments = json.loads(message.function_call.arguments)- result = await tool.run_json(args=arguments, cancellation_token=cancellation_token)- result_as_str = tool.return_value_as_string(result)- except json.JSONDecodeError:- result_as_str = f"Error: Invalid arguments: {message.function_call.arguments}"- except Exception as e:- result_as_str = f"Error: {e}"- return ToolExecutionTaskResult(- result=FunctionExecutionResult(content=result_as_str, call_id=message.function_call.id),- )---class ToolUserAgent(TypeRoutedAgent):- """An agent that uses tools to perform tasks. It doesn't execute the tools- by itself, but delegates the execution to ToolExecutorAgent using direct- messaging."""-- def __init__(- self,- description: str,- system_messages: List[SystemMessage],- model_client: ChatCompletionClient,- tools: List[Tool],- tool_executor: AgentId,- ) -> None:- super().__init__(description)- self._model_client = model_client- self._system_messages = system_messages- self._tools = tools- self._tool_executor = tool_executor-- @message_handler- async def handle_user_message(self, message: UserRequest, cancellation_token: CancellationToken) -> AIResponse:- """Handle a user message, execute the model and tools, and returns the response."""- session: List[LLMMessage] = []- session.append(UserMessage(content=message.content, source="User"))- response = await self._model_client.create(self._system_messages + session, tools=self._tools)- session.append(AssistantMessage(content=response.content, source=self.metadata["name"]))-- # Keep executing the tools until the response is not a list of function calls.- while isinstance(response.content, list) and all(isinstance(item, FunctionCall) for item in response.content):- results = await asyncio.gather(- *[- self.send_message(ToolExecutionTask(function_call=call), self._tool_executor)- for call in response.content- ]- )- # Combine the results into a single response.- result = FunctionExecutionResultMessage(content=[result.result for result in results])- session.append(result)- # Execute the model again with the new response.- response = await self._model_client.create(self._system_messages + session, tools=self._tools)- session.append(AssistantMessage(content=response.content, source=self.metadata["name"]))-- assert isinstance(response.content, str)- return AIResponse(content=response.content)---async def main() -> None:- # Create the runtime.- runtime = SingleThreadedAgentRuntime()- # Define the tools.- tools: List[Tool] = [- # A tool that executes Python code.- PythonCodeExecutionTool(- LocalCommandLineCodeExecutor(),- )- ]- # Register agents.- executor = runtime.register_and_get("tool_executor", lambda: ToolExecutorAgent("Tool Executor", tools))- tool_user = runtime.register_and_get(- "tool_use_agent",- lambda: ToolUserAgent(- description="Tool Use Agent",- system_messages=[SystemMessage("You are a helpful AI Assistant. Use your tools to solve problems.")],- model_client=OpenAIChatCompletionClient(model="gpt-3.5-turbo"),- tools=tools,- tool_executor=executor,- ),- )-- # Send a task to the tool user.- result = runtime.send_message(UserRequest("Run the following Python code: print('Hello, World!')"), tool_user)-- # Run the runtime until the task is completed.- while not result.done():- await runtime.process_next()-- # Print the result.- ai_response = result.result()- assert isinstance(ai_response, AIResponse)- print(ai_response.content)---if __name__ == "__main__":- import logging-- logging.basicConfig(level=logging.WARNING)- logging.getLogger("agnext").setLevel(logging.DEBUG)- asyncio.run(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 2523b3c8f..c4e2138a4 100644--- a/python/examples/tool-use/coding_two_agent_pub_sub.py+++ b/python/examples/tool-use/coding_two_agent_pub_sub.py@@ -1,3 +1,19 @@+"""+This example shows how to use pub/sub to implement+a simple interaction between a tool executor agent and a tool use agent.+1. The tool use agent receives a user message, and makes an inference using a model.+If the response is a list of function calls, the agent publishes the function calls+to the tool executor agent.+2. The tool executor agent receives the function calls, executes the tools, and publishes+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 uuid@@ -40,15 +56,10 @@ class UserRequest:@dataclass-class AIResponse:+class AgentResponse:content: str-@dataclass-class Termination:- pass--class ToolExecutorAgent(TypeRoutedAgent):"""An agent that executes tools."""@@ -113,8 +124,9 @@ class ToolUseAgent(TypeRoutedAgent):if isinstance(response.content, str):# If the response is a string, just publish the response.- response_message = AIResponse(content=response.content)+ response_message = AgentResponse(content=response.content)await self.publish_message(response_message)+ 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)@@ -153,7 +165,7 @@ class ToolUseAgent(TypeRoutedAgent):)# If the response is a string, just publish the response.if isinstance(response.content, str):- response_message = AIResponse(content=response.content)+ response_message = AgentResponse(content=response.content)await self.publish_message(response_message)self._tool_results.pop(message.session_id)self._tool_counter.pop(message.session_id)@@ -174,8 +186,9 @@ class TerminationHandler(DefaultInterventionHandler):self._terminated = Falseasync def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:- if isinstance(message, Termination):+ if isinstance(message, AgentResponse):self._terminated = True+ print(f"AI Response: {message.content}")return message@property@@ -183,17 +196,6 @@ class TerminationHandler(DefaultInterventionHandler):return self._terminated-class DisplayAgent(TypeRoutedAgent):- """An agent that displays to the console and publishes a termination message- to the runtime."""-- @message_handler- async def handle_code_writing_result(self, message: AIResponse, cancellation_token: CancellationToken) -> None:- print("AI Response:", message.content)- # Terminate the runtime.- await self.publish_message(Termination())--async def main() -> None:termination_handler = TerminationHandler()runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)@@ -214,7 +216,6 @@ async def main() -> None:tools=tools,),)- runtime.register("display_agent", lambda: DisplayAgent("Display Agent"))# Publish a task.runtime.publish_message(UserRequest("Run the following Python code: print('Hello, World!')"), namespace="default")diff --git a/python/examples/tool-use/custom_function_tool_one_agent_direct.py b/python/examples/tool-use/custom_function_tool_one_agent_direct.pyindex a59b43cba..6c6238397 100644--- a/python/examples/tool-use/custom_function_tool_one_agent_direct.py+++ b/python/examples/tool-use/custom_function_tool_one_agent_direct.py@@ -1,3 +1,8 @@+"""+This example shows how to use custom function tools with a tool-enabled+agent.+"""+import asyncioimport osimport random