类class io.agentscope.core.state 2.x

AgentState

@JsonPropertyOrder({ "session_id", "user_id", "summary", "context", "reply_id", "cur_iter", "shutdown_interrupted", "permission_context", "tool_context", "tasks_context", "plan_mode_context" }) public final class AgentState implements State

源码Source io/agentscope/core/state/AgentState.java:44–394

AgentState 保存 Java 智能体的上下文、摘要、回复进度、权限、工具与任务状态。构建器负责构造，AgentStateStore 负责跨进程持久化。位于 io.agentscope.core.state 包，实现 State。核心成员包括 getSessionId、getUserId、getSummary、setSummary、getContext、contextMutable。

Mutable per-agent runtime state.

Carries everything a single agent needs to resume mid-conversation: the conversation buffer, a rolling summary, the per-iteration reply identifier, the permission/tool/task sub-contexts, and a counter for the current reasoning iteration.

The #context list is exposed as a defensive copy via #getContext() and as a live, mutable handle via #contextMutable(), mirroring the pattern used by TaskContextState. Storage layers may swap whole AgentState instances or mutate the inner collections in place.

summary is modelled as a free-form String; richer structured forms are left for future iterations once context-compression strategies require them.

核心精讲Deep dive

AgentState：会话状态AgentState: session state

AgentState 保存 Java 智能体的上下文、摘要、回复进度、权限、工具与任务状态。Builder 负责构造，AgentStateStore 负责跨进程持久化。

AgentState stores the Java agent's context, summary, reply progress, permissions, tool and task state. The builder constructs it, and AgentStateStore persists it across processes.

builder 可设置 sessionId、userId、context 与各类子上下文。The builder sets sessionId, userId, context and the various sub-contexts.
JsonFileAgentStateStore、InMemoryAgentStateStore 提供开箱即用的存储。JsonFileAgentStateStore and InMemoryAgentStateStore provide ready-made storage.
RuntimeContext.agentState 把状态绑定到单次调用。RuntimeContext.agentState binds state to a single call.

构造状态并绑定到调用Build state and bind it to a call

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.state.AgentState;

public class StateDemo {
    public static void main(String[] args) {
        AgentState state = AgentState.builder()
                .sessionId("demo-session")
                .userId("alice")
                .summary("The user is comparing deployment options.")
                .build();

        RuntimeContext context = RuntimeContext.builder()
                .sessionId("demo-session")
                .agentState(state)
                .build();

        System.out.println(context.getAgentState().getSessionId());
    }
}

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`Builder`	类class	构建器，用于构建并配置目标实例。 A class in io.agentscope.core.state that persists and restores session and memory data across calls.

方法摘要Method Summary

方法Method	说明Description
`public String getSessionId()`	返回会话 ID。 Returns the session id.
`public String getUserId()`	获取用户标识。 Nullable; `null` = anonymous / single-tenant context.
`public String getSummary()`	获取摘要。 Returns the summary.
`public void setSummary(String summary)`	设置上下文摘要。 Sets the summary.
`public List<Msg> getContext()`	返回消息上下文列表。 Defensive copy of the conversation buffer.
`public List<Msg> contextMutable()`	返回上下文可变。 Live, mutable handle for components that append/replace messages in place.
`public String getReplyId()`	获取回复标识。 Returns the reply id.
`public void setReplyId(String replyId)`	设置回复标识。 Sets the reply id.
`public int getCurIter()`	返回当前迭代轮数。 Returns the cur iter.
`public void setCurIter(int curIter)`	设置当前迭代次数。 Sets the cur iter.
`public boolean isShutdownInterrupted()`	判断是否 `isShutdownInterrupted`。 Returns whether the shutdown interrupted.
`public void setShutdownInterrupted(boolean shutdownInterrupted)`	设置 `setShutdownInterrupted`。 Sets the shutdown interrupted.
`public` `PermissionContextState getPermissionContext()`	返回权限上下文。 Returns the permission context.
`public void setPermissionContext(PermissionContextState permissionContext)`	设置权限上下文。 Replaces the permission context for this session.
`public` `ToolContextState getToolContext()`	获取工具上下文。 Returns the tool context.
`public` `TaskContextState getTasksContext()`	获取任务上下文。 Returns the tasks context.
`public` `PlanModeContextState getPlanModeContext()`	获取计划模式上下文。 Returns the plan mode context.
`public static Builder builder()` static	创建会话状态构建器。 Returns the builder.
`public String toJson()`	返回到 JSON。 Serialize this state to a pretty-printed JSON string.
`public static` `AgentState fromJsonString(String json)` static	设置该参数。 Deserialize an `AgentState` from a JSON string produced by `#toJson()`.
`public boolean equals(Object o)`	设置该参数。 Performs the equals operation.
`public int hashCode()`	返回 `hashCode` 结果。 Returns the hash code.
`public String toString()`	返回 `toString` 结果。 Returns the to string.

方法详情Method Detail

getSessionId

public String getSessionId()

获取会话标识。

Returns the session id.

返回Returns String

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

源码Source io/agentscope/core/state/AgentState.java:149–152

getUserId

public String getUserId()

获取用户标识。

Nullable; null = anonymous / single-tenant context.

返回Returns String

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

源码Source io/agentscope/core/state/AgentState.java:155–158

getSummary

public String getSummary()

获取摘要。

Returns the summary.

返回Returns String

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

