Add support for user-defined control messages

Author: RussellLuo

coagent/core/agent.py

@@ -245,6 +245,15 @@ async def _handle_control(self, msg: ControlMessage) -> None:
             case Cancel():
                 # Delete the agent when cancelled.
                 await self.delete()
+            case _:
+                await self._handle_control_custom(msg, Context())
+
+    async def _handle_control_custom(self, msg: ControlMessage, ctx: Context) -> None:
+        """Handle user-defined CONTROL messages."""
+        h: Handler = self.__get_handler(msg)
+        # By design, CONTROL messages are management commands that must be
+        # processed instantly and do not wait for any return value.
+        await h(self, msg, ctx)
 
     async def _handle_data(self) -> None:
         """Handle DATA messages."""

coagent/core/messages.py

@@ -58,12 +58,14 @@ class ControlMessage(Message):
     """ControlMessage is the base class for all control messages.
 
     A control message is used to control the behavior of an agent. For example,
-    a `Cancel` message can be sent to an agent to cancel the processing of DATA
-    messages.
-
-    Note that for a given agent, CONTROL messages and DATA messages are processed
-    in separate coroutines. So the CONTROL messages can be processed in a timely
-    manner without being blocked by the DATA messages.
+    a `Cancel` message can be sent to an agent to cancel the processing of the
+    agent and delete it.
+
+    For a specific agent, CONTROL messages and DATA messages are processed in
+    separate coroutines, so CONTROL messages can be processed in a timely manner
+    without being blocked by DATA messages. By design, CONTROL messages are
+    management commands that must be processed instantly and do not wait for
+    any return value.
 
     Any CONTROL message should be a subclass of this class. And any other messages,
     inherited from `Message`, are DATA messages.