消息与通信#

在 AutoGen 核心中，一个代理可以对消息进行反应、发送和发布消息，而消息是代理之间相互通信的唯一方式。

消息#

消息是可序列化的对象，它们可以使用以下方式定义：

Pydantic的pydantic.BaseModel的子类，或者
一个数据类

例如：

from dataclasses import dataclass


@dataclass
class TextMessage:
    content: str
    source: str


@dataclass
class ImageMessage:
    url: str
    source: str

注意

消息是纯粹的数据，不应包含任何逻辑。

消息处理器#

当代理接收到消息时，运行时将调用代理的消息处理程序 (on_message())，该程序应实现代理的消息处理逻辑。如果代理无法处理此消息，代理应抛出 CantHandleException。

基础类 BaseAgent 不提供消息处理逻辑，除非是高级使用场景，否则不建议直接实现 on_message() 方法。

开发人员应从实现RoutedAgent基类开始，该类提供了内置的消息路由功能。

按类型路由消息#

RoutedAgent 基类提供了一种机制，用于将消息类型与消息处理程序关联起来，使用message_handler()装饰器，因此开发者无需实现on_message()方法。

例如，以下类型路由代理会使用不同的消息处理器来响应 TextMessage 和 ImageMessage：

from autogen_core import AgentId, MessageContext, RoutedAgent, SingleThreadedAgentRuntime, message_handler


class MyAgent(RoutedAgent):
    @message_handler
    async def on_text_message(self, message: TextMessage, ctx: MessageContext) -> None:
        print(f"Hello, {message.source}, you said {message.content}!")

    @message_handler
    async def on_image_message(self, message: ImageMessage, ctx: MessageContext) -> None:
        print(f"Hello, {message.source}, you sent me {message.url}!")

创建代理运行时并注册代理类型（参见代理和代理运行时）：

runtime = SingleThreadedAgentRuntime()
await MyAgent.register(runtime, "my_agent", lambda: MyAgent("My Agent"))

AgentType(type='my_agent')

使用TextMessage和ImageMessage测试此代理。

runtime.start()
agent_id = AgentId("my_agent", "default")
await runtime.send_message(TextMessage(content="Hello, World!", source="User"), agent_id)
await runtime.send_message(ImageMessage(url="https://example.com/image.jpg", source="User"), agent_id)
await runtime.stop_when_idle()

Hello, User, you said Hello, World!!
Hello, User, you sent me https://example.com/image.jpg!

运行时在传递第一条消息时，会自动创建一个MyAgent实例，其代理ID为AgentId("my_agent", "default")。

路由相同类型的消息#

在某些场景中，将相同类型的消息路由到不同的处理程序是有用的。例如，来自不同发送代理的消息应以不同的方式处理。您可以使用match参数的message_handler()装饰器。

match 参数将相同消息类型的处理程序与特定消息关联起来——它是消息类型路由的次要因素。它接受一个可调用对象，该对象将消息和MessageContext作为参数，并返回一个布尔值，指示消息是否应由装饰的处理程序处理。可调用对象按照处理程序的字母顺序进行检查。

以下是一个根据发送代理使用match参数路由消息的代理示例：

class RoutedBySenderAgent(RoutedAgent):
    @message_handler(match=lambda msg, ctx: msg.source.startswith("user1"))  # type: ignore
    async def on_user1_message(self, message: TextMessage, ctx: MessageContext) -> None:
        print(f"Hello from user 1 handler, {message.source}, you said {message.content}!")

    @message_handler(match=lambda msg, ctx: msg.source.startswith("user2"))  # type: ignore
    async def on_user2_message(self, message: TextMessage, ctx: MessageContext) -> None:
        print(f"Hello from user 2 handler, {message.source}, you said {message.content}!")

    @message_handler(match=lambda msg, ctx: msg.source.startswith("user2"))  # type: ignore
    async def on_image_message(self, message: ImageMessage, ctx: MessageContext) -> None:
        print(f"Hello, {message.source}, you sent me {message.url}!")

上述代理使用消息的source字段来确定发送方代理。你也可以使用MessageContext的sender字段来确定发送方代理，如果有可用的代理ID的话。

让我们使用具有不同source值的消息来测试这个代理：

