类class io.agentscope.harness.agent.gateway 2.x

HarnessGateway

public final class HarnessGateway implements Gateway, WakeupDispatcher.WakeupTarget

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:62–847

Harness 网关，承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.gateway 包，实现 Gateway、WakeupDispatcher.WakeupTarget。核心成员包括 create、messageBus、channelManager、setRuntimeContextResolver、getRuntimeContextResolver、bindMainAgent。

Default Gateway implementation. Routes inbound turns by MsgContext#canonicalKey(), serializes concurrent turns per session via SessionTurnGate, and dispatches to the appropriate registered HarnessAgent.

This implementation provides:

Multi-agent registry with fallback to a main agent
Stable session mapping: same MsgContext#canonicalKey() always resolves to the same session id, giving each logical conversation its own memory
Per-session fair mutual exclusion preventing concurrent turns from racing
Outbound address tracking for proactive delivery (e.g. subagent announces)

方法摘要Method Summary

方法Method	说明Description
`public static` `HarnessGateway create(ChannelManager channelManager)` static	创建并返回实例。 Creates a gateway with a channel manager for outbound delivery.
`public static` `HarnessGateway create(ChannelManager channelManager, MessageBus messageBus)` static	创建网关使用渠道管理器和消息总线。 Creates a gateway with a channel manager and message bus.
`public static` `HarnessGateway create()` static	创建并返回实例。 Creates a gateway without outbound delivery support.
`public` `MessageBus messageBus()`	返回消息总线。 Returns the message bus, or null if not configured.
`public` `ChannelManager channelManager()`	返回渠道管理器。 The channel manager for outbound delivery, or null if not configured.
`public void setRuntimeContextResolver(ChannelRuntimeContextResolver runtimeContextResolver)`	设置运行时上下文解析器。 Sets an optional `ChannelRuntimeContextResolver` used when building the per-turn `RuntimeContext`.
`public` `ChannelRuntimeContextResolver getRuntimeContextResolver()`	获取运行时上下文解析器。 Returns the configured `ChannelRuntimeContextResolver`, or `null`.
`public void bindMainAgent(HarnessAgent agent)`	设置该参数。 Performs the bind main agent operation.
`public void registerAgent(String agentId,` `HarnessAgent agent)`	注册智能体。 Registers the agent.
`public` `HarnessAgent findAgent(String agentId)`	查找智能体。 Returns the agent registered under `agentId`, or null if not found.
`public Mono<Msg> run(MsgContext context, List<Msg> messages)`	执行运行相关操作。 Performs the run operation.
`public Mono<Msg> run(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress)`	执行运行相关操作。 Performs the run operation.
`public Mono<Msg> run(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress, RuntimeContext callerContext)`	执行运行相关操作。 Performs the run operation.
`public Mono<Msg> run(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress, RuntimeContext callerContext, InboundMessage inboundMessage)`	执行运行相关操作。 Performs the run operation.
`public Flux<AgentEvent> runStream(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress)`	运行流。 Runs the stream.
`public Flux<AgentEvent> runStream(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress, RuntimeContext callerContext)`	运行流。 Runs the stream.
`public Flux<AgentEvent> runStream(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress, RuntimeContext callerContext, InboundMessage inboundMessage)`	运行流。 Runs the stream.
`public boolean deliverToSession(String sessionId, List<Msg> messages)`	执行 `deliverToSession` 方法。 Delivers proactive outbound messages through the channel manager using the session's last recorded outbound address.
`public String exposeSubagent(String agentId, String sessionId,` `Agent agent, OutboundAddress replyTo)`	执行 `exposeSubagent` 方法。 Exposes a spawned subagent as a user-addressable entry point.
`public void revokeSubagent(String subagentId)`	设置该参数。 Revokes a previously exposed subagent, removing it from the live cache and the registry.
`public void setSubagentRegistry(SubagentRegistry registry)`	设置子智能体注册表。 Installs the durable `SubagentRegistry`.
`public void setSubagentMaterializer(SubagentMaterializer materializer)`	设置子智能体物化器。 Installs the `SubagentMaterializer` used to rebuild subagents that are not present in the local live cache (cross-node / post-restart recovery).
`public void setBaseStore(BaseStore store)`	设置基类存储。 Installs the `BaseStore` used to persist session routing metadata across nodes.
`public void setSessionTurnGate(SessionTurnGate gate)`	设置 `setSessionTurnGate`。 Installs the `SessionTurnGate` used to serialize concurrent turns per session.
`public Mono<Msg> runSubagent(String subagentId, List<Msg> messages)`	运行子智能体。 Runs the subagent.
`public Flux<AgentEvent> runSubagentStream(String subagentId, List<Msg> messages)`	运行子智能体流。 Runs the subagent stream.
`public void registerExternalSession(String sessionId, String gateKey)`	注册外部会话。 Adopts a control-plane-allocated session id so `#runWakeup(String, String)` can resolve it.
`public boolean isSessionRunning(String sessionId)`	判断是否会话运行中。 Returns `true` when the given session is currently inside a gated turn (a run is in progress).
`public Mono<Msg> runWakeup(String sessionId)` deprecated	运行 `runWakeup`。 {@inheritDoc}
`public Mono<Msg> runWakeup(String userId, String sessionId)`	运行 `runWakeup`。 Triggers a wakeup-driven run for an idle session, propagating the owning user id when present.

