类class agentscope.state

AgentState

class AgentState(BaseModel)

源码Source agentscope/state/_state.py:209–403

AgentState 保存一次会话的全部可变状态：消息上下文、回复上下文、权限、工具与任务上下文。它让智能体可以在进程重启后恢复，也支持同一会话的并发控制。位于 agentscope.state 包。核心成员包括 reply_id、cur_iter、append_context、has_awaiting_tool_calls、get_awaiting_tool_calls、get_unfinished_tool_calls。

The agent state that should be saved and loaded from storage. Declared in agentscope.state.

核心精讲Deep dive

AgentState：可持久化的会话状态AgentState: persistable session state

AgentState 保存一次会话的全部可变状态：消息上下文、回复上下文、权限、工具与任务上下文。它让智能体可以在进程重启后恢复，也支持同一会话的并发控制。

AgentState stores all mutable state of a session: message context, reply context, permissions, tool and task context. It lets agents resume after a restart and supports concurrency control for the same session.

session_id 标识会话，context 保存消息列表。session_id identifies the session and context stores the message list.
reply_id 与 cur_iter 跟踪当前回复及迭代进度。reply_id and cur_iter track the current reply and iteration progress.
把 state 传给 Agent 即可复用上下文；外部存储可序列化整个对象。Passing state to Agent reuses the context; external stores can persist the whole object.

跨轮复用同一份状态Reuse one state across turns

import asyncio
import os

from agentscope.agent import Agent
from agentscope.credential import OpenAICredential
from agentscope.message import UserMsg
from agentscope.model import OpenAIChatModel
from agentscope.state import AgentState

state = AgentState(session_id="demo-session")
model = OpenAIChatModel(
    credential=OpenAICredential(api_key=os.environ["OPENAI_API_KEY"]),
    model="gpt-4.1-mini",
)


async def main() -> None:
    agent = Agent(
        name="assistant",
        system_prompt="You are a helpful assistant.",
        model=model,
        state=state,
    )
    await agent.reply(UserMsg("user", "My name is Alice."))
    await agent.reply(UserMsg("user", "What is my name?"))
    print(state.session_id, len(state.context))


asyncio.run(main())

属性摘要Property Summary

属性Property	说明Description
`reply_id`	当前回复的唯一标识。 The reply id of the current reply.
`cur_iter`	当前回复已执行的迭代轮数。 The current iteration of the agent's reasoning-acting loop in this reply.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`session_id`	str	会话标识字段。	`Field(default_factory=_generate_id)`
`summary`	str \| list[TextBlock \| DataBlock]	摘要字段。	`''`
`context`	list[Msg]	上下文字段。	`Field(default_factory=list)`
`reply_context`	ReplyContext	回复上下文字段。	`Field(default_factory=ReplyContext)`
`permission_context`	PermissionContext	权限上下文字段。	`Field(default_factory=PermissionContext)`
`tool_context`	ToolContext	工具上下文字段。	`Field(default_factory=ToolContext)`
`tasks_context`	TaskContext	任务上下文字段。	`Field(default_factory=TaskContext)`
`middle_context`	dict[str, Any]	`middle_context` 字段。	`Field(default_factory=dict)`

方法摘要Method Summary

方法Method	说明Description
`def reply_id(value: str) -> None`reply_id.setter	当前回复的唯一标识。 Set the reply id of the current reply.
`def cur_iter(value: int) -> None`cur_iter.setter	当前回复已执行的迭代轮数。 Set the current iteration of the agent's reasoning-acting loop in this reply.
`def append_context(name: str, blocks: list[TextBlock \| DataBlock \| HintBlock \| ToolCallBlock \| ToolResultBlock]) -> None`	向指定名称的上下文追加内容块。 Append the given blocks to the agent's own message with the current `reply_id`. If such message doesn't exist, a new assistant message with agent's name and current reply ID will be created.
`def has_awaiting_tool_calls(name: str) -> bool`	判断是否存在等待外部结果的工具调用。 Whether the tail assistant message written by ``name`` has any tool call still awaiting an outside response — an ``ASKING`` user confirmation or a ``SUBMITTED`` external execution with no matching tool result yet.
`def get_awaiting_tool_calls(name: str) -> list[ToolCallBlock]`	返回等待外部结果的工具调用列表。 Get the tail assistant message's tool calls still awaiting an outside response — an ``ASKING`` user confirmation or a ``SUBMITTED`` external execution with no matching tool result yet.
`def get_unfinished_tool_calls(name: str) -> list[ToolCallBlock]`	返回尚未完成的工具调用列表。 Get the current reply's tool calls with no matching tool result yet, whatever their state. A reply accumulates into a single message, so the calls of the finished reasoning-acting rounds are excluded while the ones of the ongoing round are returned.

