Embabel Agent Documentation/com.embabel.agent.core/ReplanRequestedException

ReplanRequestedException

class ReplanRequestedException constructor(val reason: String, val blackboardUpdater: BlackboardUpdater = BlackboardUpdater {}) : RuntimeException

Exception thrown by a tool to signal that the tool loop should terminate and the agent should replan based on the updated blackboard state.

This enables tools to influence agent behavior at a higher level than just returning results. Use cases include:

Chat routing: A routing tool classifies user intent and requests replan to switch to the appropriate handler action
Discovery: A tool discovers that the current approach won't work and the agent should try a different plan
State changes: A tool detects significant state changes that require the agent to reassess its goals

When caught by the tool loop:

The loop terminates gracefully (no error)
blackboardUpdater is made available for the caller to apply
The caller (typically action executor) can trigger GOAP replanning

Example usage:

@LlmTool(description = "Routes user to appropriate handler")
fun routeUser(message: String): String {
    val intent = classifyIntent(message)
    throw ReplanRequestedException(
        reason = "Classified as $intent request",
        blackboardUpdater = { bb -> bb.addObject(intent) }
    )
}