类class io.agentscope.core 2.x

ReActAgent

@SuppressWarnings("deprecation") public class ReActAgent extends AgentBase implements AutoCloseable

源码Source io/agentscope/core/ReActAgent.java:217–5658

ReActAgent 是 Java 版的核心智能体。构建器组装模型、工具、权限、状态存储与中间件，call 返回 Mono，streamEvents 返回 AgentEvent 流。位于 io.agentscope.core 包，继承自 AgentBase，实现 AutoCloseable。核心成员包括 callSerializationKey、beforeAgentExecution、seedSystemMsg、stateForCall、consumeSystemMsgAfterPreCall、call。

ReAct (Reasoning and Acting) Agent implementation.

ReAct is an agent design pattern that combines reasoning (thinking and planning) with acting (tool execution) in an iterative loop. The agent alternates between these two phases until it either completes the task or reaches the maximum iteration limit.

Key Features:

Reactive Streaming: Uses Project Reactor for non-blocking execution
Hook System: Extensible hooks for monitoring and intercepting agent execution
HITL Support: Human-in-the-loop via stopAgent() in PostReasoningEvent/PostActingEvent
Structured Output: per-call generate_response tool provides type-safe output

Usage Example:

`import io.agentscope.extensions.model.dashscope.DashScopeChatModel;

// Create a model (requires dependency: agentscope-extensions-model-dashscope)
DashScopeChatModel model = DashScopeChatModel.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.modelName("qwen-plus")
.build();

// Create a toolkit with tools
Toolkit toolkit = new Toolkit();
toolkit.registerObject(new MyToolClass());

// Build the agent
ReActAgent agent = ReActAgent.builder()
.name("Assistant")
.sysPrompt("You are a helpful assistant.")
.model(model)
.toolkit(toolkit)
.maxIters(10)
.build();

// Use the agent
Msg response = agent.call(Msg.builder()
.name("user")
.role(MsgRole.USER)
.content(TextBlock.builder().text("What's the weather?").build())
.build()).block();
`

Concurrency: Calls sharing a (userId, sessionId) slot are serialized; distinct slots can execute concurrently. Runtime contexts are passed through each call's execution scope, middleware parameters, and tool parameters, never through a shared current context accessor. Custom tools, hooks, and middlewares must also be safe for concurrent use.

核心精讲Deep dive

ReActAgent：响应式 ReAct 智能体ReActAgent: the reactive ReAct agent

ReActAgent 是 Java 版的核心智能体。Builder 组装模型、工具、权限、状态存储与中间件，call 返回 Mono，streamEvents 返回 AgentEvent 流。

ReActAgent is the core agent in Java. Its builder assembles the model, tools, permissions, state store and middleware; call returns Mono and streamEvents returns a stream of AgentEvent.

Builder 覆盖 name、sysPrompt、model、toolkit、maxIters、middleware、stateStore 与 knowledge。The builder covers name, sysPrompt, model, toolkit, maxIters, middleware, stateStore and knowledge.
call 有文本、Msg 列表与结构化输出等重载，最终都返回 Mono<Msg>。call is overloaded for text, message lists and structured output, all returning Mono<Msg>.
interrupt 提供协作式取消，事件流会收到中断事件。interrupt provides cooperative cancellation and the event stream receives interruption events.

构建并调用 ReActAgentBuild and call a ReActAgent

import io.agentscope.core.ReActAgent;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.Msg;
import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.extensions.model.openai.OpenAIChatModel;

public class QuickStart {
    static final class WeatherTools {
        @Tool(name = "get_weather", description = "Return the current weather for a city.")
        public String getWeather(
                @ToolParam(name = "city", description = "City name, e.g. Hangzhou") String city) {
            return city + ": sunny, 24C";
        }
    }

    public static void main(String[] args) {
        OpenAIChatModel model = OpenAIChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4.1-mini")
                .build();

        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new WeatherTools());

        ReActAgent agent = ReActAgent.builder()
                .name("assistant")
                .sysPrompt("You are a concise assistant. Use tools when needed.")
                .model(model)
                .toolkit(toolkit)
                .maxIters(8)
                .build();

        Msg reply = agent.call(
                "What's the weather in Hangzhou?",
                RuntimeContext.builder().sessionId("demo").userId("alice").build()
        ).block();
        System.out.println(reply.getTextContent());
        agent.close();
    }
}

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`Builder`	类class	ReActAgent 构建器 A class in io.agentscope.core that drives agent reasoning, tool calls and conversation execution.

字段摘要Field Summary

字段Field	类型Type	说明Description
`STRUCTURED_OUTPUT_TOOL_NAME` staticfinal	String	结构化输出工具名称字段。 Tool name used for the per-call structured-output `generate_response` tool.
`CONFIRM_SINK_KEY` staticfinaldeprecated	String	确认 SINK 键字段。 @deprecated Permission HITL no longer uses a Reactor Sink. Confirm results are now delivered via a second {@code agent.call(msgs)} carrying a {@link ConfirmResult} payload \u2014 see {@code applyConfirmResults}. This constant is retained as a compile-time marker and will be removed in a future release.

方法摘要Method Summary