runtime = SingleThreadedAgentRuntime()
await RoutedBySenderAgent.register(runtime, "my_agent", lambda: RoutedBySenderAgent("Routed by sender agent"))
runtime.start()
agent_id = AgentId("my_agent", "default")
await runtime.send_message(TextMessage(content="Hello, World!", source="user1-test"), agent_id)
await runtime.send_message(TextMessage(content="Hello, World!", source="user2-test"), agent_id)
await runtime.send_message(ImageMessage(url="https://example.com/image.jpg", source="user1-test"), agent_id)
await runtime.send_message(ImageMessage(url="https://example.com/image.jpg", source="user2-test"), agent_id)
await runtime.stop_when_idle()

Hello from user 1 handler, user1-test, you said Hello, World!!
Hello from user 2 handler, user2-test, you said Hello, World!!
Hello, user2-test, you sent me https://example.com/image.jpg!

在上面的例子中，第一个ImageMessage没有被处理，因为消息的source字段与处理程序的match条件不匹配。

直接消息传递#

AutoGen核心中有两种通信类型：

直接消息: 向另一个代理发送直接消息。
广播: 向一个主题发布消息。

首先，我们来看看直接消息的功能。在消息处理程序中，可以使用autogen_core.BaseAgent.send_message()方法发送直接消息给另一个代理，在运行时使用autogen_core.AgentRuntime.send_message()方法。等待这些方法的调用将返回接收代理的消息处理程序的返回值。当接收代理的处理程序返回None时，将返回None。

注意

如果被调用的代理在发送者等待时引发异常，该异常将传播回发送者。

请求/响应#

直接消息传递可以用于请求/响应场景，其中发送者期望从接收者那里得到响应。接收者可以通过从其消息处理程序返回一个值来响应消息。您可以将其视为代理之间的函数调用。

例如，考虑以下代理：

from dataclasses import dataclass

from autogen_core import MessageContext, RoutedAgent, SingleThreadedAgentRuntime, message_handler


@dataclass
class Message:
    content: str


class InnerAgent(RoutedAgent):
    @message_handler
    async def on_my_message(self, message: Message, ctx: MessageContext) -> Message:
        return Message(content=f"Hello from inner, {message.content}")


class OuterAgent(RoutedAgent):
    def __init__(self, description: str, inner_agent_type: str):
        super().__init__(description)
        self.inner_agent_id = AgentId(inner_agent_type, self.id.key)

    @message_handler
    async def on_my_message(self, message: Message, ctx: MessageContext) -> None:
        print(f"Received message: {message.content}")
        # Send a direct message to the inner agent and receives a response.
        response = await self.send_message(Message(f"Hello from outer, {message.content}"), self.inner_agent_id)
        print(f"Received inner response: {response.content}")

收到消息后，OuterAgent 会直接发送一条消息给 InnerAgent 并接收一条响应消息。

我们可以通过向OuterAgent发送一个Message来测试这些代理。

runtime = SingleThreadedAgentRuntime()
await InnerAgent.register(runtime, "inner_agent", lambda: InnerAgent("InnerAgent"))
await OuterAgent.register(runtime, "outer_agent", lambda: OuterAgent("OuterAgent", "inner_agent"))
runtime.start()
outer_agent_id = AgentId("outer_agent", "default")
await runtime.send_message(Message(content="Hello, World!"), outer_agent_id)
await runtime.stop_when_idle()

Received message: Hello, World!
Received inner response: Hello from inner, Hello from outer, Hello, World!

两个输出都是由OuterAgent的消息处理器生成的，然而第二个输出是基于InnerAgent的响应。

一般来说，直接消息传递适用于发送者和接收者紧密耦合的场景——它们是一起创建的，并且发送者与接收者的特定实例相关联。例如，代理通过向ToolAgent的实例发送直接消息来执行工具调用，并使用响应形成行动-观察循环。

广播#

Broadcast 实际上是带有主题和订阅的发布/订阅模型。阅读主题和订阅以了解核心概念。

直接消息传递和广播之间的关键区别在于广播不能用于请求/响应场景。当代理发布消息时，它只是单向的，它不能从任何其他代理接收响应，即使接收代理的处理程序返回了一个值。

注意

如果对已发布的消息给出响应，它将被丢弃。

注意

如果代理发布了它订阅的消息类型，它将不会收到它发布的消息。这是为了防止无限循环。

订阅和发布主题#

基于类型的订阅将发布到特定主题类型的消息映射到特定代理类型的代理。要使一个代理继承自RoutedAgent 并订阅特定主题类型的主题，你可以使用type_subscription()类装饰器。

下面的示例展示了一个ReceiverAgent类，该类使用type_subscription()装饰器订阅"default"主题类型的主题，并打印接收到的消息。

from autogen_core import RoutedAgent, message_handler, type_subscription


