Add msg_to param to ConversableAgent.run (#704)

* add msg_to param to ConversableAgene.run

* Add agent name, user input control, and max turns control to run. Docstrings and termination condition update.

Signed-off-by: Mark Sze <[email protected]>

* Rearrange docstring arguments

* Updated notebook for run

Signed-off-by: Mark Sze <[email protected]>

* Add commas to notebook

Signed-off-by: Mark Sze <[email protected]>

---------

Signed-off-by: Mark Sze <[email protected]>
Co-authored-by: Mark Sze <[email protected]>

Author: davorrunje

autogen/agentchat/conversable_agent.py

@@ -2912,18 +2912,28 @@ def get_total_usage(self) -> Union[None, dict[str, int]]:
 
     @contextmanager
     def _create_executor(
-        self, executor_kwargs: Optional[dict[str, Any]] = None, tools: Optional[Union[Tool, Iterable[Tool]]] = None
+        self,
+        executor_kwargs: Optional[dict[str, Any]] = None,
+        tools: Optional[Union[Tool, Iterable[Tool]]] = None,
+        agent_name: str = "executor",
+        agent_human_input_mode: str = "NEVER",
     ) -> Generator["ConversableAgent", None, None]:
+        """Creates a user proxy / tool executor agent.
+
+        Args:
+            executor_kwargs: agent's arguments.
+            tools: tools to register for execution with the agent.
+            agent_name: agent's name, defaults to 'executor'.
+            agent_human_input_mode: agent's human input mode, defaults to 'NEVER'.
+        """
         if executor_kwargs is None:
             executor_kwargs = {}
         if "is_termination_msg" not in executor_kwargs:
-            executor_kwargs["is_termination_msg"] = lambda x: (x["content"] is not None) and x["content"].endswith(
-                "TERMINATE"
-            )
+            executor_kwargs["is_termination_msg"] = lambda x: (x["content"] is not None) and "TERMINATE" in x["content"]
 
         executor = ConversableAgent(
-            name="executor",
-            human_input_mode="NEVER",
+            name=agent_name,
+            human_input_mode=agent_human_input_mode,
             code_execution_config={
                 "work_dir": "coding",
                 "use_docker": True,
@@ -2947,39 +2957,79 @@ def run(
         self,
         message: str,
         *,
-        clear_history: bool = False,
-        executor_kwargs: Optional[dict[str, Any]] = None,
         tools: Optional[Union[Tool, Iterable[Tool]]] = None,
+        executor_kwargs: Optional[dict[str, Any]] = None,
+        max_turns: Optional[int] = None,
+        msg_to: Literal["agent", "user"] = "agent",
+        clear_history: bool = False,
+        user_input: bool = True,
     ) -> ChatResult:
-        """Run the agent with the given message.
+        """Run a chat with the agent using the given message.
+
+        A second agent will be created to represent the user, this agent will by known by the name 'user'.
+
+        The user can terminate the conversation when prompted or, if agent's reply contains 'TERMINATE', it will terminate.
 
         Args:
             message: the message to be processed.
-            clear_history: whether to clear the chat history.
-            executor_kwargs: the keyword arguments for the executor.
             tools: the tools to be used by the agent.
+            executor_kwargs: the keyword arguments for the executor.
+            max_turns: maximum number of turns (a turn is equivalent to both agents having replied), defaults no None which means unlimited. The original message is included.
+            msg_to: which agent is receiving the message and will be the first to reply, defaults to the agent.
+            clear_history: whether to clear the chat history.
+            user_input: the user will be asked for input at their turn.
         """
-        with self._create_executor(executor_kwargs=executor_kwargs, tools=tools) as executor:
-            return executor.initiate_chat(self, message=message, clear_history=clear_history).summary
+        with self._create_executor(
+            executor_kwargs=executor_kwargs,
+            tools=tools,
+            agent_name="user",
+            agent_human_input_mode="ALWAYS" if user_input else "NEVER",
+        ) as executor:
+            if msg_to == "agent":
+                return executor.initiate_chat(self, message=message, clear_history=clear_history, max_turns=max_turns)
+            else:
+                return self.initiate_chat(executor, message=message, clear_history=clear_history, max_turns=max_turns)
 
     async def a_run(
         self,
         message: str,
         *,
-        clear_history=False,
         tools: Optional[Union[Tool, Iterable[Tool]]] = None,
         executor_kwargs: Optional[dict[str, Any]] = None,
+        max_turns: Optional[int] = None,
+        msg_to: Literal["agent", "user"] = "agent",
+        clear_history: bool = False,
+        user_input: bool = True,
     ) -> ChatResult:
-        """Run the agent with the given message.
+        """Run a chat asynchronously with the agent using the given message.
+
+        A second agent will be created to represent the user, this agent will by known by the name 'user'.
+
+        The user can terminate the conversation when prompted or, if agent's reply contains 'TERMINATE', it will terminate.
 
         Args:
             message: the message to be processed.
-            clear_history: whether to clear the chat history.
-            executor_kwargs: the keyword arguments for the executor.
             tools: the tools to be used by the agent.
+            executor_kwargs: the keyword arguments for the executor.
+            max_turns: maximum number of turns (a turn is equivalent to both agents having replied), defaults no None which means unlimited. The original message is included.
+            msg_to: which agent is receiving the message and will be the first to reply, defaults to the agent.
+            clear_history: whether to clear the chat history.
+            user_input: the user will be asked for input at their turn.
         """
-        with self._create_executor(executor_kwargs=executor_kwargs, tools=tools) as executor:
-            return (await executor.a_initiate_chat(self, message=message, clear_history=clear_history)).summary
+        with self._create_executor(
+            executor_kwargs=executor_kwargs,
+            tools=tools,
+            agent_name="user",
+            agent_human_input_mode="ALWAYS" if user_input else "NEVER",
+        ) as executor:
+            if msg_to == "agent":
+                return await executor.a_initiate_chat(
+                    self, message=message, clear_history=clear_history, max_turns=max_turns
+                )
+            else:
+                return await self.a_initiate_chat(
+                    executor, message=message, clear_history=clear_history, max_turns=max_turns
+                )
 
 
 @export_module("autogen")

notebook/agentchat_assistant_agent_standalone.ipynb

@@ -8,7 +8,7 @@
     "\n",
     "AG2 supports running `AssistantAgent` as a standalone agent with the ability to execute simple tasks without the need for interacting with other agents.\n",
     "\n",
-    "To enable our assistant agent to surf the web, we will use `BrowserUseTool` fow which we need to install the browser-use optional dependency and [playwright](https://playwright.dev/python/docs/intro)\n",
+    "To enable our assistant agent access to surf the web, we will use the `BrowserUseTool` Tool for which we need to install the browser-use optional dependency and [playwright](https://playwright.dev/python/docs/intro).\n",
     "\n",
     "````{=mdx}\n",
     ":::info Requirements\n",
@@ -33,7 +33,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -48,12 +48,12 @@
    "source": [
     "## Set your API Endpoint\n",
     "\n",
-    "The [`config_list_from_json`](https://docs.ag2.ai/reference/autogen/config_list_from_json#config-list-from-json) function loads a list of configurations from an environment variable or a json file."
+    "The [`config_list_from_json`](https://docs.ag2.ai/reference/autogen/config_list_from_json#config-list-from-json) function loads a list of configurations from an environment variable or a JSON file."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -78,8 +78,10 @@
     "# Configure your assistant agent\n",
     "\n",
     "Here we will configure two assistant agents:\n",
-    "1. x_assistant, tasked with exploring the trending topics on X (Formally Twitter)\n",
-    "2. arxiv_researcher, tasked with discovery of papers that allign with the hot topic of the day"
+    "1. x_assistant, tasked with exploring the trending topics on X (formally Twitter)\n",
+    "2. arxiv_researcher, tasked with discovery of papers that allign with the hot topic of the day\n",
+    "\n",
+    "We will set the browser configuration to not run headless, this will open the browser as a window so you can see it in action."
    ]
   },
   {
@@ -94,6 +96,7 @@
     "\n",
     "browser_use_tool = BrowserUseTool(\n",
     "    llm_config=llm_config,\n",
+    "    browser_config={\"headless\": False},\n",
     ")"
    ]
   },
@@ -108,8 +111,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Lets run our x_assistant to discover the hot topic of the day\n",
-    "To be able to do this let's give our assistant the capability to browse the web using a `BrowserUseTool`"
+    "Let's run our x_assistant to discover the hot topic of the day.\n",
+    "\n",
+    "To be able to do this we give our assistant the capability to browse the web using a `BrowserUseTool` Tool."
    ]
   },
   {
@@ -121,16 +125,17 @@
     "hot_topic_res = x_assistant.run(\n",
     "    \"Find out today's hot topic and an influencer who is talking about it on X using a web search\",\n",
     "    tools=browser_use_tool,\n",
+    "    user_input=False,\n",
     ")\n",
     "\n",
-    "print(hot_topic_res)"
+    "print(hot_topic_res.summary)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "After discovering the hot topic, lets run the discovery of papers that allign with the topic"
+    "After discovering the hot topic, let's run the discovery of papers that align with the topic"
    ]
   },
   {
@@ -140,17 +145,18 @@
    "outputs": [],
    "source": [
     "paper_abstract = arxiv_researcher.run(\n",
-    "    \"Get the abstract of a relevant paper based on \" + hot_topic_res,\n",
+    "    \"Get the abstract of a relevant paper based on:\\n\" + hot_topic_res.summary,\n",
+    "    user_input=False,\n",
     ")\n",
     "\n",
-    "print(paper_abstract)"
+    "print(paper_abstract.summary)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now, Lets create a twitter post using our x_assistant"
+    "Now, let's create an X post using our x_assistant"
    ]
   },
   {
@@ -159,19 +165,20 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Secneario 1. This task requires x_assistant's past state\n",
+    "# Scenario 1. This task requires x_assistant's past state\n",
     "post = x_assistant.run(\n",
-    "    \"Create an X post based on the hot topic and this \" + paper_abstract + \"and mention the influencer\",\n",
+    "    \"Create an X post based on the hot topic and the following and mention the influencer:\\n\" + paper_abstract.summary,\n",
+    "    user_input=False,\n",
     ")\n",
     "\n",
-    "print(post)"
+    "print(post.summary)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Finally, lets ask our x_assistant who should we follow on twitter"
+    "Finally, let's ask our x_assistant who should we follow on X"
    ]
   },
   {
@@ -180,21 +187,22 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Scenario 2.  Doing another task that does not require history or past state\n",
+    "# Scenario 2. Doing another task that does not require history or past state\n",
     "\n",
     "influencer_choice = x_assistant.run(\n",
     "    \"Find a influencer I should follow on Twitter by searching the web\",\n",
     "    clear_history=True,\n",
     "    tools=browser_use_tool,\n",
+    "    user_input=False,\n",
     ")\n",
     "\n",
-    "print(influencer_choice)"
+    "print(influencer_choice.summary)"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -208,7 +216,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.11"
+   "version": "3.11.10"
   }
  },
  "nbformat": 4,

test/agentchat/test_assistant_agent.py

@@ -205,8 +205,8 @@ def get_twitter_hot_topic() -> str:
         tools=get_twitter_hot_topic,
     )
 
-    assert "AI" in hot_topic_res
-    assert "elonmusk" in hot_topic_res
+    assert "AI" in hot_topic_res.summary
+    assert "elonmusk" in hot_topic_res.summary
 
 
 @pytest.mark.openai