方法Method	说明Description
`protected Object callSerializationKey(RuntimeContext rc)`	调用序列化键。 Calls the serialization key.
`protected Object beforeAgentExecution(List<Msg> msgs, RuntimeContext rc, RunControl control)`	在智能体执行前调用。 Performs the before agent execution operation.
`protected Mono<Msg> seedSystemMsg(Object callExectution)`	设置预置系统消息。 Performs the seed system msg operation.
`protected` `AgentState stateForCall(Object callScope)`	设置调用时使用的状态。 Performs the state for call operation.
`protected void consumeSystemMsgAfterPreCall(Msg systemMsg, Object callScope)`	执行消费系统消息之后前置调用相关操作。 Performs the consume system msg after pre call operation.
`public Mono<Msg> call(List<Msg> msgs, RuntimeContext context)`	执行一次智能体调用，返回 Mono。 Calls the agent with a per-call `RuntimeContext` (metadata for hooks and tools, not persisted).
`public Mono<Msg> call(List<Msg> msgs, Class<?> structuredOutputClass, RuntimeContext context)`	执行一次智能体调用，返回 Mono。 Performs the call operation.
`public Mono<Msg> call(List<Msg> msgs, JsonNode outputSchema, RuntimeContext context)`	执行一次智能体调用，返回 Mono。 Performs the call operation.
`public Mono<Msg> call(String text, RuntimeContext context)`	执行一次智能体调用，返回 Mono。 Calls the agent with a plain text input and per-call `RuntimeContext`.
`public Mono<Msg> call(String text, Class<?> structuredOutputClass, RuntimeContext context)`	执行一次智能体调用，返回 Mono。 Calls the agent with a plain text input, structured output class, and per-call `RuntimeContext`.
`public void interrupt()` deprecated	以协作方式中断当前运行。 Returns the interrupt.
`public void interrupt(Msg msg)` deprecated	以协作方式中断当前运行。 Performs the interrupt operation.
`public void interrupt(InterruptSource source)` deprecated	以协作方式中断当前运行。 Performs the interrupt operation.
`public void interrupt(RuntimeContext ctx)`	以协作方式中断当前运行。 Interrupts the in-flight call identified by the given `RuntimeContext`.
`public void interrupt(RuntimeContext ctx, Msg msg)`	以协作方式中断当前运行。 Interrupts the in-flight call identified by the given `RuntimeContext` with an associated user message.
`public void interrupt(String userId, String sessionId)`	以协作方式中断当前运行。 Interrupts the in-flight call for a specific `(userId, sessionId)` session.
`public void interrupt(String userId, String sessionId,` `Msg msg)`	以协作方式中断当前运行。 Interrupts the in-flight call for a specific `(userId, sessionId)` session with an associated user message.
`public Flux<Event> stream(List<Msg> msgs, StreamOptions options, RuntimeContext context)` deprecated	执行流相关操作。 Performs the stream operation.
`public Flux<Event> stream(List<Msg> msgs, StreamOptions options, Class<?> structuredModel, RuntimeContext context)` deprecated	执行流相关操作。 Performs the stream operation.
`public Flux<Event> stream(List<Msg> msgs, StreamOptions options, JsonNode schema, RuntimeContext context)` deprecated	执行流相关操作。 Performs the stream operation.
`protected Mono<Msg> callInternal(List<Msg> msgs, RuntimeContext context, Function<List<Msg>, Mono<Msg>> doCallFn)`	调用内部。 Overrides the base-class hook so that every `call()` variant — including structured output and context-bearing overloads — runs through the same `#buildAgentStream` core as `streamEvents()`.
`public` `AgentRun<AgentEvent> prepareRun(List<Msg> msgs, RuntimeContext context)`	执行 `prepareRun` 方法。 Prepare a single-use event execution handle without starting the call.
`public` `AgentRun<Msg> prepareCall(List<Msg> msgs, RuntimeContext context)`	执行 `prepareCall` 方法。 Prepare a single-use reply execution handle without starting the call.
`public Flux<AgentEvent> streamEvents(List<Msg> msgs)`	执行调用并流式返回 AgentEvent。 Stream fine-grained `AgentEvent`s from the full agent lifecycle.
`public Flux<AgentEvent> streamEvents(Msg msg)`	执行调用并流式返回 AgentEvent。 Stream fine-grained `AgentEvent`s for a single input message.
`public Flux<AgentEvent> streamEvents(List<Msg> msgs, RuntimeContext context)`	执行调用并流式返回 AgentEvent。 Stream fine-grained `AgentEvent`s with a caller-supplied `RuntimeContext`.
`public Flux<AgentEvent> streamEvents(Msg msg, RuntimeContext context)`	执行调用并流式返回 AgentEvent。 Stream fine-grained `AgentEvent`s for a single input message with a caller-supplied `RuntimeContext`.
`public Flux<AgentEvent> streamEvents(String text)`	执行调用并流式返回 AgentEvent。 Stream fine-grained `AgentEvent`s for a plain text input.
`public Flux<AgentEvent> streamEvents(String text, RuntimeContext context)`	执行调用并流式返回 AgentEvent。 Stream fine-grained `AgentEvent`s for a plain text input with a caller-supplied `RuntimeContext`.
`protected Mono<Msg> doCall(List<Msg> msgs)`	执行调用操作。 Performs the do call operation.
`protected Mono<Msg> doCall(List<Msg> msgs, Class<?> structuredOutputClass)`	执行调用操作。 Performs the do call operation.
`protected Mono<Msg> doCall(List<Msg> msgs, JsonNode outputSchema)`	执行调用操作。 Performs the do call operation.
`protected` `GenerateOptions buildGenerateOptions()`	构建 `buildGenerateOptions`。 Builds the generate options.
`protected Mono<Msg> handleInterrupt(InterruptContext context, Msg... originalArgs)`	处理中断。 Performs the handle interrupt operation.
`protected Mono<Void> doObserve(Msg msg)`	执行观察操作。 Performs the do observe operation.
`public` `Toolkit getToolkit()`	获取工具包。 Returns this agent's toolkit; request-specific views do not mutate its registry.
`public String getSysPrompt()`	获取 `getSysPrompt`。 Returns the sys prompt.
`public` `Model getModel()`	获取模型。 Returns the model.
`public int getMaxIters()`	获取最大迭代次数。 Returns the max iters.
`public` `GenerateOptions getGenerateOptions()`	获取 `getGenerateOptions`。 Gets the configured generation options for this agent.
`public` `AgentState getAgentState()` deprecated	获取智能体状态。 Returns the agent state.
`public` `AgentState getAgentState(RuntimeContext ctx)`	获取智能体状态。 Returns the `AgentState` for the session identified by the given `RuntimeContext`.
`public` `AgentState getAgentState(String userId, String sessionId)`	获取智能体状态。 Returns the `AgentState` for the given `(userId, sessionId)` slot, loading it from the configured `AgentStateStore` on first access and caching it for subsequent calls within this JVM.
`public void clearStateCache()`	清空状态缓存。 Clears all locally cached per-session state and permission engines.
`public void clearStateCache(RuntimeContext ctx)`	清空状态缓存。 Clears the locally cached state and permission engine for the session identified by `ctx`.
`public void clearStateCache(String userId, String sessionId)`	清空状态缓存。 Clears the locally cached state and permission engine for one `(userId, sessionId)` slot.
`public void clearContext(RuntimeContext ctx)`	清空上下文。 Clears the model-visible conversation context for the session identified by `ctx`.
`public void clearContext(String userId, String sessionId)`	清空上下文。 Clears the model-visible conversation context for one `(userId, sessionId)` session.
`public void setPermissionMode(String userId, String sessionId,` `PermissionMode mode)`	设置权限模式。 Switches the `PermissionMode` for the given `(userId, sessionId)` session at runtime and rebuilds that session's cached `PermissionEngine` so the change takes effect on the next tool evaluation.
`public void replacePermissionContext(String userId, String sessionId,` `PermissionContextState permissionContext)`	执行 `replacePermissionContext` 方法。 Replaces the permission context for one `(userId, sessionId)` slot, rebuilds that slot's permission engine, and persists the updated state.
`public void setPermissionMode(RuntimeContext ctx, PermissionMode mode)`	设置权限模式。 Switches the `PermissionMode` for the session identified by the given `RuntimeContext`.
`public` `PermissionMode getPermissionMode(String userId, String sessionId)`	获取权限模式。 Returns the current `PermissionMode` for the given `(userId, sessionId)` session.
`public void saveAgentState(RuntimeContext ctx)`	保存智能体状态。 Persists the cached `AgentState` for the session identified by the given `RuntimeContext`.
`public void saveAgentState(String userId, String sessionId)`	保存智能体状态。 Persists the cached `AgentState` for the given `(userId, sessionId)` slot via the configured `AgentStateStore`.
`public long getStateConflictCount()`	获取 `getStateConflictCount`。 Returns how many optimistic-concurrency conflicts have been observed on this agent.
`public` `ConflictPolicy getConflictPolicy()`	获取 `getConflictPolicy`。 Returns the configured `ConflictPolicy` for agent_state saves.
`public` `AgentStateStore getStateStore()`	获取状态存储。 Returns the `AgentStateStore` configured for state persistence, or `null`.
`public String getDefaultSessionId()`	获取默认会话标识。 Returns the builder-time fallback `sessionId`, used when a call's `RuntimeContext` carries no `sessionId`.
`public` `ModelConfig getModelConfig()`	获取模型配置。 Returns the model-call configuration (retries, timeouts).
`public` `ReactConfig getReactConfig()`	获取ReAct 配置。 Returns the reasoning-loop configuration (maxIters, stopOnReject).
`public` `PermissionEngine getPermissionEngine()` deprecated	获取权限引擎。 Returns the permission engine.
`public` `PermissionContextState getPermissionContext()` deprecated	获取权限上下文。 Returns the permission context.
`public List<MiddlewareBase> getMiddlewares()`	获取 `getMiddlewares`。 Returns the immutable list of registered middlewares.
`public` `ExecutionConfig getModelExecutionConfig()`	获取模型执行配置。 Returns the per-model-call `ExecutionConfig`, or `null` if none was set.
`public` `ExecutionConfig getToolExecutionConfig()`	获取工具执行配置。 Returns the per-tool-call `ExecutionConfig`, or `null` if none was set.
`public` `ToolExecutionContext getToolExecutionContext()`	获取工具执行上下文。 Returns the `ToolExecutionContext` bound at build time, or `null` if none.
`public boolean isPendingToolRecoveryEnabled()`	判断是否 `isPendingToolRecoveryEnabled`。 Returns whether pending-tool-call recovery is enabled (HITL: resume tool calls left in a pending state across `call()` invocations).
`public String getSystemPrompt()`	获取系统提示词。 Returns the system prompt (alias for `#getSysPrompt()`).
`public static` `Builder builder()` static	返回构建器实例。 Returns the builder.
`public void close()`	释放智能体持有的资源。 Releases resources and connections.

