.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "tutorial/task_state.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_tutorial_task_state.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_tutorial_task_state.py:


.. _state:

状态/会话管理
=================================

在 AgentScope 中，**"状态"** 是指智能体在运行中某一时刻的数据快照，包括其当前的系统提示、记忆、上下文、装备的工具以及其他 **随时间变化** 的信息。

为了管理应用程序的状态，AgentScope 设计实现了 **自动状态注册** 和 **会话级状态管理**，具有以下特性：

- 支持所有继承自 ``StateModule`` 的变量的 **自动状态注册**
- 支持使用自定义序列化/反序列化方法的 **手动状态注册**
- 支持 **会话/应用程序级别管理**

.. GENERATED FROM PYTHON SOURCE LINES 16-29

.. code-block:: Python

    import asyncio
    import json
    import os

    from agentscope.agent import ReActAgent
    from agentscope.formatter import DashScopeChatFormatter
    from agentscope.memory import InMemoryMemory
    from agentscope.message import Msg
    from agentscope.model import DashScopeChatModel
    from agentscope.module import StateModule
    from agentscope.session import JSONSession
    from agentscope.tool import Toolkit








.. GENERATED FROM PYTHON SOURCE LINES 30-61

状态模块
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``StateModule`` 类是 AgentScope 中状态管理的基础，提供三个基本函数：

.. list-table:: ``StateModule`` 的方法
    :header-rows: 1

    * - 方法
      - 参数
      - 描述
    * - ``register_state``
      - | ``attr_name``,
        | ``custom_to_json``（可选）,
        | ``custom_from_json``（可选）
      - 将属性注册为其状态，带有可选的序列化/反序列化函数。
    * - ``state_dict``
      -
      - 获取当前对象的状态字典
    * - ``load_state_dict``
      - | ``state_dict``,
        | ``strict``（可选）
      - 将状态字典加载到当前对象

在 ``StateModule`` 的对象中，以下所有属性都将被视为其状态的一部分：

- 继承自 ``StateModule`` 的 **属性**
- 通过 ``register_state`` 方法注册的 **属性**

注意 ``StateModule`` 支持 **嵌套** 序列化和反序列化，例如下面的示例中，``ClassB`` 中包含一个 ``ClassA`` 的实例：


.. GENERATED FROM PYTHON SOURCE LINES 61-91

.. code-block:: Python



    class ClassA(StateModule):
        def __init__(self) -> None:
            super().__init__()
            self.cnt = 123
            # 将 cnt 属性注册为状态
            self.register_state("cnt")


    class ClassB(StateModule):
        def __init__(self) -> None:
            super().__init__()

            # 属性 "a" 继承自 StateModule，将自动视为状态的一部分
            self.a = ClassA()

            # 手动将属性 "c" 注册为状态
            self.c = "Hello, world!"
            self.register_state("c")


    obj_b = ClassB()

    print("obj_b.a 的状态：")
    print(obj_b.a.state_dict())

    print("\nobj_b 的状态：")
    print(json.dumps(obj_b.state_dict(), indent=4))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    obj_b.a 的状态：
    {'cnt': 123}

    obj_b 的状态：
    {
        "a": {
            "cnt": 123
        },
        "c": "Hello, world!"
    }




.. GENERATED FROM PYTHON SOURCE LINES 92-96

我们可以观察到 ``obj_b`` 的状态自动包含了其属性 ``a`` 的状态。

在 AgentScope 中，``AgentBase``、``MemoryBase``、``LongTermMemoryBase`` 和 ``Toolkit`` 类都继承自 ``StateModule``，因此支持自动和嵌套状态管理。


.. GENERATED FROM PYTHON SOURCE LINES 96-115

.. code-block:: Python


    # 创建一个智能体
    agent = ReActAgent(
        name="Friday",
        sys_prompt="你是一个名为 Friday 的助手。",
        model=DashScopeChatModel(
            model_name="qwen-max",
            api_key=os.environ["DASHSCOPE_API_KEY"],
        ),
        formatter=DashScopeChatFormatter(),
        memory=InMemoryMemory(),
        toolkit=Toolkit(),
    )

    initial_state = agent.state_dict()

    print("智能体的初始状态：")
    print(json.dumps(initial_state, indent=4, ensure_ascii=False))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    智能体的初始状态：
    {
        "memory": {
            "content": []
        },
        "toolkit": {
            "active_groups": []
        },
        "name": "Friday",
        "_sys_prompt": "你是一个名为 Friday 的助手。"
    }




.. GENERATED FROM PYTHON SOURCE LINES 116-118

然后我们通过生成回复消息来改变其状态：


.. GENERATED FROM PYTHON SOURCE LINES 118-130

