Add user proxy docs. Make user proxy's default impl cancellable

python/packages/autogen-agentchat/src/autogen_agentchat/agents/_user_proxy_agent.py

@@ -2,6 +2,7 @@
 from inspect import iscoroutinefunction
 from typing import Awaitable, Callable, List, Optional, Sequence, Union, cast
 
+from aioconsole import ainput
 from autogen_core.base import CancellationToken
 
 from ..base import Response
@@ -14,6 +15,13 @@
 InputFuncType = Union[SyncInputFunc, AsyncInputFunc]
 
 
+# TODO: ainput doesn't seem to play nicely with jupyter.
+async def cancellable_input(prompt: str, cancellation_token: Optional[CancellationToken]) -> Awaitable[str]:
+    task = asyncio.create_task(ainput(prompt))
+    cancellation_token.link_future(task)
+    return await task
+
+
 class UserProxyAgent(BaseChatAgent):
     """An agent that can represent a human user through an input function.
 
@@ -51,7 +59,7 @@ def __init__(
     ) -> None:
         """Initialize the UserProxyAgent."""
         super().__init__(name=name, description=description)
-        self.input_func = input_func or input
+        self.input_func = input_func or cancellable_input
         self._is_async = iscoroutinefunction(self.input_func)
 
     @property

python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py

@@ -1,7 +1,6 @@
 import json
 import logging
-from typing import Any, List, Dict
-from .... import TRACE_LOGGER_NAME
+from typing import Any, Dict, List
 
 from autogen_core.base import AgentId, CancellationToken, MessageContext
 from autogen_core.components import DefaultTopicId, Image, event, rpc
@@ -12,8 +11,10 @@
     UserMessage,
 )
 
+from .... import TRACE_LOGGER_NAME
 from ....base import Response, TerminationCondition
-from ....messages import AgentMessage, MultiModalMessage, StopMessage, TextMessage, ChatMessage
+from ....messages import AgentMessage, ChatMessage, MultiModalMessage, StopMessage, TextMessage
+from .._base_group_chat_manager import BaseGroupChatManager
 from .._events import (
     GroupChatAgentResponse,
     GroupChatMessage,
@@ -22,7 +23,6 @@
     GroupChatStart,
     GroupChatTermination,
 )
-from .._base_group_chat_manager import BaseGroupChatManager
 from ._prompts import (
     ORCHESTRATOR_FINAL_ANSWER_PROMPT,
     ORCHESTRATOR_PROGRESS_LEDGER_PROMPT,

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb

@@ -104,6 +104,67 @@
     "as well as a list of inner messages in the {py:attr}`~autogen_agentchat.base.Response.inner_messages` attribute,\n",
     "which stores the agent's \"thought process\" that led to the final response.\n",
     "\n",
+    "## User Proxy Agent\n",
+    "\n",
+    "{py:class}`~autogen_agentchat.agents.UserProxyAgent` is a built-in agent that\n",
+    "provides one way for a user to intervene in the process. This agent will put the team in a temporary blocking state, and thus any exceptions or runtime failures while in the blocked state will result in a deadlock. It is strongly advised that a this agent be coupled with a timeout mechanic and that all errors and exceptions emanating from it are handled."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "BaseException: \n"
+     ]
+    }
+   ],
+   "source": [
+    "import asyncio\n",
+    "\n",
+    "from autogen_agentchat.agents import UserProxyAgent\n",
+    "\n",
+    "token = CancellationToken()\n",
+    "agent = UserProxyAgent(\"user_proxy\")\n",
+    "\n",
+    "\n",
+    "async def timeout(delay):\n",
+    "    await asyncio.sleep(delay)\n",
+    "\n",
+    "\n",
+    "def cancellation_callback(task):\n",
+    "    token.cancel()\n",
+    "\n",
+    "\n",
+    "try:\n",
+    "    timeout_task = asyncio.create_task(timeout(3))\n",
+    "    timeout_task.add_done_callback(cancellation_callback)\n",
+    "    agent_task = asyncio.create_task(\n",
+    "        agent.on_messages(\n",
+    "            [TextMessage(content=\"What is your name? \", source=\"user\")],\n",
+    "            cancellation_token=token,\n",
+    "        )\n",
+    "    )\n",
+    "\n",
+    "    response = await agent_task\n",
+    "    print(f\"Your name is {response.chat_message.content}\")\n",
+    "\n",
+    "except Exception as e:\n",
+    "    print(f\"Exception: {e}\")\n",
+    "except BaseException as e:\n",
+    "    print(f\"BaseException: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The User Proxy agent is ideally used for on-demand human-in-the-loop interactions for scenarios such as Just In Time approvals, human feedback, alerts, etc. For slower user interactions, consider terminating the session using a termination condition and start another one from run or run_stream with another message.\n",
+    "\n",
     "### Stream Messages\n",
     "\n",
     "We can also stream each message as it is generated by the agent by using the\n",
@@ -251,7 +312,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.5"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/custom-agents.ipynb

@@ -95,59 +95,6 @@
     "# Use asyncio.run(run_countdown_agent()) when running in a script.\n",
     "await run_countdown_agent()"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## UserProxyAgent \n",
-    "\n",
-    "A common use case for building a custom agent is to create an agent that acts as a proxy for the user.\n",
-    "\n",
-    "In the example below we show how to implement a `UserProxyAgent` - an agent that asks the user to enter\n",
-    "some text through console and then returns that message as a response."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import asyncio\n",
-    "from typing import List, Sequence\n",
-    "\n",
-    "from autogen_agentchat.agents import BaseChatAgent\n",
-    "from autogen_agentchat.base import Response\n",
-    "from autogen_agentchat.messages import ChatMessage\n",
-    "from autogen_core.base import CancellationToken\n",
-    "\n",
-    "\n",
-    "class UserProxyAgent(BaseChatAgent):\n",
-    "    def __init__(self, name: str) -> None:\n",
-    "        super().__init__(name, \"A human user.\")\n",
-    "\n",
-    "    @property\n",
-    "    def produced_message_types(self) -> List[type[ChatMessage]]:\n",
-    "        return [TextMessage]\n",
-    "\n",
-    "    async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> Response:\n",
-    "        user_input = await asyncio.get_event_loop().run_in_executor(None, input, \"Enter your response: \")\n",
-    "        return Response(chat_message=TextMessage(content=user_input, source=self.name))\n",
-    "\n",
-    "    async def on_reset(self, cancellation_token: CancellationToken) -> None:\n",
-    "        pass\n",
-    "\n",
-    "\n",
-    "async def run_user_proxy_agent() -> None:\n",
-    "    user_proxy_agent = UserProxyAgent(name=\"user_proxy_agent\")\n",
-    "    response = await user_proxy_agent.on_messages([], CancellationToken())\n",
-    "    print(response.chat_message.content)\n",
-    "\n",
-    "\n",
-    "# Use asyncio.run(run_user_proxy_agent()) when running in a script.\n",
-    "await run_user_proxy_agent()"
-   ]
   }
  ],
  "metadata": {

python/packages/autogen-core/pyproject.toml

@@ -17,6 +17,7 @@ classifiers = [
 dependencies = [
     "openai>=1.3",
     "pillow",
+    "aioconsole",
     "aiohttp",
     "typing-extensions",
     "pydantic<3.0.0,>=2.0.0",