字段详情Field Detail

STRUCTURED_OUTPUT_TOOL_NAME

public static final String STRUCTURED_OUTPUT_TOOL_NAME

staticfinal

结构化输出工具名称字段。声明为 public static final String STRUCTURED_OUTPUT_TOOL_NAME。

Tool name used for the per-call structured-output generate_response tool.

源码Source io/agentscope/core/ReActAgent.java:225

CONFIRM_SINK_KEY

@Deprecated public static final String CONFIRM_SINK_KEY

staticfinaldeprecated

确认 SINK 键字段。声明为 @Deprecated public static final String CONFIRM_SINK_KEY。

@deprecated Permission HITL no longer uses a Reactor Sink.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Permission HITL no longer uses a Reactor Sink. Confirm results are now delivered via a second `agent.call(msgs)` carrying a `ConfirmResult` payload — see `applyConfirmResults`. This constant is retained as a compile-time marker and will be removed in a future release.

源码Source io/agentscope/core/ReActAgent.java:233–234

方法详情Method Detail

callSerializationKey

protected Object callSerializationKey(RuntimeContext rc)

调用序列化键。

Calls the serialization key.

参数Parameters

名称Name	类型Type	说明Description
`rc`	RuntimeContext	rc（类型 `RuntimeContext`）。The rc.