方法详情Method Detail

create

public static HarnessGateway create(ChannelManager channelManager)

static

创建并返回实例。

Creates a gateway with a channel manager for outbound delivery.

参数Parameters

名称Name	类型Type	说明Description
`channelManager`	ChannelManager	渠道管理器（类型 `ChannelManager`）。The channel manager.

返回Returns HarnessGateway

返回HarnessGateway。Returns harness gateway.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:120–122

create

public static HarnessGateway create(ChannelManager channelManager, MessageBus messageBus)

static

创建网关使用渠道管理器和消息总线。

Creates a gateway with a channel manager and message bus.

参数Parameters

名称Name	类型Type	说明Description
`channelManager`	ChannelManager	渠道管理器（类型 `ChannelManager`）。The channel manager.
`messageBus`	MessageBus	消息总线（类型 `MessageBus`）。The message bus.

返回Returns HarnessGateway

返回HarnessGateway。Returns harness gateway.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:125–128

create

public static HarnessGateway create()

static

创建并返回实例。

Creates a gateway without outbound delivery support.

返回Returns HarnessGateway

返回HarnessGateway。Returns harness gateway.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:131–133

messageBus

public MessageBus messageBus()

返回消息总线。

Returns the message bus, or null if not configured.

返回Returns MessageBus

返回MessageBus。Returns message bus.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:136–138

channelManager

public ChannelManager channelManager()

返回渠道管理器。

The channel manager for outbound delivery, or null if not configured.

返回Returns ChannelManager

返回ChannelManager。Returns channel manager.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:141–143

setRuntimeContextResolver

public void setRuntimeContextResolver(ChannelRuntimeContextResolver runtimeContextResolver)

设置运行时上下文解析器。