@type_subscription(topic_type="default")
class ReceivingAgent(RoutedAgent):
    @message_handler
    async def on_my_message(self, message: Message, ctx: MessageContext) -> None:
        print(f"Received a message: {message.content}")

要从代理的处理程序中发布消息，请使用publish_message()方法并指定一个TopicId。此调用仍需要等待，以便运行时能够安排向所有订阅者传递消息，但它将始终返回None。如果代理在处理发布的消息时引发异常，这将记录但不会传播回发布代理。

以下示例展示了BroadcastingAgent在接收到消息时向主题发布消息的过程。

from autogen_core import TopicId


class BroadcastingAgent(RoutedAgent):
    @message_handler
    async def on_my_message(self, message: Message, ctx: MessageContext) -> None:
        await self.publish_message(
            Message("Publishing a message from broadcasting agent!"),
            topic_id=TopicId(type="default", source=self.id.key),
        )

BroadcastingAgent 将消息发布到类型为 "default" 的主题，并将源分配给代理实例的代理键。

订阅是通过agent运行时注册的，既可以作为agent类型注册的一部分，也可以通过单独的API方法进行注册。以下是我们如何使用type_subscription()装饰器为接收agent注册TypeSubscription，以及为广播agent注册时没有使用装饰器的示例。

from autogen_core import TypeSubscription

runtime = SingleThreadedAgentRuntime()

# Option 1: with type_subscription decorator
# The type_subscription class decorator automatically adds a TypeSubscription to
# the runtime when the agent is registered.
await ReceivingAgent.register(runtime, "receiving_agent", lambda: ReceivingAgent("Receiving Agent"))

# Option 2: with TypeSubscription
await BroadcastingAgent.register(runtime, "broadcasting_agent", lambda: BroadcastingAgent("Broadcasting Agent"))
await runtime.add_subscription(TypeSubscription(topic_type="default", agent_type="broadcasting_agent"))

# Start the runtime and publish a message.
runtime.start()
await runtime.publish_message(
    Message("Hello, World! From the runtime!"), topic_id=TopicId(type="default", source="default")
)
await runtime.stop_when_idle()

Received a message: Hello, World! From the runtime!
Received a message: Publishing a message from broadcasting agent!

如上例所示，你也可以直接通过运行时的publish_message()方法发布到主题，而无需创建代理实例。

从输出中可以看出，接收代理收到了两条消息：一条是通过运行时发布的，另一条是由广播代理发布的。

默认主题和订阅#

在上述示例中，我们使用了 TopicId 和 TypeSubscription 分别指定了主题和订阅。这对于许多场景来说是合适的方式。然而，当发布的范围是单一的，即所有代理都发布和订阅所有广播的消息时，我们可以使用便捷类 DefaultTopicId 和 default_subscription() 来简化我们的代码。

DefaultTopicId 用于创建一个主题，该主题使用 "default" 作为主题类型的默认值，并使用发布代理的密钥作为主题来源的默认值。default_subscription() 用于创建订阅默认主题的类型订阅。我们可以通过使用 DefaultTopicId 和 default_subscription() 来简化 BroadcastingAgent。

from autogen_core import DefaultTopicId, default_subscription


@default_subscription
class BroadcastingAgentDefaultTopic(RoutedAgent):
    @message_handler
    async def on_my_message(self, message: Message, ctx: MessageContext) -> None:
        # Publish a message to all agents in the same namespace.
        await self.publish_message(
            Message("Publishing a message from broadcasting agent!"),
            topic_id=DefaultTopicId(),
        )

当运行时调用register()来注册代理类型时，它会创建一个TypeSubscription，其主题类型使用"default"作为默认值，并且代理类型使用在同一上下文中正在注册的相同代理类型。

runtime = SingleThreadedAgentRuntime()
await BroadcastingAgentDefaultTopic.register(
    runtime, "broadcasting_agent", lambda: BroadcastingAgentDefaultTopic("Broadcasting Agent")
)
await ReceivingAgent.register(runtime, "receiving_agent", lambda: ReceivingAgent("Receiving Agent"))
runtime.start()
await runtime.publish_message(Message("Hello, World! From the runtime!"), topic_id=DefaultTopicId())
await runtime.stop_when_idle()

Received a message: Hello, World! From the runtime!
Received a message: Publishing a message from broadcasting agent!

注意

如果你的场景允许所有代理发布和订阅所有广播的消息，使用 DefaultTopicId 和 default_subscription() 来修饰你的代理类。