类class io.agentscope.builder.web.toolbus 2.x

ToolConfirmationCoordinator

@Component public class ToolConfirmationCoordinator

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:54–872

工具确认 Coordinator，承载智能体的部署、调度与服务化运行。位于 io.agentscope.builder.web.toolbus 包。核心成员包括 requestConfirmation、deleteSessionTickets、cancelSession、resolvePersonal、resolveManaged、resolutionEvent。

Coordinates human-in-the-loop tool confirmations.

The durable ticket is the decision authority. A Managed AgentTask ticket captures the full Attempt fence and can only be resolved by the control-plane callback carrying that same fence. Personal chat confirmations remain user-addressable, but are also scoped by session id. Local futures are merely continuations and poll the shared ticket so any replica can deliver a decision.

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`ConfirmationDecision`	记录record	承载确认决策数据的记录类型。 A record in io.agentscope.builder.web.toolbus that carries data used when components deploys, schedules and serves agents.
`ManagedDecision`	记录record	承载托管决策数据的记录类型。 Fully fenced control-plane decision callback.
`DecisionResult`	枚举enum	定义决策结果相关取值的枚举。 Stable outcome used by both HTTP APIs to distinguish stale and replayed decisions.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `ToolConfirmationCoordinator(SessionEventLog eventLog, DataSessionService sessionService, CoordinationStore coordinationStore, ControlPlaneClient controlPlaneClient, long timeoutMs)`	初始化 `ToolConfirmationCoordinator` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public CompletableFuture<Boolean> requestConfirmation(String sessionId, String toolUseId, String toolName, Map<String, Object> input)`	执行请求确认相关操作。 Performs the request confirmation operation.
`public CompletableFuture<Boolean> requestConfirmation(String sessionId, String toolUseId, String toolName, Map<String, Object> input,` `ManagedTurnContext turnContext)`	执行请求确认相关操作。 Creates a confirmation from the immutable turn context carried by RuntimeContext.
`public void deleteSessionTickets(String sessionId)`	删除 `deleteSessionTickets`。 Removes all raw confirmation inputs when their owning session is deleted.
`public void cancelSession(String sessionId, String reason)`	执行取消会话相关操作。 Purges durable tickets and releases waiters owned by an invalidated/interrupted turn.
`public` `DecisionResult resolvePersonal(String sessionId, String toolUseId, boolean allow, String denyMessage)`	解析 `resolvePersonal`。 Resolves a personal-chat confirmation after the HTTP layer authenticated session owner.
`public` `DecisionResult resolveManaged(ManagedDecision decision)`	解析托管。 Resolves a Managed AgentTask confirmation from the control plane with full fencing.
`public Optional<SessionEventDto> resolutionEvent(String sessionId, String toolUseId)`	执行 `resolutionEvent` 方法。 Returns the stable persisted decision event after a successful resolve.
`public` `DecisionResult expire(String sessionId, String toolUseId, long now)`	执行 `expire` 方法。 Expires one pending ticket and resumes a live continuation as a denied tool call.
`public boolean awaitConfirmation(String sessionId, String toolUseId, String toolName, Map<String, Object> input)`	执行 `awaitConfirmation` 方法。 Performs the await confirmation operation.
`public boolean awaitConfirmation(String sessionId, String toolUseId, String toolName, Map<String, Object> input,` `ManagedTurnContext turnContext)`	执行 `awaitConfirmation` 方法。 Performs the await confirmation operation.
`public` `ConfirmationDecision awaitDecision(String sessionId, String toolUseId, String toolName, Map<String, Object> input)`	执行 `awaitDecision` 方法。 Waits for a decision and preserves the human rejection reason for the agent context.
`public` `ConfirmationDecision awaitDecision(String sessionId, String toolUseId, String toolName, Map<String, Object> input, ManagedTurnContext turnContext)`	执行 `awaitDecision` 方法。 Performs the await decision operation.

构造器详情Constructor Detail

ToolConfirmationCoordinator

public ToolConfirmationCoordinator(SessionEventLog eventLog, DataSessionService sessionService, CoordinationStore coordinationStore, ControlPlaneClient controlPlaneClient, long timeoutMs)

初始化 ToolConfirmationCoordinator 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`eventLog`	SessionEventLog	事件日志（类型 `SessionEventLog`）。The event log.
`sessionService`	DataSessionService	会话服务（类型 `DataSessionService`）。The session service.
`coordinationStore`	CoordinationStore	coordination 存储（类型 `CoordinationStore`）。The coordination store.
`controlPlaneClient`	ControlPlaneClient	控制面客户端（类型 `ControlPlaneClient`）。The control plane client.
`timeoutMs`	long	超时 Ms（类型 `long`）。The timeout ms.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:70–81

方法详情Method Detail

requestConfirmation

public CompletableFuture<Boolean> requestConfirmation(String sessionId, String toolUseId, String toolName, Map<String, Object> input)

执行请求确认相关操作。

Performs the request confirmation operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.
`toolName`	String	工具名称（类型 `String`）。The tool name.
`input`	Map<String, Object>	输入消息（类型 `Map`）。The input.

返回Returns CompletableFuture<Boolean>

返回CompletableFuture。Returns completable future.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:83–86

requestConfirmation

public CompletableFuture<Boolean> requestConfirmation(String sessionId, String toolUseId, String toolName, Map<String, Object> input, ManagedTurnContext turnContext)

执行请求确认相关操作。

Creates a confirmation from the immutable turn context carried by RuntimeContext.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.
`toolName`	String	工具名称（类型 `String`）。The tool name.
`input`	Map<String, Object>	输入消息（类型 `Map`）。The input.
`turnContext`	ManagedTurnContext	轮次上下文（类型 `ManagedTurnContext`）。The turn context.

返回Returns CompletableFuture<Boolean>

返回CompletableFuture。Returns completable future.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:92–197

deleteSessionTickets

public void deleteSessionTickets(String sessionId)

删除 deleteSessionTickets。

Removes all raw confirmation inputs when their owning session is deleted.

参数Parameters

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

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:200–202

cancelSession

public void cancelSession(String sessionId, String reason)

执行取消会话相关操作。

Purges durable tickets and releases waiters owned by an invalidated/interrupted turn.

参数Parameters

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

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:205–227

resolvePersonal

public DecisionResult resolvePersonal(String sessionId, String toolUseId, boolean allow, String denyMessage)

解析 resolvePersonal。

Resolves a personal-chat confirmation after the HTTP layer authenticated session owner.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.
`allow`	boolean	allow（类型 `boolean`）。The allow.
`denyMessage`	String	拒绝消息（类型 `String`）。The deny message.

返回Returns DecisionResult

返回DecisionResult。Returns decision result.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:230–249

resolveManaged

public DecisionResult resolveManaged(ManagedDecision decision)

解析托管。

Resolves a Managed AgentTask confirmation from the control plane with full fencing.

参数Parameters

名称Name	类型Type	说明Description
`decision`	ManagedDecision	决策（类型 `ManagedDecision`）。The decision.

返回Returns DecisionResult

返回DecisionResult。Returns decision result.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:252–310

resolutionEvent

public Optional<SessionEventDto> resolutionEvent(String sessionId, String toolUseId)

执行 resolutionEvent 方法。

Returns the stable persisted decision event after a successful resolve.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.

返回Returns Optional<SessionEventDto>

返回可选。Returns optional.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:313–328

expire

public DecisionResult expire(String sessionId, String toolUseId, long now)

执行 expire 方法。

Expires one pending ticket and resumes a live continuation as a denied tool call.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.
`now`	long	当前时间（类型 `long`）。The now.

返回Returns DecisionResult

返回DecisionResult。Returns decision result.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:331–352

awaitConfirmation

public boolean awaitConfirmation(String sessionId, String toolUseId, String toolName, Map<String, Object> input)

执行 awaitConfirmation 方法。

Performs the await confirmation operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.
`toolName`	String	工具名称（类型 `String`）。The tool name.
`input`	Map<String, Object>	输入消息（类型 `Map`）。The input.

返回Returns boolean

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

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:354–357

awaitConfirmation

public boolean awaitConfirmation(String sessionId, String toolUseId, String toolName, Map<String, Object> input, ManagedTurnContext turnContext)

执行 awaitConfirmation 方法。

Performs the await confirmation operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.
`toolName`	String	工具名称（类型 `String`）。The tool name.
`input`	Map<String, Object>	输入消息（类型 `Map`）。The input.
`turnContext`	ManagedTurnContext	轮次上下文（类型 `ManagedTurnContext`）。The turn context.

返回Returns boolean

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

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:359–378

awaitDecision

public ConfirmationDecision awaitDecision(String sessionId, String toolUseId, String toolName, Map<String, Object> input)

执行 awaitDecision 方法。

Waits for a decision and preserves the human rejection reason for the agent context.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.
`toolName`	String	工具名称（类型 `String`）。The tool name.
`input`	Map<String, Object>	输入消息（类型 `Map`）。The input.

返回Returns ConfirmationDecision

返回ConfirmationDecision。Returns confirmation decision.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:381–384

awaitDecision

public ConfirmationDecision awaitDecision(String sessionId, String toolUseId, String toolName, Map<String, Object> input, ManagedTurnContext turnContext)

执行 awaitDecision 方法。

Performs the await decision operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionId`	String	会话标识（类型 `String`）。The session id.
`toolUseId`	String	工具使用标识（类型 `String`）。The tool use id.
`toolName`	String	工具名称（类型 `String`）。The tool name.
`input`	Map<String, Object>	输入消息（类型 `Map`）。The input.
`turnContext`	ManagedTurnContext	轮次上下文（类型 `ManagedTurnContext`）。The turn context.