Sets an optional ChannelRuntimeContextResolver used when building the per-turn RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContextResolver`	ChannelRuntimeContextResolver	运行时上下文解析器（类型 `ChannelRuntimeContextResolver`）。The runtime context resolver.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:149–151

getRuntimeContextResolver

public ChannelRuntimeContextResolver getRuntimeContextResolver()

获取运行时上下文解析器。

Returns the configured ChannelRuntimeContextResolver, or null.

返回Returns ChannelRuntimeContextResolver

返回ChannelRuntimeContextResolver。Returns channel runtime context resolver.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:154–156

bindMainAgent

public void bindMainAgent(HarnessAgent agent)

设置该参数。

Performs the bind main agent operation.

参数Parameters

名称Name	类型Type	说明Description
`agent`	HarnessAgent	智能体（类型 `HarnessAgent`）。The agent.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:158–165

registerAgent

public void registerAgent(String agentId, HarnessAgent agent)

注册智能体。

Registers the agent.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`agent`	HarnessAgent	智能体（类型 `HarnessAgent`）。The agent.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:167–172

findAgent

public HarnessAgent findAgent(String agentId)

查找智能体。

Returns the agent registered under agentId, or null if not found.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.

返回Returns HarnessAgent

返回HarnessAgent。Returns harness agent.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:178–181

run

public Mono<Msg> run(MsgContext context, List<Msg> messages)

执行运行相关操作。

Performs the run operation.

参数Parameters

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

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:183–186

run

public Mono<Msg> run(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress)

执行运行相关操作。

Performs the run operation.

参数Parameters

名称Name	类型Type	说明Description
`context`	MsgContext	上下文（类型 `MsgContext`）。The context.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.
`outboundAddress`	OutboundAddress	出站 Address（类型 `OutboundAddress`）。The outbound address.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:188–191

run

public Mono<Msg> run(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress, RuntimeContext callerContext)

执行运行相关操作。

Performs the run operation.

参数Parameters

名称Name	类型Type	说明Description
`context`	MsgContext	上下文（类型 `MsgContext`）。The context.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.
`outboundAddress`	OutboundAddress	出站 Address（类型 `OutboundAddress`）。The outbound address.
`callerContext`	RuntimeContext	caller 上下文（类型 `RuntimeContext`）。The caller context.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:193–200

run

public Mono<Msg> run(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress, RuntimeContext callerContext, InboundMessage inboundMessage)

执行运行相关操作。

Performs the run operation.

参数Parameters

名称Name	类型Type	说明Description
`context`	MsgContext	上下文（类型 `MsgContext`）。The context.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.
`outboundAddress`	OutboundAddress	出站 Address（类型 `OutboundAddress`）。The outbound address.
`callerContext`	RuntimeContext	caller 上下文（类型 `RuntimeContext`）。The caller context.
`inboundMessage`	InboundMessage	入站消息（类型 `InboundMessage`）。The inbound message.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:202–231

runStream

public Flux<AgentEvent> runStream(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress)

运行流。

Runs the stream.

参数Parameters

名称Name	类型Type	说明Description
`context`	MsgContext	上下文（类型 `MsgContext`）。The context.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.
`outboundAddress`	OutboundAddress	出站 Address（类型 `OutboundAddress`）。The outbound address.

返回Returns Flux<AgentEvent>

返回Flux。Returns flux.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:233–237

runStream

public Flux<AgentEvent> runStream(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress, RuntimeContext callerContext)

运行流。

Runs the stream.

参数Parameters

名称Name	类型Type	说明Description
`context`	MsgContext	上下文（类型 `MsgContext`）。The context.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.
`outboundAddress`	OutboundAddress	出站 Address（类型 `OutboundAddress`）。The outbound address.
`callerContext`	RuntimeContext	caller 上下文（类型 `RuntimeContext`）。The caller context.

返回Returns Flux<AgentEvent>

返回Flux。Returns flux.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:239–246

runStream

public Flux<AgentEvent> runStream(MsgContext context, List<Msg> messages, OutboundAddress outboundAddress, RuntimeContext callerContext, InboundMessage inboundMessage)

运行流。

Runs the stream.

参数Parameters

名称Name	类型Type	说明Description
`context`	MsgContext	上下文（类型 `MsgContext`）。The context.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.
`outboundAddress`	OutboundAddress	出站 Address（类型 `OutboundAddress`）。The outbound address.
`callerContext`	RuntimeContext	caller 上下文（类型 `RuntimeContext`）。The caller context.
`inboundMessage`	InboundMessage	入站消息（类型 `InboundMessage`）。The inbound message.

返回Returns Flux<AgentEvent>

返回Flux。Returns flux.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:248–277

deliverToSession

public boolean deliverToSession(String sessionId, List<Msg> messages)

执行 deliverToSession 方法。

Delivers proactive outbound messages through the channel manager using the session's last recorded outbound address.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.

返回Returns boolean

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

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:335–346

exposeSubagent

public String exposeSubagent(String agentId, String sessionId, Agent agent, OutboundAddress replyTo)

执行 exposeSubagent 方法。

Exposes a spawned subagent as a user-addressable entry point.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。the subagent type identifier
`sessionId`	String	会话标识（类型 `String`）。the session id assigned to the subagent
`agent`	Agent	智能体实例。the agent instance
`replyTo`	OutboundAddress	回复到（类型 `OutboundAddress`）。the outbound address for delivering replies; may be null

返回Returns String

返回字符串结果。the subagentId handle for direct addressing

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:369–389

revokeSubagent

public void revokeSubagent(String subagentId)

设置该参数。

Revokes a previously exposed subagent, removing it from the live cache and the registry.

参数Parameters

名称Name	类型Type	说明Description
`subagentId`	String	子智能体标识（类型 `String`）。The subagent id.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:392–401

setSubagentRegistry

public void setSubagentRegistry(SubagentRegistry registry)

设置子智能体注册表。

Installs the durable SubagentRegistry.

参数Parameters

名称Name	类型Type	说明Description
`registry`	SubagentRegistry	注册表（类型 `SubagentRegistry`）。The registry.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:407–411

setSubagentMaterializer

public void setSubagentMaterializer(SubagentMaterializer materializer)

设置子智能体物化器。

Installs the SubagentMaterializer used to rebuild subagents that are not present in the local live cache (cross-node / post-restart recovery).

参数Parameters

名称Name	类型Type	说明Description
`materializer`	SubagentMaterializer	物化器（类型 `SubagentMaterializer`）。The materializer.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:417–419

setBaseStore

public void setBaseStore(BaseStore store)

设置基类存储。

Installs the BaseStore used to persist session routing metadata across nodes.

参数Parameters

名称Name	类型Type	说明Description
`store`	BaseStore	存储实例（类型 `BaseStore`）。The store.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:425–427

setSessionTurnGate

public void setSessionTurnGate(SessionTurnGate gate)

设置 setSessionTurnGate。

Installs the SessionTurnGate used to serialize concurrent turns per session.

参数Parameters

名称Name	类型Type	说明Description
`gate`	SessionTurnGate	gate（类型 `SessionTurnGate`）。turn gate implementation; ignored when `null`

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:435–439

runSubagent

public Mono<Msg> runSubagent(String subagentId, List<Msg> messages)

运行子智能体。

Runs the subagent.

参数Parameters

名称Name	类型Type	说明Description
`subagentId`	String	子智能体标识（类型 `String`）。The subagent id.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:484–503

runSubagentStream

public Flux<AgentEvent> runSubagentStream(String subagentId, List<Msg> messages)

运行子智能体流。

Runs the subagent stream.

参数Parameters

名称Name	类型Type	说明Description
`subagentId`	String	子智能体标识（类型 `String`）。The subagent id.
`messages`	List<Msg>	消息列表（类型 `List`）。The messages.

返回Returns Flux<AgentEvent>

返回Flux。Returns flux.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:539–550

registerExternalSession

public void registerExternalSession(String sessionId, String gateKey)

注册外部会话。

Adopts a control-plane-allocated session id so #runWakeup(String, String) can resolve it.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。external session id assigned by the control plane
`gateKey`	String	gate 键（类型 `String`）。stable gate key (e.g. `team:{teamName}:{role}`)

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:588–597

isSessionRunning

public boolean isSessionRunning(String sessionId)

判断是否会话运行中。

Returns true when the given session is currently inside a gated turn (a run is in progress).

参数Parameters

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

返回Returns boolean

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

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:604–607

runWakeup

public Mono<Msg> runWakeup(String sessionId)

deprecated

运行 runWakeup。

{@inheritDoc} Delegates to #runWakeup(String, String) with a null user id.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `#runWakeup(String, String)` so the wakeup-driven round loads agent state from the correct `(userId, sessionId)` slot. This overload preserves legacy anonymous-wakeup behavior.

参数Parameters

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

返回Returns Mono<Msg>

返回Mono。Returns mono.

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:618–622

runWakeup

public Mono<Msg> runWakeup(String userId, String sessionId)

运行 runWakeup。

Triggers a wakeup-driven run for an idle session, propagating the owning user id when present.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。the owning user id carried by the wakeup entry; may be `null` or blank
`sessionId`	String	会话标识（类型 `String`）。the session to wake up

返回Returns Mono<Msg>

返回Mono。the agent's response, or `Mono#empty()` if the session is unknown

源码Source io/agentscope/harness/agent/gateway/HarnessGateway.java:640–674

继承成员Inherited Members

继承自Methods inherited from Gateway

run, runStream