注意
Go to the end 下载完整示例代码。
状态/会话管理¶
在AgentScope中，“state”指的是智能体在运行应用中的状态，包括其当前的系统提示、记忆、上下文、配备工具以及其他随时间变化的信息。
为了管理应用程序的状态，AgentScope设计了一个自动状态注册系统和会话级状态管理，其特点包括：
支持对所有继承自
StateModule的变量进行自动状态注册支持使用自定义序列化/反序列化方法进行手动状态注册
支持 会话/应用级管理功能
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
状态模块¶
StateModule类是AgentScope中状态管理的基础，提供三个基本功能：
Method |
Arguments |
Description |
|---|---|---|
|
attr_name,custom_to_json (optional),custom_from_json (optional) |
将属性注册为智能体状态，可选择性地使用序列化/反序列化函数。 |
|
- |
获取当前对象的状态字典 |
|
state_dict,strict (optional) |
加载状态字典至当前对象 |
在一个StateModule对象中，所有以下属性都被视为其状态的一部分：
继承自
StateModule的 属性register_state方法注册的 属性
StateModule 支持 嵌套的 序列化和反序列化：
class ClassA(StateModule):
def __init__(self) -> None:
super().__init__()
self.cnt = 123
# register cnt attribute as state
self.register_state("cnt")
class ClassB(StateModule):
def __init__(self) -> None:
super().__init__()
# attribute "a" inherits from StateModule
self.a = ClassA()
# register attribute "c" as state manually
self.c = "Hello, world!"
self.register_state("c")
obj_b = ClassB()
print("State of obj_b.a:")
print(obj_b.a.state_dict())
print("\nState of obj_b:")
print(json.dumps(obj_b.state_dict(), indent=4))
State of obj_b.a:
{'cnt': 123}
State of obj_b:
{
"a": {
"cnt": 123
},
"c": "Hello, world!"
}
obj_b的状态自动包含了其属性a的状态。
在agentscope中，AgentBase、MemoryBase、LongTermMemoryBase 和 Toolkit 类都继承自 StateModule，因此支持自动和嵌套状态管理。
# Creating an agent
agent = ReActAgent(
name="Friday",
sys_prompt="You're a assistant named 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("Initial state of the agent:")
print(json.dumps(initial_state, indent=4))
Initial state of the agent:
{
"memory": {
"content": []
},
"toolkit": {
"active_groups": []
},
"name": "Friday",
"_sys_prompt": "You're a assistant named Friday."
}
然后我们通过生成回复消息来更改其状态：
async def example_agent_state() -> None:
"""Example of agent state management"""
await agent(Msg("user", "Hello, agent!", "user"))
print("State of the agent after generating a reply:")
print(json.dumps(agent.state_dict(), indent=4))
asyncio.run(example_agent_state())
Friday: Hello! How can I assist you today?
State of the agent after generating a reply:
{
"memory": {
"content": [
{
"id": "2bkgGJwVWBf39KPweifbY4",
"name": "user",
"role": "user",
"content": "Hello, agent!",
"metadata": null,
"timestamp": "2025-09-08 07:56:01.212"
},
{
"id": "JpVy6Pxi7MvzHADK9XYypM",
"name": "Friday",
"role": "assistant",
"content": [
{
"id": "B9EiDvGixP6j76DiMD8eaA",
"type": "tool_use",
"name": "generate_response",
"input": {
"response": "Hello! How can I assist you today?"
}
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:01.212"
},
{
"id": "Wr66hftVhiuQ6vmoUfBKjA",
"name": "system",
"role": "system",
"content": [
{
"type": "tool_result",
"id": "B9EiDvGixP6j76DiMD8eaA",
"name": "generate_response",
"output": [
{
"type": "text",
"text": "Successfully generated response."
}
]
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:03.025"
},
{
"id": "mssqC9TRyjT6uxsfqrYVgq",
"name": "Friday",
"role": "assistant",
"content": "Hello! How can I assist you today?",
"metadata": null,
"timestamp": "2025-09-08 07:56:03.025"
}
]
},
"toolkit": {
"active_groups": []
},
"name": "Friday",
"_sys_prompt": "You're a assistant named Friday."
}
现在我们将智能体状态恢复到初始状态：
agent.load_state_dict(initial_state)
print("State after loading the initial state:")
print(json.dumps(agent.state_dict(), indent=4))
State after loading the initial state:
{
"memory": {
"content": []
},
"toolkit": {
"active_groups": []
},
"name": "Friday",
"_sys_prompt": "You're a assistant named Friday."
}
会话管理¶
在AgentScope中，会话（session）指的是应用中StateModule的集合，例如多个智能体。
Agentscope 提供了一个 SessionBase 类，它包含两个用于会话管理的抽象方法：save_session_state 和 load_session_state。开发者可以利用自己的存储解决方案来实现这些方法。
在AgentScope中，我们提供了一个基于JSON的会话类JSONSession，它
以会话ID命名的JSON文件中存储/加载会话状态。
这里我们展示如何在AgentScope中使用基于JSON的会话管理。
保存会话状态¶
# change the agent state by generating a reply message
asyncio.run(example_agent_state())
print("\nState of agent:")
print(json.dumps(agent.state_dict(), indent=4))
Friday: Hello! How can I assist you today?
State of the agent after generating a reply:
{
"memory": {
"content": [
{
"id": "Ejj97TNNUKbwGfi8tLZiqc",
"name": "user",
"role": "user",
"content": "Hello, agent!",
"metadata": null,
"timestamp": "2025-09-08 07:56:03.028"
},
{
"id": "d75RyvUvxysHnYUumfahmK",
"name": "Friday",
"role": "assistant",
"content": [
{
"id": "JdmWjruLUtKLZhfJKphFQU",
"type": "tool_use",
"name": "generate_response",
"input": {
"response": "Hello! How can I assist you today?"
}
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:03.028"
},
{
"id": "jBVhC6uPisWXLFkonuJwwE",
"name": "system",
"role": "system",
"content": [
{
"type": "tool_result",
"id": "JdmWjruLUtKLZhfJKphFQU",
"name": "generate_response",
"output": [
{
"type": "text",
"text": "Successfully generated response."
}
]
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:04.771"
},
{
"id": "6vQcBrfFniLvr7VoPELT2k",
"name": "Friday",
"role": "assistant",
"content": "Hello! How can I assist you today?",
"metadata": null,
"timestamp": "2025-09-08 07:56:04.771"
}
]
},
"toolkit": {
"active_groups": []
},
"name": "Friday",
"_sys_prompt": "You're a assistant named Friday."
}
State of agent:
{
"memory": {
"content": [
{
"id": "Ejj97TNNUKbwGfi8tLZiqc",
"name": "user",
"role": "user",
"content": "Hello, agent!",
"metadata": null,
"timestamp": "2025-09-08 07:56:03.028"
},
{
"id": "d75RyvUvxysHnYUumfahmK",
"name": "Friday",
"role": "assistant",
"content": [
{
"id": "JdmWjruLUtKLZhfJKphFQU",
"type": "tool_use",
"name": "generate_response",
"input": {
"response": "Hello! How can I assist you today?"
}
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:03.028"
},
{
"id": "jBVhC6uPisWXLFkonuJwwE",
"name": "system",
"role": "system",
"content": [
{
"type": "tool_result",
"id": "JdmWjruLUtKLZhfJKphFQU",
"name": "generate_response",
"output": [
{
"type": "text",
"text": "Successfully generated response."
}
]
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:04.771"
},
{
"id": "6vQcBrfFniLvr7VoPELT2k",
"name": "Friday",
"role": "assistant",
"content": "Hello! How can I assist you today?",
"metadata": null,
"timestamp": "2025-09-08 07:56:04.771"
}
]
},
"toolkit": {
"active_groups": []
},
"name": "Friday",
"_sys_prompt": "You're a assistant named Friday."
}
接着我们将其保存到一个会话文件中：
session = JSONSession(
session_id="session_2025-08-08", # Use the time as session id
save_dir="./user-bob/", # Use the username as the save directory
)
async def example_session() -> None:
"""Example of session management."""
await session.save_session_state(
agent=agent,
)
print("The saved state:")
with open(session.save_path, "r", encoding="utf-8") as f:
print(json.dumps(json.load(f), indent=4))
asyncio.run(example_session())
The saved state:
{
"agent": {
"memory": {
"content": [
{
"id": "Ejj97TNNUKbwGfi8tLZiqc",
"name": "user",
"role": "user",
"content": "Hello, agent!",
"metadata": null,
"timestamp": "2025-09-08 07:56:03.028"
},
{
"id": "d75RyvUvxysHnYUumfahmK",
"name": "Friday",
"role": "assistant",
"content": [
{
"id": "JdmWjruLUtKLZhfJKphFQU",
"type": "tool_use",
"name": "generate_response",
"input": {
"response": "Hello! How can I assist you today?"
}
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:03.028"
},
{
"id": "jBVhC6uPisWXLFkonuJwwE",
"name": "system",
"role": "system",
"content": [
{
"type": "tool_result",
"id": "JdmWjruLUtKLZhfJKphFQU",
"name": "generate_response",
"output": [
{
"type": "text",
"text": "Successfully generated response."
}
]
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:04.771"
},
{
"id": "6vQcBrfFniLvr7VoPELT2k",
"name": "Friday",
"role": "assistant",
"content": "Hello! How can I assist you today?",
"metadata": null,
"timestamp": "2025-09-08 07:56:04.771"
}
]
},
"toolkit": {
"active_groups": []
},
"name": "Friday",
"_sys_prompt": "You're a assistant named Friday."
}
}
加载会话状态¶
现在我们加载已保存文件中的会话状态：
async def example_load_session() -> None:
"""Example of loading session state."""
# we first clear the memory of the agent
await agent.memory.clear()
print("Current state of the agent:")
print(json.dumps(agent.state_dict(), indent=4))
# then we load the session state
await session.load_session_state(
# The keyword argument must be the same as the one used in `save_session_state`
agent=agent,
)
print("After loading the session state:")
print(json.dumps(agent.state_dict(), indent=4))
asyncio.run(example_load_session())
Current state of the agent:
{
"memory": {
"content": []
},
"toolkit": {
"active_groups": []
},
"name": "Friday",
"_sys_prompt": "You're a assistant named Friday."
}
After loading the session state:
{
"memory": {
"content": [
{
"id": "Ejj97TNNUKbwGfi8tLZiqc",
"name": "user",
"role": "user",
"content": "Hello, agent!",
"metadata": null,
"timestamp": "2025-09-08 07:56:03.028"
},
{
"id": "d75RyvUvxysHnYUumfahmK",
"name": "Friday",
"role": "assistant",
"content": [
{
"id": "JdmWjruLUtKLZhfJKphFQU",
"type": "tool_use",
"name": "generate_response",
"input": {
"response": "Hello! How can I assist you today?"
}
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:03.028"
},
{
"id": "jBVhC6uPisWXLFkonuJwwE",
"name": "system",
"role": "system",
"content": [
{
"type": "tool_result",
"id": "JdmWjruLUtKLZhfJKphFQU",
"name": "generate_response",
"output": [
{
"type": "text",
"text": "Successfully generated response."
}
]
}
],
"metadata": null,
"timestamp": "2025-09-08 07:56:04.771"
},
{
"id": "6vQcBrfFniLvr7VoPELT2k",
"name": "Friday",
"role": "assistant",
"content": "Hello! How can I assist you today?",
"metadata": null,
"timestamp": "2025-09-08 07:56:04.771"
}
]
},
"toolkit": {
"active_groups": []
},
"name": "Friday",
"_sys_prompt": "You're a assistant named Friday."
}
现在我们可以看到代理的状态已经恢复到保存的状态。
脚本总运行时间： (0 分 3.570 秒)