{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# 快速入门\n\n:::{note}\n安装说明请参见[此处](installation)。\n:::\n\n在深入核心API之前，我们先从一个简单的示例开始：两个从10倒数到1的智能体。\n\n我们首先定义智能体类及其各自处理消息的流程。\n创建两个智能体类：`Modifier`和`Checker`。`Modifier`智能体修改给定的数字，`Check`智能体根据条件检查该值。\n我们还创建了一个`Message`数据类，用于定义智能体之间传递的消息。\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 4,
      "metadata": {},
      "outputs": [],
      "source": [
        "from dataclasses import dataclass\n",
        "from typing import Callable\n",
        "\n",
        "from autogen_core import DefaultTopicId, MessageContext, RoutedAgent, default_subscription, message_handler\n",
        "\n",
        "\n",
        "@dataclass\n",
        "class Message:\n",
        "    content: int\n",
        "\n",
        "\n",
        "@default_subscription\n",
        "class Modifier(RoutedAgent):\n",
        "    def __init__(self, modify_val: Callable[[int], int]) -> None:\n",
        "        super().__init__(\"A modifier agent.\")\n",
        "        self._modify_val = modify_val\n",
        "\n",
        "    @message_handler\n",
        "    async def handle_message(self, message: Message, ctx: MessageContext) -> None:\n",
        "        val = self._modify_val(message.content)\n",
        "        print(f\"{'-'*80}\\nModifier:\\nModified {message.content} to {val}\")\n",
        "        await self.publish_message(Message(content=val), DefaultTopicId())  # type: ignore\n",
        "\n",
        "\n",
        "@default_subscription\n",
        "class Checker(RoutedAgent):\n",
        "    def __init__(self, run_until: Callable[[int], bool]) -> None:\n",
        "        super().__init__(\"A checker agent.\")\n",
        "        self._run_until = run_until\n",
        "\n",
        "    @message_handler\n",
        "    async def handle_message(self, message: Message, ctx: MessageContext) -> None:\n",
        "        if not self._run_until(message.content):\n",
        "            print(f\"{'-'*80}\\nChecker:\\n{message.content} passed the check, continue.\")\n",
        "            await self.publish_message(Message(content=message.content), DefaultTopicId())\n",
        "        else:\n",
        "            print(f\"{'-'*80}\\nChecker:\\n{message.content} failed the check, stopping.\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "你可能已经注意到，无论智能体逻辑是使用模型还是代码执行器，\n都与消息传递方式完全解耦。这是核心思想：框架提供\n通信基础设施，而智能体负责自己的逻辑。我们将这种通信基础设施称为**智能体运行时**。\n\n智能体运行时是本框架的核心概念。除了传递消息外，\n它还管理智能体的生命周期。\n因此智能体的创建由运行时处理。\n\n以下代码展示如何使用\n{py:class}`~autogen_core.SingleThreadedAgentRuntime`\n（一个本地嵌入式智能体运行时实现）来注册和运行智能体。\n\n```{note}\n如果使用VSCode或其他编辑器，请记得导入asyncio并用async def main() -> None:包裹代码，然后使用asyncio.run(main())函数运行代码。\n```\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "10 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 10 to 9\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "9 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 9 to 8\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "8 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 8 to 7\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "7 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 7 to 6\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "6 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 6 to 5\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "5 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 5 to 4\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "4 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 4 to 3\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "3 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 3 to 2\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "2 passed the check, continue.\n",
            "--------------------------------------------------------------------------------\n",
            "Modifier:\n",
            "Modified 2 to 1\n",
            "--------------------------------------------------------------------------------\n",
            "Checker:\n",
            "1 failed the check, stopping.\n"
          ]
        }
      ],
      "source": [
        "from autogen_core import AgentId, SingleThreadedAgentRuntime\n",
        "\n",
        "# 创建一个本地嵌入式运行时。\n",
        "runtime = SingleThreadedAgentRuntime()\n",
        "\n",
        "# 通过提供智能体类型、创建实例的工厂函数和订阅关系，\n",
        "# 来注册modifier和checker智能体。\n",
        "await Modifier.register(\n",
        "    runtime,\n",
        "    \"modifier\",\n",
        "    # 将值减1\n",
        "    lambda: Modifier(modify_val=lambda x: x - 1),\n",
        ")\n",
        "\n",
        "await Checker.register(\n",
        "    runtime,\n",
        "    \"checker\",\n",
        "    # 运行直到值小于或等于1\n",
        "    lambda: Checker(run_until=lambda x: x <= 1),\n",
        ")\n",
        "\n",
        "# 启动运行时并向检查器发送直接消息\n",
        "runtime.start()\n",
        "await runtime.send_message(Message(10), AgentId(\"checker\", \"default\"))\n",
        "await runtime.stop_when_idle()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "从代理输出中可以看到，根据修改器和检查器条件的要求，值已成功从10递减到1\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "AutoGen还支持分布式代理运行时，可以托管运行在不同进程或机器上的代理，这些代理可以具有不同的身份、语言和依赖项。\n\n要了解如何使用代理运行时、通信、消息处理和订阅功能，请继续阅读本快速入门之后的章节。\n"
      ]
    }
  ],
  "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.12.3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 2
}