属性详情Attribute Detail

session_id

str = Field(default_factory=_generate_id)

会话标识字段。声明为 str。

The session id field.

源码Source agentscope/state/_state.py:212

summary

str | list[TextBlock | DataBlock] = ''

摘要字段。声明为 str | list[TextBlock | DataBlock]。

The summary field.

源码Source agentscope/state/_state.py:216

context

list[Msg] = Field(default_factory=list)

上下文字段。声明为 list[Msg]。

The context field.

源码Source agentscope/state/_state.py:220

reply_context

ReplyContext = Field(default_factory=ReplyContext)

回复上下文字段。声明为 ReplyContext。

The reply context field.

源码Source agentscope/state/_state.py:268

permission_context

PermissionContext = Field(default_factory=PermissionContext)

权限上下文字段。声明为 PermissionContext。

The permission context field.

源码Source agentscope/state/_state.py:274

tool_context

ToolContext = Field(default_factory=ToolContext)

工具上下文字段。声明为 ToolContext。

The tool context field.

源码Source agentscope/state/_state.py:283

tasks_context

TaskContext = Field(default_factory=TaskContext)

任务上下文字段。声明为 TaskContext。

The tasks context field.

源码Source agentscope/state/_state.py:288

middle_context

dict[str, Any] = Field(default_factory=dict)

middle_context 字段。声明为 dict[str, Any]。

The middle context field.

源码Source agentscope/state/_state.py:294

属性详情Property Detail

reply_id

def reply_id() -> str

当前回复的回复标识。

The reply id of the current reply.

返回Returns str

返回字符串结果。Returns a string.

源码Source agentscope/state/_state.py:244–246

cur_iter

def cur_iter() -> int

获取当前迭代次数。

The current iteration of the agent's reasoning-acting loop in this reply.

返回Returns int

返回数值结果。Returns a numeric result.

源码Source agentscope/state/_state.py:254–257

方法详情Method Detail

reply_id

def reply_id(value: str) -> None

reply_id.setter

当前回复的回复标识。

The reply id of the current reply.

参数Parameters

名称Name	类型Type	说明Description
`value`	str	值（类型 `str`）。The value.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/state/_state.py:249–251

cur_iter

def cur_iter(value: int) -> None

cur_iter.setter

获取当前迭代次数。

The current iteration of the agent's reasoning-acting loop in this reply.

参数Parameters

名称Name	类型Type	说明Description
`value`	int	值（类型 `int`）。The value.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/state/_state.py:260–263

append_context

def append_context(name: str, blocks: list[TextBlock | DataBlock | HintBlock | ToolCallBlock | ToolResultBlock]) -> None

追加上下文。

Append the given blocks to the agent's own message with the current reply_id.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	名称（类型 `str`）。The name.
`blocks`	list[TextBlock \| DataBlock \| HintBlock \| ToolCallBlock \| ToolResultBlock]	内容块列表（类型 `list[TextBlock \| DataBlock \| HintBlock \| ToolCallBlock \| ToolResultBlock]`）。The blocks.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/state/_state.py:298–326

has_awaiting_tool_calls

def has_awaiting_tool_calls(name: str) -> bool

判断是否具有等待中的工具调用。

Whether the tail assistant message written by name has any tool call still awaiting an outside response — an ASKING user confirmation or a SUBMITTED external execution with no matching tool result yet.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	名称（类型 `str`）。Only messages authored by this agent name are inspected; observed messages from other agents are ignored.

返回Returns bool

返回布尔值，表示判断结果。`bool`:

源码Source agentscope/state/_state.py:328–343

get_awaiting_tool_calls

def get_awaiting_tool_calls(name: str) -> list[ToolCallBlock]

获取等待中的工具调用。

Get the tail assistant message's tool calls still awaiting an outside response — an ASKING user confirmation or a SUBMITTED external execution with no matching tool result yet.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	名称（类型 `str`）。Only messages authored by this agent name are inspected; observed messages from other agents are ignored.

返回Returns list[ToolCallBlock]

返回ToolCallBlock列表。`list[ToolCallBlock]`:

源码Source agentscope/state/_state.py:345–372

get_unfinished_tool_calls

def get_unfinished_tool_calls(name: str) -> list[ToolCallBlock]

获取未完成的工具调用。

Get the current reply's tool calls with no matching tool result yet, whatever their state.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	名称（类型 `str`）。Only messages authored by this agent name are inspected; observed messages from other agents are ignored.

返回Returns list[ToolCallBlock]

返回ToolCallBlock列表。`list[ToolCallBlock]`:

源码Source agentscope/state/_state.py:374–403