返回Returns Object

返回对象。Returns object.

源码Source io/agentscope/core/ReActAgent.java:726–737

beforeAgentExecution

protected Object beforeAgentExecution(List<Msg> msgs, RuntimeContext rc, RunControl control)

在智能体执行前调用。

Performs the before agent execution operation.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`rc`	RuntimeContext	rc（类型 `RuntimeContext`）。The rc.
`control`	RunControl	control（类型 `RunControl`）。The control.

返回Returns Object

返回对象。Returns object.

源码Source io/agentscope/core/ReActAgent.java:739–768

seedSystemMsg

protected Mono<Msg> seedSystemMsg(Object callExectution)

设置预置系统消息。

Performs the seed system msg operation.

参数Parameters

名称Name	类型Type	说明Description
`callExectution`	Object	调用 Exectution（类型 `Object`）。The call exectution.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:770–782

stateForCall

protected AgentState stateForCall(Object callScope)

设置调用时使用的状态。

Performs the state for call operation.

参数Parameters

名称Name	类型Type	说明Description
`callScope`	Object	调用范围（类型 `Object`）。The call scope.

返回Returns AgentState

返回AgentState。Returns agent state.

源码Source io/agentscope/core/ReActAgent.java:784–787

consumeSystemMsgAfterPreCall

protected void consumeSystemMsgAfterPreCall(Msg systemMsg, Object callScope)

执行消费系统消息之后前置调用相关操作。

Performs the consume system msg after pre call operation.

参数Parameters

名称Name	类型Type	说明Description
`systemMsg`	Msg	系统消息（类型 `Msg`）。The system msg.
`callScope`	Object	调用范围（类型 `Object`）。The call scope.

源码Source io/agentscope/core/ReActAgent.java:822–826

call

public Mono<Msg> call(List<Msg> msgs, RuntimeContext context)

向智能体发送输入并返回最终回复。

Calls the agent with a per-call RuntimeContext (metadata for hooks and tools, not persisted).

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	本次调用输入的消息列表。The msgs.
`context`	RuntimeContext	本次调用的会话与工具上下文。The context.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:849–851

call

public Mono<Msg> call(List<Msg> msgs, Class<?> structuredOutputClass, RuntimeContext context)

向智能体发送输入并返回最终回复。

Performs the call operation.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	本次调用输入的消息列表。The msgs.
`structuredOutputClass`	Class<?>	结构化输出的目标类型。The structured output class.
`context`	RuntimeContext	本次调用的会话与工具上下文。The context.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:853–855

call

public Mono<Msg> call(List<Msg> msgs, JsonNode outputSchema, RuntimeContext context)

向智能体发送输入并返回最终回复。

Performs the call operation.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	本次调用输入的消息列表。The msgs.
`outputSchema`	JsonNode	结构化输出的 JSON 模式。The output schema.
`context`	RuntimeContext	本次调用的会话与工具上下文。The context.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:857–859

call

public Mono<Msg> call(String text, RuntimeContext context)

向智能体发送输入并返回最终回复。

Calls the agent with a plain text input and per-call RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`text`	String	用户输入文本。input text (wrapped into a `UserMessage`)
`context`	RuntimeContext	本次调用的会话与工具上下文。per-call runtime context

返回Returns Mono<Msg>

返回Mono。response message

源码Source io/agentscope/core/ReActAgent.java:868–870

call

public Mono<Msg> call(String text, Class<?> structuredOutputClass, RuntimeContext context)

向智能体发送输入并返回最终回复。

Calls the agent with a plain text input, structured output class, and per-call RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`text`	String	用户输入文本。input text (wrapped into a `UserMessage`)
`structuredOutputClass`	Class<?>	结构化输出的目标类型。class defining the structure
`context`	RuntimeContext	本次调用的会话与工具上下文。per-call runtime context

返回Returns Mono<Msg>

返回Mono。response message with structured data in metadata

源码Source io/agentscope/core/ReActAgent.java:881–883