.. code-block:: Python



    async def example_agent_state() -> None:
        """智能体状态管理示例。"""
        await agent(Msg("user", "你好，智能体！", "user"))

        print("生成回复后智能体的状态：")
        print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))


    asyncio.run(example_agent_state())





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Friday: 你好！有什么我能帮助你的吗？
    生成回复后智能体的状态：
    {
        "memory": {
            "content": [
                {
                    "id": "UTtundaKxWcWoasTPxa92b",
                    "name": "user",
                    "role": "user",
                    "content": "你好，智能体！",
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:33.570"
                },
                {
                    "id": "HvtMXtpRg2Dg6eMSkySKbC",
                    "name": "Friday",
                    "role": "assistant",
                    "content": [
                        {
                            "id": "EcfyFnVqdP7tiNaKYYEH8y",
                            "type": "tool_use",
                            "name": "generate_response",
                            "input": {
                                "response": "你好！有什么我能帮助你的吗？"
                            }
                        }
                    ],
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:33.570"
                },
                {
                    "id": "fMcejZo7xNyF4NFXRkZSPN",
                    "name": "system",
                    "role": "system",
                    "content": [
                        {
                            "type": "tool_result",
                            "id": "EcfyFnVqdP7tiNaKYYEH8y",
                            "name": "generate_response",
                            "output": [
                                {
                                    "type": "text",
                                    "text": "Successfully generated response."
                                }
                            ]
                        }
                    ],
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:35.015"
                },
                {
                    "id": "Ym5BaJiw8n6jWVhx7HiMZW",
                    "name": "Friday",
                    "role": "assistant",
                    "content": "你好！有什么我能帮助你的吗？",
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:35.015"
                }
            ]
        },
        "toolkit": {
            "active_groups": []
        },
        "name": "Friday",
        "_sys_prompt": "你是一个名为 Friday 的助手。"
    }




.. GENERATED FROM PYTHON SOURCE LINES 131-133

现在我们将智能体的状态恢复到初始状态：


.. GENERATED FROM PYTHON SOURCE LINES 133-139

.. code-block:: Python


    agent.load_state_dict(initial_state)

    print("加载初始状态后：")
    print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    加载初始状态后：
    {
        "memory": {
            "content": []
        },
        "toolkit": {
            "active_groups": []
        },
        "name": "Friday",
        "_sys_prompt": "你是一个名为 Friday 的助手。"
    }




.. GENERATED FROM PYTHON SOURCE LINES 140-154

会话管理
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

会话（Session）是应用程序中状态的集合，例如多个智能体。

AgentScope 提供了 ``SessionBase`` 类，包含两个用于会话管理的抽象方法：``save_session_state`` 和 ``load_session_state``。
开发者可以继承该类来实现自己的状态保存方案，例如对接到自己的数据库或文件系统。

在 AgentScope 中，我们提供了基于 JSON 和文件系统的的会话类 ``JSONSession``，
它会将状态保存到会化 ID 命名的 JSON 文件中，也可以从中加载状态。

保存会话状态
-----------------------------------------


.. GENERATED FROM PYTHON SOURCE LINES 154-161

.. code-block:: Python


    # 通过生成回复消息改变智能体状态
    asyncio.run(example_agent_state())

    print("\n智能体的状态：")
    print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Friday: 你好！有什么我能为你做的吗？
    生成回复后智能体的状态：
    {
        "memory": {
            "content": [
                {
                    "id": "bPGK3LFH3mQXs6mFJisFKU",
                    "name": "user",
                    "role": "user",
                    "content": "你好，智能体！",
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:35.018"
                },
                {
                    "id": "KX47UYXejHgeYrF9BEaahp",
                    "name": "Friday",
                    "role": "assistant",
                    "content": [
                        {
                            "id": "UHNB946w3u8MaHT6AQyG3g",
                            "type": "tool_use",
                            "name": "generate_response",
                            "input": {
                                "response": "你好！有什么我能为你做的吗？"
                            }
                        }
                    ],
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:35.019"
                },
                {
                    "id": "jbUFPyi3zyNo8xV8V8KBYs",
                    "name": "system",
                    "role": "system",
                    "content": [
                        {
                            "type": "tool_result",
                            "id": "UHNB946w3u8MaHT6AQyG3g",
                            "name": "generate_response",
                            "output": [
                                {
                                    "type": "text",
                                    "text": "Successfully generated response."
                                }
                            ]
                        }
                    ],
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:36.722"
                },
                {
                    "id": "7Cyq8R6Pai6t3o43TVRtag",
                    "name": "Friday",
                    "role": "assistant",
                    "content": "你好！有什么我能为你做的吗？",
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:36.722"
                }
            ]
        },
        "toolkit": {
            "active_groups": []
        },
        "name": "Friday",
        "_sys_prompt": "你是一个名为 Friday 的助手。"
    }

    智能体的状态：
    {
        "memory": {
            "content": [
                {
                    "id": "bPGK3LFH3mQXs6mFJisFKU",
                    "name": "user",
                    "role": "user",
                    "content": "你好，智能体！",
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:35.018"
                },
                {
                    "id": "KX47UYXejHgeYrF9BEaahp",
                    "name": "Friday",
                    "role": "assistant",
                    "content": [
                        {
                            "id": "UHNB946w3u8MaHT6AQyG3g",
                            "type": "tool_use",
                            "name": "generate_response",
                            "input": {
                                "response": "你好！有什么我能为你做的吗？"
                            }
                        }
                    ],
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:35.019"
                },
                {
                    "id": "jbUFPyi3zyNo8xV8V8KBYs",
                    "name": "system",
                    "role": "system",
                    "content": [
                        {
                            "type": "tool_result",
                            "id": "UHNB946w3u8MaHT6AQyG3g",
                            "name": "generate_response",
                            "output": [
                                {
                                    "type": "text",
                                    "text": "Successfully generated response."
                                }
                            ]
                        }
                    ],
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:36.722"
                },
                {
                    "id": "7Cyq8R6Pai6t3o43TVRtag",
                    "name": "Friday",
                    "role": "assistant",
                    "content": "你好！有什么我能为你做的吗？",
                    "metadata": null,
                    "timestamp": "2025-08-27 03:49:36.722"
                }
            ]
        },
        "toolkit": {
            "active_groups": []
        },
        "name": "Friday",
        "_sys_prompt": "你是一个名为 Friday 的助手。"
    }




