34 · 智能体与动作的终止（Termination）

Embabel 提供了提前终止 Agent 与动作的机制，可以优雅终止（在下一个检查点）也可以立即终止。 这适用于用户取消、超时处理、资源上限、或严重错误处理等场景。

在"信号"与"异常"之间选择

机制	何时使用	行为
优雅（Signal 信号）	"让我把手上的活干完，然后停" —— 副作用需要跑完	在下一个检查点终止；当前操作正常完成
立即（Exception 异常）	"立刻停，没别的要做了" —— 不需要继续处理	立即终止；异常抛出之后的任何东西都不执行

Agent 终止（Agent Termination）

Agent 终止会停掉整个 Agent 进程。进程状态变为 TERMINATED。

优雅的 Agent 终止（信号）

当"当前操作应当先跑完再停"时，用 terminateAgent()。Agent 会在下一个检查点 tick 之前终止。

// 信号："让我把手上的活干完，然后停掉 agent"
@LlmTool(description = "Save all pending work and shutdown")
fun saveAndShutdown(ctx: ProcessContext): String {
    repository.saveAll(pendingRecords)              // 副作用完成
    ctx.terminateAgent("All work saved, shutting down")
    return "Saved ${pendingRecords.size} records"   // 工具正常结束
}

立即的 Agent 终止（异常）

当 Agent 必须立即停止时，用 TerminateAgentException。不会再有工具调用或动作执行。

// 异常："立刻停，没别的要做了"
@LlmTool(description = "Validate critical prerequisites")
fun validatePrerequisites(): String {
    if (!authService.hasRequiredPermissions()) {
        throw TerminateAgentException("Missing required permissions")
        // 这里之后的任何代码都不会执行
    }
    return "Prerequisites validated"
}

动作终止（Action Termination）

动作终止只停掉当前动作。Agent 会继续执行计划中的下一个动作。 这适合"跳过有问题的步骤、但让整体目标继续推进"的场景。

⚠️ 要让动作终止后允许重试，该动作必须定义为 canRerun = true。

优雅的动作终止（信号）

当"当前工具调用应当先跑完再停掉该动作"时，用 terminateAction()。动作会在工具调用之间终止。

优雅的动作终止只适用于使用工具循环的、基于 LLM 的动作。 对简单的转换类动作，请改用 TerminateActionException。

// 信号："让我把这次工具调用做完，然后停"
@LlmTool(description = "Save and shutdown")
fun saveAndStop(ctx: ProcessContext): String {
    customerRepository.save(record)                 // 副作用完成
    ctx.terminateAction("Save complete, no more work needed")
    return "Saved"                                  // 工具正常结束
}

立即的动作终止（异常）

当动作必须立即停止时，用 TerminateActionException。当前批次中剩余的工具调用都会被跳过。

// 异常："立刻停，没什么可做的了"
@LlmTool(description = "Check service health")
fun checkHealth(): String {
    if (!mcpClient.isConnected("required_service")) {
        throw TerminateActionException("Service unavailable")
        // 这里之后的任何代码都不会执行
    }
    return "Healthy"
}

同时捕获两种异常

TerminateAgentException 与 TerminateActionException 都继承自 TerminationException， 因此可以把它们一起捕获：

try {
    tool.execute()
} catch (e: TerminationException) {
    logger.info("Terminated: ${e.reason}")
    // 同时处理 Agent 终止与动作终止
}

小结（Summary）

作用域	机制	方法 / 异常	使用场景
Agent	优雅	processContext.terminateAgent(reason)	"把手上的活干完，然后停掉 Agent"
Agent	立即	throw TerminateAgentException(reason)	"立刻停 —— 严重错误，无法恢复"
Action	优雅	processContext.terminateAction(reason)	"把当前工具调用做完，然后停掉该动作"
Action	立即	throw TerminateActionException(reason)	"立刻停 —— 换个路子试"