interrupt

public void interrupt()

deprecated

请求中断当前执行。

Returns the interrupt.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Use `#interrupt(String, String)` with explicit userId/sessionId.

源码Source io/agentscope/core/ReActAgent.java:903–907

interrupt

public void interrupt(Msg msg)

deprecated

请求中断当前执行。

Performs the interrupt operation.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Use `#interrupt(String, String, Msg)` with explicit userId/sessionId.

参数Parameters

名称Name	类型Type	说明Description
`msg`	Msg	消息（类型 `Msg`）。The msg.

源码Source io/agentscope/core/ReActAgent.java:910–914

interrupt

public void interrupt(InterruptSource source)

deprecated

请求中断当前执行。

Performs the interrupt operation.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Use `#interrupt(String, String)` with explicit userId/sessionId.

参数Parameters

名称Name	类型Type	说明Description
`source`	InterruptSource	来源（类型 `InterruptSource`）。The source.

源码Source io/agentscope/core/ReActAgent.java:917–921

interrupt

public void interrupt(RuntimeContext ctx)

请求中断当前执行。

Interrupts the in-flight call identified by the given RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`ctx`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。the runtime context identifying the session to interrupt

源码Source io/agentscope/core/ReActAgent.java:929–931

interrupt

public void interrupt(RuntimeContext ctx, Msg msg)

请求中断当前执行。

Interrupts the in-flight call identified by the given RuntimeContext with an associated user message.

参数Parameters

名称Name	类型Type	说明Description
`ctx`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。the runtime context identifying the session to interrupt
`msg`	Msg	消息（类型 `Msg`）。optional user message to attach to the interrupt signal

源码Source io/agentscope/core/ReActAgent.java:940–947

interrupt

public void interrupt(String userId, String sessionId)

请求中断当前执行。

Interrupts the in-flight call for a specific (userId, sessionId) session.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。the user id (`null` = anonymous / single-tenant)
`sessionId`	String	会话标识。the session id

源码Source io/agentscope/core/ReActAgent.java:955–957

interrupt

public void interrupt(String userId, String sessionId, Msg msg)

请求中断当前执行。

Interrupts the in-flight call for a specific (userId, sessionId) session with an associated user message.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`msg`	Msg	消息（类型 `Msg`）。The msg.

源码Source io/agentscope/core/ReActAgent.java:963–965

stream

public Flux<Event> stream(List<Msg> msgs, StreamOptions options, RuntimeContext context)

deprecated

执行流相关操作。

Performs the stream operation.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。since 2.0.0, for removal. Use `#streamEvents(List)` (and overloads that accept `RuntimeContext` via `call()`-driven lifecycle) for the fine-grained `AgentEvent` stream.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`options`	StreamOptions	选项（类型 `StreamOptions`）。The options.
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。The context.

返回Returns Flux<Event>

返回Flux。Returns flux.

源码Source io/agentscope/core/ReActAgent.java:972–975

stream

public Flux<Event> stream(List<Msg> msgs, StreamOptions options, Class<?> structuredModel, RuntimeContext context)

deprecated

执行流相关操作。

Performs the stream operation.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。since 2.0.0, for removal. Use `#streamEvents(List)` for the fine-grained `AgentEvent` stream.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`options`	StreamOptions	选项（类型 `StreamOptions`）。The options.
`structuredModel`	Class<?>	结构化模型（类型 `Class`）。The structured model.
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。The context.

返回Returns Flux<Event>

返回Flux。Returns flux.

源码Source io/agentscope/core/ReActAgent.java:981–988

stream

public Flux<Event> stream(List<Msg> msgs, StreamOptions options, JsonNode schema, RuntimeContext context)

deprecated

执行流相关操作。

Performs the stream operation.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。since 2.0.0, for removal. Use `#streamEvents(List)` for the fine-grained `AgentEvent` stream.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`options`	StreamOptions	选项（类型 `StreamOptions`）。The options.
`schema`	JsonNode	模式定义（类型 `JsonNode`）。The schema.
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。The context.

返回Returns Flux<Event>

返回Flux。Returns flux.

源码Source io/agentscope/core/ReActAgent.java:994–998

callInternal

protected Mono<Msg> callInternal(List<Msg> msgs, RuntimeContext context, Function<List<Msg>, Mono<Msg>> doCallFn)

调用内部。

Overrides the base-class hook so that every call() variant — including structured output and context-bearing overloads — runs through the same #buildAgentStream core as streamEvents().

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。The context.
`doCallFn`	Function<List<Msg>, Mono<Msg>>	执行调用 Fn（类型 `Function , Mono >`）。The do call fn.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:1011–1020

prepareRun

public AgentRun<AgentEvent> prepareRun(List<Msg> msgs, RuntimeContext context)

执行 prepareRun 方法。

Prepare a single-use event execution handle without starting the call.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。The context.

返回Returns AgentRun<AgentEvent>

返回AgentRun。Returns agent run.

源码Source io/agentscope/core/ReActAgent.java:1101–1103

prepareCall

public AgentRun<Msg> prepareCall(List<Msg> msgs, RuntimeContext context)

执行 prepareCall 方法。

Prepare a single-use reply execution handle without starting the call.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。The context.

返回Returns AgentRun<Msg>

返回AgentRun。Returns agent run.

源码Source io/agentscope/core/ReActAgent.java:1106–1108

