fix(core): raise RecipientNotFoundError instead of generic Exception for unknown recipients

python/packages/autogen-core/src/autogen_core/__init__.py

@@ -58,6 +58,7 @@
 )
 from ._single_threaded_agent_runtime import SingleThreadedAgentRuntime
 from ._subscription import Subscription
+from .exceptions import RecipientNotFoundError
 from ._subscription_context import SubscriptionInstantiationContext
 from ._telemetry import (
     trace_create_agent_span,
@@ -140,4 +141,5 @@
     "trace_create_agent_span",
     "trace_invoke_agent_span",
     "trace_tool_span",
+    "RecipientNotFoundError",
 ]

python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py

@@ -44,7 +44,7 @@
 from ._subscription import Subscription
 from ._telemetry import EnvelopeMetadata, MessageRuntimeTracingConfig, TraceHelper, get_telemetry_envelope_metadata
 from ._topic import TopicId
-from .exceptions import MessageDroppedException
+from .exceptions import MessageDroppedException, RecipientNotFoundError
 
 logger = logging.getLogger("autogen_core")
 event_logger = logging.getLogger("autogen_core.events")
@@ -362,7 +362,7 @@ async def send_message(
         ):
             future = asyncio.get_event_loop().create_future()
             if recipient.type not in self._known_agent_names:
-                future.set_exception(Exception("Recipient not found"))
+                future.set_exception(RecipientNotFoundError(f"Recipient '{recipient.type}' not found in the runtime."))
                 return await future
 
             content = message.__dict__ if hasattr(message, "__dict__") else message

python/packages/autogen-core/src/autogen_core/exceptions.py

@@ -1,4 +1,10 @@
-__all__ = ["CantHandleException", "UndeliverableException", "MessageDroppedException", "NotAccessibleError"]
+__all__ = [
+    "CantHandleException",
+    "UndeliverableException",
+    "MessageDroppedException",
+    "NotAccessibleError",
+    "RecipientNotFoundError",
+]
 
 
 class CantHandleException(Exception):
@@ -15,3 +21,13 @@ class MessageDroppedException(Exception):
 
 class NotAccessibleError(Exception):
     """Tried to access a value that is not accessible. For example if it is remote cannot be accessed locally."""
+
+
+class RecipientNotFoundError(Exception):
+    """Raised when a message is sent to an agent type that is not registered in the runtime.
+
+    Args:
+        recipient: The :class:`~autogen_core.AgentId` that could not be found.
+
+    .. versionadded:: v0.4.10
+    """

python/packages/autogen-core/tests/test_runtime.py

@@ -7,6 +7,7 @@
     AgentType,
     DefaultTopicId,
     MessageContext,
+    RecipientNotFoundError,
     RoutedAgent,
     SingleThreadedAgentRuntime,
     TopicId,
@@ -364,3 +365,14 @@ async def test_event_handler_exception_multi_message() -> None:
         await runtime.stop_when_idle()
 
     await runtime.close()
+
+
+@pytest.mark.asyncio
+async def test_send_message_to_unregistered_agent_raises_recipient_not_found() -> None:
+    runtime = SingleThreadedAgentRuntime()
+    runtime.start()
+    with pytest.raises(RecipientNotFoundError):
+        await runtime.send_message(MessageType(), AgentId("nonexistent_agent", "default"))
+    await runtime.stop_when_idle()
+
+    await runtime.close()