返回Returns ConfirmationDecision

返回ConfirmationDecision。Returns confirmation decision.

源码Source io/agentscope/builder/web/toolbus/ToolConfirmationCoordinator.java:386–402

嵌套类详情Nested Class Detail

ConfirmationDecision

public record ConfirmationDecision(boolean allow, String reason)

承载确认决策数据的记录类型。位于 io.agentscope.builder.web.toolbus 包。核心成员包括 allow、reason。

A record in io.agentscope.builder.web.toolbus that carries data used when components deploys, schedules and serves agents. Declared in io.agentscope.builder.web.toolbus.

ManagedDecision

public record ManagedDecision( String sessionId, String toolUseId, String approvalId, String agentTaskId, String attemptId, long dispatchGeneration, String turnId, String status, long decisionVersion, boolean allow, String reason)

承载托管决策数据的记录类型。位于 io.agentscope.builder.web.toolbus 包。核心成员包括 sessionId、toolUseId、approvalId、agentTaskId、attemptId、dispatchGeneration。

Fully fenced control-plane decision callback.

DecisionResult

public enum DecisionResult

定义决策结果相关取值的枚举。位于 io.agentscope.builder.web.toolbus 包。核心成员包括 RESOLVED、IDEMPOTENT、NOT_FOUND、FENCE_MISMATCH、EXPIRED、CONFLICT。

Stable outcome used by both HTTP APIs to distinguish stale and replayed decisions.