streamEvents

public Flux<AgentEvent> streamEvents(List<Msg> msgs)

执行事件。

Stream fine-grained AgentEvents from the full agent lifecycle.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。input messages

返回Returns Flux<AgentEvent>

返回Flux。event stream covering the full agent invocation lifecycle

源码Source io/agentscope/core/ReActAgent.java:1123–1125

streamEvents

public Flux<AgentEvent> streamEvents(Msg msg)

执行事件。

Stream fine-grained AgentEvents for a single input message.

参数Parameters

名称Name	类型Type	说明Description
`msg`	Msg	消息（类型 `Msg`）。input message

返回Returns Flux<AgentEvent>

返回Flux。event stream covering the full agent invocation lifecycle

源码Source io/agentscope/core/ReActAgent.java:1133–1135

streamEvents

public Flux<AgentEvent> streamEvents(List<Msg> msgs, RuntimeContext context)

执行事件。

Stream fine-grained AgentEvents with a caller-supplied RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。input messages
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。runtime context to propagate into the call

返回Returns Flux<AgentEvent>

返回Flux。event stream covering the full agent invocation lifecycle

源码Source io/agentscope/core/ReActAgent.java:1148–1150

streamEvents

public Flux<AgentEvent> streamEvents(Msg msg, RuntimeContext context)

执行事件。

Stream fine-grained AgentEvents for a single input message with a caller-supplied RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`msg`	Msg	消息（类型 `Msg`）。input message
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。runtime context to propagate into the call

返回Returns Flux<AgentEvent>

返回Flux。event stream covering the full agent invocation lifecycle

源码Source io/agentscope/core/ReActAgent.java:1160–1162

streamEvents

public Flux<AgentEvent> streamEvents(String text)

执行事件。

Stream fine-grained AgentEvents for a plain text input.

参数Parameters

名称Name	类型Type	说明Description
`text`	String	文本（类型 `String`）。input text (wrapped into a `UserMessage`)

返回Returns Flux<AgentEvent>

返回Flux。event stream covering the full agent invocation lifecycle

源码Source io/agentscope/core/ReActAgent.java:1170–1172

streamEvents

public Flux<AgentEvent> streamEvents(String text, RuntimeContext context)

执行事件。

Stream fine-grained AgentEvents for a plain text input with a caller-supplied RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`text`	String	文本（类型 `String`）。input text (wrapped into a `UserMessage`)
`context`	RuntimeContext	上下文（类型 `RuntimeContext`）。runtime context to propagate into the call

返回Returns Flux<AgentEvent>

返回Flux。event stream covering the full agent invocation lifecycle

源码Source io/agentscope/core/ReActAgent.java:1182–1184

doCall

protected Mono<Msg> doCall(List<Msg> msgs)

执行调用操作。

Performs the do call operation.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:1204–1235

doCall

protected Mono<Msg> doCall(List<Msg> msgs, Class<?> structuredOutputClass)

执行调用操作。

Performs the do call operation.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`structuredOutputClass`	Class<?>	结构化输出类（类型 `Class`）。The structured output class.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:1239–1242

doCall

protected Mono<Msg> doCall(List<Msg> msgs, JsonNode outputSchema)

执行调用操作。

Performs the do call operation.

参数Parameters

名称Name	类型Type	说明Description
`msgs`	List<Msg>	消息列表（类型 `List`）。The msgs.
`outputSchema`	JsonNode	输出模式（类型 `JsonNode`）。The output schema.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:1244–1247

buildGenerateOptions

protected GenerateOptions buildGenerateOptions()

构建 buildGenerateOptions。

Builds the generate options.

返回Returns GenerateOptions

返回GenerateOptions。Returns generate options.

源码Source io/agentscope/core/ReActAgent.java:4247–4271

handleInterrupt

protected Mono<Msg> handleInterrupt(InterruptContext context, Msg... originalArgs)

处理中断。

Performs the handle interrupt operation.

参数Parameters

名称Name	类型Type	说明Description
`context`	InterruptContext	上下文（类型 `InterruptContext`）。The context.
`originalArgs` varargs	Msg...	original 参数（类型 `Msg...`）。The original args.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:4338–4374

doObserve

protected Mono<Void> doObserve(Msg msg)

执行观察操作。

Performs the do observe operation.

参数Parameters

名称Name	类型Type	说明Description
`msg`	Msg	消息（类型 `Msg`）。The msg.

返回Returns Mono<Void>

返回Mono。Returns mono.

源码Source io/agentscope/core/ReActAgent.java:4376–4382

getToolkit

public Toolkit getToolkit()

获取工具包。

Returns this agent's toolkit; request-specific views do not mutate its registry.

返回Returns Toolkit

返回工具包。Returns toolkit.

源码Source io/agentscope/core/ReActAgent.java:4387–4389

getSysPrompt

public String getSysPrompt()

获取 getSysPrompt。

Returns the sys prompt.

返回Returns String

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

源码Source io/agentscope/core/ReActAgent.java:4391–4393

getModel

public Model getModel()

获取模型。

Returns the model.

返回Returns Model

返回模型。Returns model.

源码Source io/agentscope/core/ReActAgent.java:4395–4397

getMaxIters

public int getMaxIters()

获取最大迭代次数。

Returns the max iters.

返回Returns int

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

源码Source io/agentscope/core/ReActAgent.java:4399–4401

getGenerateOptions