.. GENERATED FROM PYTHON SOURCE LINES 162-163

然后我们将其保存到会话文件中：

.. GENERATED FROM PYTHON SOURCE LINES 163-185

.. code-block:: Python


    session = JSONSession(
        session_id="session_2025-08-08",  # 使用时间作为会话 ID
        save_dir="./user-bob/",  # 使用用户名作为保存目录
    )


    async def example_session() -> None:
        """会话管理示例。"""

        # 可以保存多个状态，只需要输入的对象为 ``StateModule`` 的子类。
        await session.save_session_state(
            agent=agent,
        )

        print("保存的状态：")
        with open(session.save_path, "r", encoding="utf-8") as f:
            print(json.dumps(json.load(f), indent=4, ensure_ascii=False))


    asyncio.run(example_session())





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    保存的状态：
    {
        "agent": {
            "memory": {
                "content": [
                    {
                        "id": "bPGK3LFH3mQXs6mFJisFKU",
                        "name": "user",
                        "role": "user",
                        "content": "你好，智能体！",
                        "metadata": null,
                        "timestamp": "2025-08-27 03:49:35.018"
                    },
                    {
                        "id": "KX47UYXejHgeYrF9BEaahp",
                        "name": "Friday",
                        "role": "assistant",
                        "content": [
                            {
                                "id": "UHNB946w3u8MaHT6AQyG3g",
                                "type": "tool_use",
                                "name": "generate_response",
                                "input": {
                                    "response": "你好！有什么我能为你做的吗？"
                                }
                            }
                        ],
                        "metadata": null,
                        "timestamp": "2025-08-27 03:49:35.019"
                    },
                    {
                        "id": "jbUFPyi3zyNo8xV8V8KBYs",
                        "name": "system",
                        "role": "system",
                        "content": [
                            {
                                "type": "tool_result",
                                "id": "UHNB946w3u8MaHT6AQyG3g",
                                "name": "generate_response",
                                "output": [
                                    {
                                        "type": "text",
                                        "text": "Successfully generated response."
                                    }
                                ]
                            }
                        ],
                        "metadata": null,
                        "timestamp": "2025-08-27 03:49:36.722"
                    },
                    {
                        "id": "7Cyq8R6Pai6t3o43TVRtag",
                        "name": "Friday",
                        "role": "assistant",
                        "content": "你好！有什么我能为你做的吗？",
                        "metadata": null,
                        "timestamp": "2025-08-27 03:49:36.722"
                    }
                ]
            },
            "toolkit": {
                "active_groups": []
            },
            "name": "Friday",
            "_sys_prompt": "你是一个名为 Friday 的助手。"
        }
    }




.. GENERATED FROM PYTHON SOURCE LINES 186-190

加载会话状态
-----------------------------------------
然后我们可以从会话文件中加载状态：


.. GENERATED FROM PYTHON SOURCE LINES 190-210

.. code-block:: Python



    async def example_load_session() -> None:
        """加载会话状态示例。"""

        # 清空智能体状态
        await agent.memory.clear()

        print("当前智能体状态：")
        print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))

        # 从会话文件中加载状态
        await session.load_session_state(
            # 这里使用的关键词参数必须与 ``save_session_state`` 中的参数一致
            agent=agent,
        )
        print("加载会话状态后智能体的状态：")
        print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))









.. GENERATED FROM PYTHON SOURCE LINES 211-213

此时我们可以观察到智能体的状态已经恢复到之前保存的状态。



.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 3.162 seconds)


.. _sphx_glr_download_tutorial_task_state.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: task_state.ipynb <task_state.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: task_state.py <task_state.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: task_state.zip <task_state.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_