docs(CallAgent.java): add comprehensive Javadoc comments and method d…

…escriptions

agent-executor/src/main/java/org/bsc/langgraph4j/agentexecutor/actions/CallAgent.java

@@ -13,15 +13,31 @@
 
 import java.util.Map;
 
+/**
+ * The CallAgent class implements the NodeAction interface for handling 
+ * actions related to an AgentExecutor's state.
+ */
 @Slf4j
 public class CallAgent implements NodeAction<AgentExecutor.State> {
 
     final Agent agent;
 
+    /**
+     * Constructs a CallAgent with the specified agent.
+     *
+     * @param agent the agent to be associated with this CallAgent
+     */
     public CallAgent( Agent agent ) {
         this.agent = agent;
     }
 
+    /**
+     * Maps the result of the response from an AI message to a structured format.
+     *
+     * @param response the response containing the AI message
+     * @return a map containing the agent's outcome
+     * @throws IllegalStateException if the finish reason of the response is unsupported
+     */
     private Map<String,Object> mapResult( Response<AiMessage> response )  {
 
         var content = response.content();
@@ -44,6 +60,13 @@ private Map<String,Object> mapResult( Response<AiMessage> response )  {
         throw new IllegalStateException("Unsupported finish reason: " + response.finishReason() );
     }
 
+    /**
+     * Applies the action to the given state and returns the result.
+     *
+     * @param state the state to which the action is applied
+     * @return a map containing the agent's outcome
+     * @throws IllegalArgumentException if no input is provided in the state
+     */
     @Override
     public Map<String,Object> apply( AgentExecutor.State state )  {
         log.trace( "callAgent" );