public GenerateOptions getGenerateOptions()

获取 getGenerateOptions。

Gets the configured generation options for this agent.

返回Returns GenerateOptions

返回GenerateOptions。The generation options, or null if not configured

源码Source io/agentscope/core/ReActAgent.java:4408–4410

getAgentState

public AgentState getAgentState()

deprecated

获取智能体状态。

Returns the agent state.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Use `#getAgentState(RuntimeContext)` or `#getAgentState(String, String)` with explicit session identity. This method delegates to the default session slot.

返回Returns AgentState

返回AgentState。Returns agent state.

源码Source io/agentscope/core/ReActAgent.java:4417–4421

getAgentState

public AgentState getAgentState(RuntimeContext ctx)

获取智能体状态。

Returns the AgentState for the session identified by the given RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`ctx`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。the runtime context (uses `getUserId()` and `getSessionId()`)

返回Returns AgentState

返回AgentState。the agent state for the identified session

源码Source io/agentscope/core/ReActAgent.java:4429–4436

getAgentState

public AgentState getAgentState(String userId, String sessionId)

获取智能体状态。

Returns the AgentState for the given (userId, sessionId) slot, loading it from the configured AgentStateStore on first access and caching it for subsequent calls within this JVM.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.

返回Returns AgentState

返回AgentState。Returns agent state.

源码Source io/agentscope/core/ReActAgent.java:4447–4463

clearStateCache

public void clearStateCache()

清空状态缓存。

Clears all locally cached per-session state and permission engines.

源码Source io/agentscope/core/ReActAgent.java:4476–4480

clearStateCache

public void clearStateCache(RuntimeContext ctx)

清空状态缓存。

Clears the locally cached state and permission engine for the session identified by ctx.

参数Parameters

名称Name	类型Type	说明Description
`ctx`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。runtime context identifying the session; a missing session id uses the default session id

源码Source io/agentscope/core/ReActAgent.java:4489–4493

clearStateCache

public void clearStateCache(String userId, String sessionId)

清空状态缓存。

Clears the locally cached state and permission engine for one (userId, sessionId) slot.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。user identity for the slot (`null` = anonymous / single-tenant)
`sessionId`	String	会话标识（类型 `String`）。session identity; `null` or blank uses the default session id

源码Source io/agentscope/core/ReActAgent.java:4505–4511

clearContext

public void clearContext(RuntimeContext ctx)

清空上下文。

Clears the model-visible conversation context for the session identified by ctx.

参数Parameters

名称Name	类型Type	说明Description
`ctx`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。runtime context identifying the session; a missing session id uses the default session id

源码Source io/agentscope/core/ReActAgent.java:4531–4535

clearContext

public void clearContext(String userId, String sessionId)

清空上下文。

Clears the model-visible conversation context for one (userId, sessionId) session.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。user identity for the slot (`null` = anonymous / single-tenant)
`sessionId`	String	会话标识（类型 `String`）。session identity; `null` or blank uses the default session id

源码Source io/agentscope/core/ReActAgent.java:4555–4587

setPermissionMode

public void setPermissionMode(String userId, String sessionId, PermissionMode mode)

设置权限模式。

Switches the PermissionMode for the given (userId, sessionId) session at runtime and rebuilds that session's cached PermissionEngine so the change takes effect on the next tool evaluation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。user identity for the slot (may be `null`)
`sessionId`	String	会话标识（类型 `String`）。session identity (falls back to the default session id when `null`)
`mode`	PermissionMode	权限模式到开关到。the permission mode to switch to

源码Source io/agentscope/core/ReActAgent.java:4608–4613

replacePermissionContext

public void replacePermissionContext(String userId, String sessionId, PermissionContextState permissionContext)

执行 replacePermissionContext 方法。

Replaces the permission context for one (userId, sessionId) slot, rebuilds that slot's permission engine, and persists the updated state.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。user identity for the slot (may be `null`)
`sessionId`	String	会话标识（类型 `String`）。session identity (falls back to the default session id when `null`)
`permissionContext`	PermissionContextState	权限上下文（类型 `PermissionContextState`）。complete replacement context

源码Source io/agentscope/core/ReActAgent.java:4626–4632

setPermissionMode

public void setPermissionMode(RuntimeContext ctx, PermissionMode mode)

设置权限模式。

Switches the PermissionMode for the session identified by the given RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`ctx`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。the runtime context identifying the session
`mode`	PermissionMode	权限模式到开关到。the permission mode to switch to

源码Source io/agentscope/core/ReActAgent.java:4652–4656

getPermissionMode

public PermissionMode getPermissionMode(String userId, String sessionId)

获取权限模式。

Returns the current PermissionMode for the given (userId, sessionId) session.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。user identity for the slot (may be `null`)
`sessionId`	String	会话标识（类型 `String`）。session identity (falls back to the default session id when `null`)

返回Returns PermissionMode

会话's 当前权限模式。the session's current permission mode

源码Source io/agentscope/core/ReActAgent.java:4665–4668

saveAgentState

public void saveAgentState(RuntimeContext ctx)

保存智能体状态。

Persists the cached AgentState for the session identified by the given RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`ctx`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。the runtime context identifying the session to save

源码Source io/agentscope/core/ReActAgent.java:4677–4684

saveAgentState

public void saveAgentState(String userId, String sessionId)

保存智能体状态。

