A programming framework for agentic AI
Move intervention objects to root module (#4859)
Jack Gerritsc58eb9d1205d
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/termination-with-intervention.ipynb b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/termination-with-intervention.ipynbindex 1d39f0d99..4bed96d6b 100644--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/termination-with-intervention.ipynb+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/termination-with-intervention.ipynb@@ -1,179 +1,179 @@{- "cells": [- {- "cell_type": "markdown",- "metadata": {},- "source": [- "# Termination using Intervention Handler\n",- "\n",- "```{note}\n",- "This method is valid when using {py:class}`~autogen_core.SingleThreadedAgentRuntime`.\n",- "```\n",- "\n",- "There are many different ways to handle termination in `autogen_core`. Ultimately, the goal is to detect that the runtime no longer needs to be executed and you can proceed to finalization tasks. One way to do this is to use an {py:class}`autogen_core.base.intervention.InterventionHandler` to detect a termination message and then act on it."- ]- },- {- "cell_type": "code",- "execution_count": 6,- "metadata": {},- "outputs": [],- "source": [- "from dataclasses import dataclass\n",- "from typing import Any\n",- "\n",- "from autogen_core import (\n",- " AgentId,\n",- " DefaultTopicId,\n",- " MessageContext,\n",- " RoutedAgent,\n",- " SingleThreadedAgentRuntime,\n",- " default_subscription,\n",- " message_handler,\n",- ")\n",- "from autogen_core.base.intervention import DefaultInterventionHandler"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "First, we define a dataclass for regular message and message that will be used to signal termination."- ]- },- {- "cell_type": "code",- "execution_count": 7,- "metadata": {},- "outputs": [],- "source": [- "@dataclass\n",- "class Message:\n",- " content: Any\n",- "\n",- "\n",- "@dataclass\n",- "class Termination:\n",- " reason: str"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "We code our agent to publish a termination message when it decides it is time to terminate."- ]- },- {- "cell_type": "code",- "execution_count": 8,- "metadata": {},- "outputs": [],- "source": [- "@default_subscription\n",- "class AnAgent(RoutedAgent):\n",- " def __init__(self) -> None:\n",- " super().__init__(\"MyAgent\")\n",- " self.received = 0\n",- "\n",- " @message_handler\n",- " async def on_new_message(self, message: Message, ctx: MessageContext) -> None:\n",- " self.received += 1\n",- " if self.received > 3:\n",- " await self.publish_message(Termination(reason=\"Reached maximum number of messages\"), DefaultTopicId())"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "Next, we create an InterventionHandler that will detect the termination message and act on it. This one hooks into publishes and when it encounters `Termination` it alters its internal state to indicate that termination has been requested."- ]- },- {- "cell_type": "code",- "execution_count": 9,- "metadata": {},- "outputs": [],- "source": [- "class TerminationHandler(DefaultInterventionHandler):\n",- " def __init__(self) -> None:\n",- " self._termination_value: Termination | None = None\n",- "\n",- " async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:\n",- " if isinstance(message, Termination):\n",- " self._termination_value = message\n",- " return message\n",- "\n",- " @property\n",- " def termination_value(self) -> Termination | None:\n",- " return self._termination_value\n",- "\n",- " @property\n",- " def has_terminated(self) -> bool:\n",- " return self._termination_value is not None"- ]- },- {- "cell_type": "markdown",- "metadata": {},- "source": [- "Finally, we add this handler to the runtime and use it to detect termination and stop the runtime when the termination message is received."- ]- },- {- "cell_type": "code",- "execution_count": 10,- "metadata": {},- "outputs": [- {- "name": "stdout",- "output_type": "stream",- "text": [- "Termination(reason='Reached maximum number of messages')\n"- ]- }- ],- "source": [- "termination_handler = TerminationHandler()\n",- "runtime = SingleThreadedAgentRuntime(intervention_handlers=[termination_handler])\n",- "\n",- "await AnAgent.register(runtime, \"my_agent\", AnAgent)\n",- "\n",- "runtime.start()\n",- "\n",- "# Publish more than 3 messages to trigger termination.\n",- "await runtime.publish_message(Message(\"hello\"), DefaultTopicId())\n",- "await runtime.publish_message(Message(\"hello\"), DefaultTopicId())\n",- "await runtime.publish_message(Message(\"hello\"), DefaultTopicId())\n",- "await runtime.publish_message(Message(\"hello\"), DefaultTopicId())\n",- "\n",- "# Wait for termination.\n",- "await runtime.stop_when(lambda: termination_handler.has_terminated)\n",- "\n",- "print(termination_handler.termination_value)"- ]- }- ],- "metadata": {- "kernelspec": {- "display_name": ".venv",- "language": "python",- "name": "python3"- },- "language_info": {- "codemirror_mode": {- "name": "ipython",- "version": 3- },- "file_extension": ".py",- "mimetype": "text/x-python",- "name": "python",- "nbconvert_exporter": "python",- "pygments_lexer": "ipython3",- "version": "3.11.9"- }- },- "nbformat": 4,- "nbformat_minor": 2+ "cells": [+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "# Termination using Intervention Handler\n",+ "\n",+ "```{note}\n",+ "This method is valid when using {py:class}`~autogen_core.SingleThreadedAgentRuntime`.\n",+ "```\n",+ "\n",+ "There are many different ways to handle termination in `autogen_core`. Ultimately, the goal is to detect that the runtime no longer needs to be executed and you can proceed to finalization tasks. One way to do this is to use an {py:class}`autogen_core.base.intervention.InterventionHandler` to detect a termination message and then act on it."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 6,+ "metadata": {},+ "outputs": [],+ "source": [+ "from dataclasses import dataclass\n",+ "from typing import Any\n",+ "\n",+ "from autogen_core import (\n",+ " AgentId,\n",+ " DefaultInterventionHandler,\n",+ " DefaultTopicId,\n",+ " MessageContext,\n",+ " RoutedAgent,\n",+ " SingleThreadedAgentRuntime,\n",+ " default_subscription,\n",+ " message_handler,\n",+ ")"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "First, we define a dataclass for regular message and message that will be used to signal termination."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 7,+ "metadata": {},+ "outputs": [],+ "source": [+ "@dataclass\n",+ "class Message:\n",+ " content: Any\n",+ "\n",+ "\n",+ "@dataclass\n",+ "class Termination:\n",+ " reason: str"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "We code our agent to publish a termination message when it decides it is time to terminate."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 8,+ "metadata": {},+ "outputs": [],+ "source": [+ "@default_subscription\n",+ "class AnAgent(RoutedAgent):\n",+ " def __init__(self) -> None:\n",+ " super().__init__(\"MyAgent\")\n",+ " self.received = 0\n",+ "\n",+ " @message_handler\n",+ " async def on_new_message(self, message: Message, ctx: MessageContext) -> None:\n",+ " self.received += 1\n",+ " if self.received > 3:\n",+ " await self.publish_message(Termination(reason=\"Reached maximum number of messages\"), DefaultTopicId())"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "Next, we create an InterventionHandler that will detect the termination message and act on it. This one hooks into publishes and when it encounters `Termination` it alters its internal state to indicate that termination has been requested."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 9,+ "metadata": {},+ "outputs": [],+ "source": [+ "class TerminationHandler(DefaultInterventionHandler):\n",+ " def __init__(self) -> None:\n",+ " self._termination_value: Termination | None = None\n",+ "\n",+ " async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:\n",+ " if isinstance(message, Termination):\n",+ " self._termination_value = message\n",+ " return message\n",+ "\n",+ " @property\n",+ " def termination_value(self) -> Termination | None:\n",+ " return self._termination_value\n",+ "\n",+ " @property\n",+ " def has_terminated(self) -> bool:\n",+ " return self._termination_value is not None"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "Finally, we add this handler to the runtime and use it to detect termination and stop the runtime when the termination message is received."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 10,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "Termination(reason='Reached maximum number of messages')\n"+ ]+ }+ ],+ "source": [+ "termination_handler = TerminationHandler()\n",+ "runtime = SingleThreadedAgentRuntime(intervention_handlers=[termination_handler])\n",+ "\n",+ "await AnAgent.register(runtime, \"my_agent\", AnAgent)\n",+ "\n",+ "runtime.start()\n",+ "\n",+ "# Publish more than 3 messages to trigger termination.\n",+ "await runtime.publish_message(Message(\"hello\"), DefaultTopicId())\n",+ "await runtime.publish_message(Message(\"hello\"), DefaultTopicId())\n",+ "await runtime.publish_message(Message(\"hello\"), DefaultTopicId())\n",+ "await runtime.publish_message(Message(\"hello\"), DefaultTopicId())\n",+ "\n",+ "# Wait for termination.\n",+ "await runtime.stop_when(lambda: termination_handler.has_terminated)\n",+ "\n",+ "print(termination_handler.termination_value)"+ ]+ }+ ],+ "metadata": {+ "kernelspec": {+ "display_name": ".venv",+ "language": "python",+ "name": "python3"+ },+ "language_info": {+ "codemirror_mode": {+ "name": "ipython",+ "version": 3+ },+ "file_extension": ".py",+ "mimetype": "text/x-python",+ "name": "python",+ "nbconvert_exporter": "python",+ "pygments_lexer": "ipython3",+ "version": "3.11.9"+ }+ },+ "nbformat": 4,+ "nbformat_minor": 2}diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/tool-use-with-intervention.ipynb b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/tool-use-with-intervention.ipynbindex 46b759509..37def894b 100644--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/tool-use-with-intervention.ipynb+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/tool-use-with-intervention.ipynb@@ -22,13 +22,14 @@"from autogen_core import (\n"," AgentId,\n"," AgentType,\n",+ " DefaultInterventionHandler,\n",+ " DropMessage,\n"," FunctionCall,\n"," MessageContext,\n"," RoutedAgent,\n"," SingleThreadedAgentRuntime,\n"," message_handler,\n",")\n",- "from autogen_core.base.intervention import DefaultInterventionHandler, DropMessage\n","from autogen_core.models import (\n"," ChatCompletionClient,\n"," LLMMessage,\n",diff --git a/python/packages/autogen-core/samples/slow_human_in_loop.py b/python/packages/autogen-core/samples/slow_human_in_loop.pyindex 61ea36fda..eb4e627bb 100644--- a/python/packages/autogen-core/samples/slow_human_in_loop.py+++ b/python/packages/autogen-core/samples/slow_human_in_loop.py@@ -33,6 +33,7 @@ from typing import Any, Mapping, Optionalfrom autogen_core import (AgentId,CancellationToken,+ DefaultInterventionHandler,DefaultTopicId,FunctionCall,MessageContext,@@ -41,7 +42,6 @@ from autogen_core import (message_handler,type_subscription,)-from autogen_core.base.intervention import DefaultInterventionHandlerfrom autogen_core.model_context import BufferedChatCompletionContextfrom autogen_core.models import (AssistantMessage,diff --git a/python/packages/autogen-core/src/autogen_core/__init__.py b/python/packages/autogen-core/src/autogen_core/__init__.pyindex 9523476e4..c9d12872d 100644--- a/python/packages/autogen-core/src/autogen_core/__init__.py+++ b/python/packages/autogen-core/src/autogen_core/__init__.py@@ -31,6 +31,11 @@ from ._constants import (from ._default_subscription import DefaultSubscription, default_subscription, type_subscriptionfrom ._default_topic import DefaultTopicIdfrom ._image import Image+from ._intervention import (+ DefaultInterventionHandler,+ DropMessage,+ InterventionHandler,+)from ._message_context import MessageContextfrom ._message_handler_context import MessageHandlerContextfrom ._routed_agent import RoutedAgent, event, message_handler, rpc@@ -111,4 +116,7 @@ __all__ = ["ComponentConfigImpl","ComponentModel","ComponentType",+ "DropMessage",+ "InterventionHandler",+ "DefaultInterventionHandler",]diff --git a/python/packages/autogen-core/src/autogen_core/_intervention.py b/python/packages/autogen-core/src/autogen_core/_intervention.pynew file mode 100644index 000000000..649026fea--- /dev/null+++ b/python/packages/autogen-core/src/autogen_core/_intervention.py@@ -0,0 +1,41 @@+from typing import Any, Protocol, final++from ._agent_id import AgentId++__all__ = [+ "DropMessage",+ "InterventionHandler",+ "DefaultInterventionHandler",+]+++@final+class DropMessage: ...+++class InterventionHandler(Protocol):+ """An intervention handler is a class that can be used to modify, log or drop messages that are being processed by the :class:`autogen_core.base.AgentRuntime`.++ Note: Returning None from any of the intervention handler methods will result in a warning being issued and treated as "no change". If you intend to drop a message, you should return :class:`DropMessage` explicitly.+ """++ async def on_send(self, message: Any, *, sender: AgentId | None, recipient: AgentId) -> Any | type[DropMessage]: ...+ async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any | type[DropMessage]: ...+ async def on_response(+ self, message: Any, *, sender: AgentId, recipient: AgentId | None+ ) -> Any | type[DropMessage]: ...+++class DefaultInterventionHandler(InterventionHandler):+ """Simple class that provides a default implementation for all intervention+ handler methods, that simply returns the message unchanged. Allows for easy+ subclassing to override only the desired methods."""++ async def on_send(self, message: Any, *, sender: AgentId | None, recipient: AgentId) -> Any | type[DropMessage]:+ return message++ async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any | type[DropMessage]:+ return message++ async def on_response(self, message: Any, *, sender: AgentId, recipient: AgentId | None) -> Any | type[DropMessage]:+ return messagediff --git a/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py b/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.pyindex a00e531fc..37c84ca84 100644--- a/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py+++ b/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py@@ -28,6 +28,7 @@ from ._agent_metadata import AgentMetadatafrom ._agent_runtime import AgentRuntimefrom ._agent_type import AgentTypefrom ._cancellation_token import CancellationToken+from ._intervention import DropMessage, InterventionHandlerfrom ._message_context import MessageContextfrom ._message_handler_context import MessageHandlerContextfrom ._runtime_impl_helpers import SubscriptionManager, get_impl@@ -35,7 +36,6 @@ from ._serialization import MessageSerializer, SerializationRegistryfrom ._subscription import Subscriptionfrom ._telemetry import EnvelopeMetadata, MessageRuntimeTracingConfig, TraceHelper, get_telemetry_envelope_metadatafrom ._topic import TopicId-from .base.intervention import DropMessage, InterventionHandlerfrom .exceptions import MessageDroppedExceptionlogger = logging.getLogger("autogen_core")diff --git a/python/packages/autogen-core/src/autogen_core/base/intervention.py b/python/packages/autogen-core/src/autogen_core/base/intervention.pyindex 5fe337b87..aa4a388a3 100644--- a/python/packages/autogen-core/src/autogen_core/base/intervention.py+++ b/python/packages/autogen-core/src/autogen_core/base/intervention.py@@ -1,45 +1,22 @@-from typing import Any, Awaitable, Callable, Protocol, final+from typing_extensions import deprecated-from .._agent_id import AgentId+from .._intervention import DefaultInterventionHandler as DefaultInterventionHandlerAlias+from .._intervention import DropMessage as DropMessageAlias+from .._intervention import InterventionHandler as InterventionHandlerAliass__all__ = ["DropMessage",- "InterventionFunction","InterventionHandler","DefaultInterventionHandler",]+# Final so can't inherit and deprecate+DropMessage = DropMessageAlias-@final-class DropMessage: ...+@deprecated("Moved to autogen_core.InterventionHandler. Will remove this in 0.4.0.", stacklevel=2)+class InterventionHandler(InterventionHandlerAliass): ...-InterventionFunction = Callable[[Any], Any | Awaitable[type[DropMessage]]]--class InterventionHandler(Protocol):- """An intervention handler is a class that can be used to modify, log or drop messages that are being processed by the :class:`autogen_core.base.AgentRuntime`.-- Note: Returning None from any of the intervention handler methods will result in a warning being issued and treated as "no change". If you intend to drop a message, you should return :class:`DropMessage` explicitly.- """-- async def on_send(self, message: Any, *, sender: AgentId | None, recipient: AgentId) -> Any | type[DropMessage]: ...- async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any | type[DropMessage]: ...- async def on_response(- self, message: Any, *, sender: AgentId, recipient: AgentId | None- ) -> Any | type[DropMessage]: ...---class DefaultInterventionHandler(InterventionHandler):- """Simple class that provides a default implementation for all intervention- handler methods, that simply returns the message unchanged. Allows for easy- subclassing to override only the desired methods."""-- async def on_send(self, message: Any, *, sender: AgentId | None, recipient: AgentId) -> Any | type[DropMessage]:- return message-- async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any | type[DropMessage]:- return message-- async def on_response(self, message: Any, *, sender: AgentId, recipient: AgentId | None) -> Any | type[DropMessage]:- return message+@deprecated("Moved to autogen_core.DefaultInterventionHandler. Will remove this in 0.4.0.", stacklevel=2)+class DefaultInterventionHandler(DefaultInterventionHandlerAlias): ...diff --git a/python/packages/autogen-core/tests/test_intervention.py b/python/packages/autogen-core/tests/test_intervention.pyindex a046201fe..ef6ee4ebf 100644--- a/python/packages/autogen-core/tests/test_intervention.py+++ b/python/packages/autogen-core/tests/test_intervention.py@@ -1,6 +1,5 @@import pytest-from autogen_core import AgentId, SingleThreadedAgentRuntime-from autogen_core.base.intervention import DefaultInterventionHandler, DropMessage+from autogen_core import AgentId, DefaultInterventionHandler, DropMessage, SingleThreadedAgentRuntimefrom autogen_core.exceptions import MessageDroppedExceptionfrom autogen_test_utils import LoopbackAgent, MessageType