源码Source io/agentscope/core/state/AgentState.java:160–163

setSummary

public void setSummary(String summary)

设置摘要。

Sets the summary.

参数Parameters

名称Name	类型Type	说明Description
`summary`	String	摘要（类型 `String`）。The summary.

源码Source io/agentscope/core/state/AgentState.java:165–167

getContext

public List<Msg> getContext()

获取上下文。

Defensive copy of the conversation buffer.

返回Returns List<Msg>

返回列出。Returns list.

源码Source io/agentscope/core/state/AgentState.java:170–173

contextMutable

public List<Msg> contextMutable()

返回上下文可变。

Live, mutable handle for components that append/replace messages in place.

返回Returns List<Msg>

返回列出。Returns list.

源码Source io/agentscope/core/state/AgentState.java:176–178

getReplyId

public String getReplyId()

获取回复标识。

Returns the reply id.

返回Returns String

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

源码Source io/agentscope/core/state/AgentState.java:180–183

setReplyId

public void setReplyId(String replyId)

设置回复标识。

Sets the reply id.

参数Parameters

名称Name	类型Type	说明Description
`replyId`	String	回复标识（类型 `String`）。The reply id.

源码Source io/agentscope/core/state/AgentState.java:185–187

getCurIter

public int getCurIter()

获取当前迭代次数。

Returns the cur iter.

返回Returns int

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

源码Source io/agentscope/core/state/AgentState.java:189–192

setCurIter

public void setCurIter(int curIter)

设置当前迭代次数。

Sets the cur iter.

参数Parameters

名称Name	类型Type	说明Description
`curIter`	int	当前迭代次数（类型 `int`）。The cur iter.

源码Source io/agentscope/core/state/AgentState.java:194–196

isShutdownInterrupted

public boolean isShutdownInterrupted()

判断是否 isShutdownInterrupted。

Returns whether the shutdown interrupted.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/core/state/AgentState.java:198–201

setShutdownInterrupted

public void setShutdownInterrupted(boolean shutdownInterrupted)

设置 setShutdownInterrupted。

Sets the shutdown interrupted.

参数Parameters

名称Name	类型Type	说明Description
`shutdownInterrupted`	boolean	shutdown Interrupted（类型 `boolean`）。The shutdown interrupted.

源码Source io/agentscope/core/state/AgentState.java:203–205

getPermissionContext

public PermissionContextState getPermissionContext()

获取权限上下文。

Returns the permission context.

返回Returns PermissionContextState

返回PermissionContextState。Returns permission context state.

源码Source io/agentscope/core/state/AgentState.java:207–210

setPermissionContext

public void setPermissionContext(PermissionContextState permissionContext)

设置权限上下文。

Replaces the permission context for this session.

参数Parameters

名称Name	类型Type	说明Description
`permissionContext`	PermissionContextState	权限上下文（类型 `PermissionContextState`）。the new (non-null) permission context

源码Source io/agentscope/core/state/AgentState.java:219–223

getToolContext

public ToolContextState getToolContext()

获取工具上下文。

Returns the tool context.

返回Returns ToolContextState

返回ToolContextState。Returns tool context state.

源码Source io/agentscope/core/state/AgentState.java:225–228

getTasksContext

public TaskContextState getTasksContext()

获取任务上下文。

Returns the tasks context.

返回Returns TaskContextState

返回TaskContextState。Returns task context state.

源码Source io/agentscope/core/state/AgentState.java:230–233

getPlanModeContext

public PlanModeContextState getPlanModeContext()

获取计划模式上下文。

Returns the plan mode context.

返回Returns PlanModeContextState

返回PlanModeContextState。Returns plan mode context state.

源码Source io/agentscope/core/state/AgentState.java:235–238

builder

public static Builder builder()

static

返回构建器实例。

Returns the builder.

返回Returns Builder

返回当前实例，以支持链式调用。Returns the current instance for chaining.

源码Source io/agentscope/core/state/AgentState.java:240–242

toJson

public String toJson()

返回到 JSON。

Serialize this state to a pretty-printed JSON string.

返回Returns String

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

源码Source io/agentscope/core/state/AgentState.java:250–252

fromJsonString

public static AgentState fromJsonString(String json)

static

设置该参数。

Deserialize an AgentState from a JSON string produced by #toJson().

参数Parameters

名称Name	类型Type	说明Description
`json`	String	JSON（类型 `String`）。The json.

返回Returns AgentState

返回AgentState。Returns agent state.

源码Source io/agentscope/core/state/AgentState.java:257–259

equals

public boolean equals(Object o)

设置该参数。

Performs the equals operation.

参数Parameters

名称Name	类型Type	说明Description
`o`	Object	o（类型 `Object`）。The o.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/core/state/AgentState.java:261–280

hashCode

public int hashCode()

返回 hashCode 结果。

Returns the hash code.

返回Returns int

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

源码Source io/agentscope/core/state/AgentState.java:282–296

toString

public String toString()

返回 toString 结果。

Returns the to string.

返回Returns String

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

源码Source io/agentscope/core/state/AgentState.java:298–311

嵌套类详情Nested Class Detail

Builder

public static final class Builder

构建器，用于构建并配置目标实例。位于 io.agentscope.core.state 包。核心成员包括 sessionId、userId、summary、context、addMessage、replyId。

A class in io.agentscope.core.state that persists and restores session and memory data across calls. Declared in io.agentscope.core.state.