Package com.embabel.agent.core

Class ReplanRequestedException

  • All Implemented Interfaces:
    com.embabel.agent.api.tool.ToolControlFlowSignal , java.io.Serializable 
    
public final class ReplanRequestedException
extends RuntimeException implements ToolControlFlowSignal

    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) }
    )
}

    • Constructor Detail

      • ReplanRequestedException

        ReplanRequestedException(String reason, BlackboardUpdater blackboardUpdater)
        Parameters:
        reason - Human-readable explanation of why replan is needed
        blackboardUpdater - Callback to update the blackboard before replanning

      • ReplanRequestedException

        ReplanRequestedException(String reason)
        Parameters:
        reason - Human-readable explanation of why replan is needed