Persists the cached AgentState for the given (userId, sessionId) slot via the configured AgentStateStore.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.

源码Source io/agentscope/core/ReActAgent.java:4691–4701

getStateConflictCount

public long getStateConflictCount()

获取 getStateConflictCount。

Returns how many optimistic-concurrency conflicts have been observed on this agent.

返回Returns long

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

源码Source io/agentscope/core/ReActAgent.java:4704–4706

getConflictPolicy

public ConflictPolicy getConflictPolicy()

获取 getConflictPolicy。

Returns the configured ConflictPolicy for agent_state saves.

返回Returns ConflictPolicy

返回ConflictPolicy。Returns conflict policy.

源码Source io/agentscope/core/ReActAgent.java:4709–4711

getStateStore

public AgentStateStore getStateStore()

获取状态存储。

Returns the AgentStateStore configured for state persistence, or null.

返回Returns AgentStateStore

返回AgentStateStore。Returns agent state store.

源码Source io/agentscope/core/ReActAgent.java:4714–4716

getDefaultSessionId

public String getDefaultSessionId()

获取默认会话标识。

Returns the builder-time fallback sessionId, used when a call's RuntimeContext carries no sessionId.

返回Returns String

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

源码Source io/agentscope/core/ReActAgent.java:4722–4724

getModelConfig

public ModelConfig getModelConfig()

获取模型配置。

Returns the model-call configuration (retries, timeouts).

返回Returns ModelConfig

返回ModelConfig。Returns model config.

源码Source io/agentscope/core/ReActAgent.java:4727–4729

getReactConfig

public ReactConfig getReactConfig()

获取ReAct 配置。

Returns the reasoning-loop configuration (maxIters, stopOnReject).

返回Returns ReactConfig

返回ReactConfig。Returns react config.

源码Source io/agentscope/core/ReActAgent.java:4732–4734

getPermissionEngine

public PermissionEngine getPermissionEngine()

deprecated

获取权限引擎。

Returns the permission engine.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Use `getAgentState(userId, sessionId).getPermissionContext()` instead.

返回Returns PermissionEngine

返回PermissionEngine。Returns permission engine.

源码Source io/agentscope/core/ReActAgent.java:4737–4743

getPermissionContext

public PermissionContextState getPermissionContext()

deprecated

获取权限上下文。

Returns the permission context.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Use `getAgentState(userId, sessionId).getPermissionContext()` instead.

返回Returns PermissionContextState

返回PermissionContextState。Returns permission context state.

源码Source io/agentscope/core/ReActAgent.java:4746–4749

getMiddlewares

public List<MiddlewareBase> getMiddlewares()

获取 getMiddlewares。

Returns the immutable list of registered middlewares.

返回Returns List<MiddlewareBase>

返回列出。Returns list.

源码Source io/agentscope/core/ReActAgent.java:4752–4754

getModelExecutionConfig

public ExecutionConfig getModelExecutionConfig()

获取模型执行配置。

Returns the per-model-call ExecutionConfig, or null if none was set.

返回Returns ExecutionConfig

返回ExecutionConfig。Returns execution config.

源码Source io/agentscope/core/ReActAgent.java:4757–4759

getToolExecutionConfig

public ExecutionConfig getToolExecutionConfig()

获取工具执行配置。

Returns the per-tool-call ExecutionConfig, or null if none was set.

返回Returns ExecutionConfig

返回ExecutionConfig。Returns execution config.

源码Source io/agentscope/core/ReActAgent.java:4762–4764

getToolExecutionContext

public ToolExecutionContext getToolExecutionContext()

获取工具执行上下文。

Returns the ToolExecutionContext bound at build time, or null if none.

返回Returns ToolExecutionContext

返回ToolExecutionContext。Returns tool execution context.

源码Source io/agentscope/core/ReActAgent.java:4767–4769

isPendingToolRecoveryEnabled

public boolean isPendingToolRecoveryEnabled()

判断是否 isPendingToolRecoveryEnabled。

Returns whether pending-tool-call recovery is enabled (HITL: resume tool calls left in a pending state across call() invocations).

返回Returns boolean

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

源码Source io/agentscope/core/ReActAgent.java:4775–4777

getSystemPrompt

public String getSystemPrompt()

获取系统提示词。

Returns the system prompt (alias for #getSysPrompt()).

返回Returns String

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

源码Source io/agentscope/core/ReActAgent.java:4780–4782

builder

public static Builder builder()

static

返回构建器实例。

Returns the builder.

返回Returns Builder

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

源码Source io/agentscope/core/ReActAgent.java:4784–4786

close

public void close()

关闭连接并释放相关资源。

Releases resources and connections.

源码Source io/agentscope/core/ReActAgent.java:4788–4794

嵌套类详情Nested Class Detail

Builder

@SuppressWarnings("deprecation") public static class Builder

链式配置 ReActAgent 的名称、模型、工具、状态存储、权限与中间件，最后调用 build() 得到实例。位于 io.agentscope.core 包。核心成员包括 name、description、checkRunning、sysPrompt、model、toolkit。

A class in io.agentscope.core that drives agent reasoning, tool calls and conversation execution. Declared in io.agentscope.core.

继承成员Inherited Members

继承自Methods inherited from CallableAgent

call, call, call, call, call, call, call, call, call, call

继承自Methods inherited from StreamableAgent

stream, stream, stream, stream, stream, stream, stream, stream