Spring Ai Alibaba Graph源码解读系列—action

原文链接地址：Spring Ai Alibaba Graph源码解读系列---action

从今天起，我们来系统梳理下Spring Ai Alibaba Graph的源码，会给出各个部分的功能、作用，以及会新增许多Graph的案例，初步会在一个月内完结。因为目前相关代码正在快速迭代中，维护的飞书在线云文档会同步最新的源码解读及案例，让我们持续跟进业界最新技术，Let's Go!

项目源码地址如下：github.com/alibaba/spr...

本期先介绍action部分，主要是接收OverAllState、RunnableConfig对节点、边触发相应的动作

如果你初步使用过Graph框架，你会发现我们的节点都是NodeAction的实现类，条件边都是EdgeAction的实现类

action

NodeAction

函数式接口，定义图中节点的基本同步操作

apply 方法：接受当前状态，并返回更新的状态映射

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;

import java.util.Map;

@FunctionalInterface
public interface NodeAction {

    Map<String, Object> apply(OverAllState state) throws Exception;

}

AsyncNodeAction

函数式接口，定义节点的异步操作行为，表示接受状态参数并返回异步结果

|-----------|---------------------------------------------------|
| 方法名称 | 描述 |
| apply | 核心执行方法，接受当前状态，返回包含更新状态的 CompletableFuture |
| nodeasync | 将同步的NodeAction转换为异步版本，通过CompletableFuture包装同步操作结果 |

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;
import io.opentelemetry.context.Context;

import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.function.Function;

/**
 * Represents an asynchronous node action that operates on an agent state and returns
 * state update.
 *
 */
@FunctionalInterface
public interface AsyncNodeAction extends Function<OverAllState, CompletableFuture<Map<String, Object>>> {

    /**
     * Applies this action to the given agent state.
     * @param state the agent state
     * @return a CompletableFuture representing the result of the action
     */
    CompletableFuture<Map<String, Object>> apply(OverAllState state);

    /**
     * Creates an asynchronous node action from a synchronous node action.
     * @param syncAction the synchronous node action
     * @return an asynchronous node action
     */
    static AsyncNodeAction nodeasync(NodeAction syncAction) {
       return state -> {
          Context context = Context.current();
          CompletableFuture<Map<String, Object>> result = new CompletableFuture<>();
          try {
             result.complete(syncAction.apply(state));
          }
          catch (Exception e) {
             result.completeExceptionally(e);
          }
          return result;
       };
    }

}

NodeActionWithConfig

函数式接口，定义图中节点的基本同步操作，同时携带运行配置信息

apply 方法：接受当前状态和运行配置，并返回更新的状态映射

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;
import com.alibaba.cloud.ai.graph.RunnableConfig;

import java.util.Map;

@FunctionalInterface
public interface NodeActionWithConfig {

    Map<String, Object> apply(OverAllState state, RunnableConfig config) throws Exception;

}

AsyncNodeActionWithConfig

函数式接口，用于定义节点的异步操作行为，接受状态和配置参数并返回异步结果

|-----------|-------------------------------------------------------------------------|
| 方法名称 | 描述 |
| apply | 核心执行方法，接受当前状态和运行配置，返回包含更新状态的 CompletableFuture |
| nodeasync | 将同步的NodeActionWithConfig转换为异步版本，通过CompletableFuture包装同步操作结果 |
| of | 将简单的AsyncNodeAction (只接受状态参数) 转换为 AsyncNodeActionWithConfig (接受状态和配置参数) |

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;
import com.alibaba.cloud.ai.graph.RunnableConfig;
import io.opentelemetry.context.Context;

import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.function.BiFunction;

public interface AsyncNodeActionWithConfig
       extends BiFunction<OverAllState, RunnableConfig, CompletableFuture<Map<String, Object>>> {

    /**
     * Applies this action to the given agent state.
     * @param state the agent state
     * @return a CompletableFuture representing the result of the action
     */
    CompletableFuture<Map<String, Object>> apply(OverAllState state, RunnableConfig config);

    static AsyncNodeActionWithConfig nodeasync(NodeActionWithConfig syncAction) {
       return (state, config) -> {
          Context context = Context.current();
          CompletableFuture<Map<String, Object>> result = new CompletableFuture<>();
          try {
             result.complete(syncAction.apply(state, config));
          }
          catch (Exception e) {
             result.completeExceptionally(e);
          }
          return result;
       };
    }

    /**
     * Adapts a simple AsyncNodeAction to an AsyncNodeActionWithConfig.
     * @param action the simple AsyncNodeAction to be adapted
     * @return an AsyncNodeActionWithConfig that wraps the given AsyncNodeAction
     */
    static AsyncNodeActionWithConfig of(AsyncNodeAction action) {
       return (t, config) -> action.apply(t);
    }

}

EdgeAction

函数式接口，定义图中边的条件判断操作

apply 方法：接受当前状态，返回下一个执行节点 ID

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;

/**
 * Represents an edge action that operates on an agent state and returns a result.
 *
 */
@FunctionalInterface
public interface EdgeAction {

    /**
     * Applies this action to the given agent state.
     * @param state the agent state
     * @return a result of the action
     * @throws Exception if an error occurs during the action
     */
    String apply(OverAllState state) throws Exception;

}

AsyncEdgeAction

函数式接口，定义图中边的异步条件判断操作，接受状态参数并返回字符串结果

|-----------|---------------------------------------------------|
| 方法名称 | 描述 |
| apply | 核心执行方法，接受当前状态，返回下一步执行的节点ID |
| edgeasync | 将同步的EdgeAction转换为异步版本，通过CompletableFuture包装同步操作结果 |

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;
import io.opentelemetry.context.Context;

import java.util.concurrent.CompletableFuture;
import java.util.function.Function;

/**
 * Represents an asynchronous edge action that operates on an agent state and returns a
 * new route.
 *
 */
@FunctionalInterface
public interface AsyncEdgeAction extends Function<OverAllState, CompletableFuture<String>> {

    /**
     * Applies this action to the given agent state.
     * @param state the agent state
     * @return a CompletableFuture representing the result of the action
     */
    CompletableFuture<String> apply(OverAllState state);

    /**
     * Creates an asynchronous edge action from a synchronous edge action.
     * @param syncAction the synchronous edge action
     * @return an asynchronous edge action
     */
    static AsyncEdgeAction edgeasync(EdgeAction syncAction) {
       return state -> {
          Context context = Context.current();
          CompletableFuture<String> result = new CompletableFuture<>();
          try {
             result.complete(syncAction.apply(state));
          }
          catch (Exception e) {
             result.completeExceptionally(e);
          }
          return result;
       };
    }

}

Command

封装图执行的接下一个节点，及状态更新

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;

import java.util.Map;
import java.util.Objects;
import java.util.Optional;

/**
 * Represents the outcome of a {@link CommandAction} within a LangGraph4j graph. A
 * {@code Command} encapsulates instructions for the graph's next step, including an
 * optional target node to transition to and a map of updates to be applied to the
 * {@link OverAllState}.
 *
 * @param gotoNode containing the name of the next node to execute.
 * @param update A {@link Map} containing key-value pairs representing updates to be
 * merged into the current agent state. An empty map indicates no state updates.
 */
public record Command(String gotoNode, Map<String, Object> update) {

    public Command {
       Objects.requireNonNull(gotoNode, "gotoNode cannot be null");
       Objects.requireNonNull(update, "update cannot be null");
    }

    /**
     * Constructs a {@code Command} that specifies only the next node to transition to,
     * with no state updates. If {@code gotoNode} is null, it will be treated as an empty
     * {@link Optional}.
     * @param gotoNode The name of the next node to transition to. Can be null.
     */
    public Command(String gotoNode) {
       this(gotoNode, Map.of());
    }

}

CommandAction

函数式接口，定义 Command 对象的节点操作

apply 方法：接受当前状态和运行配置，返回 Command 对象

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;
import com.alibaba.cloud.ai.graph.RunnableConfig;

@FunctionalInterface
public interface CommandAction {

    Command apply(OverAllState state, RunnableConfig config) throws Exception;

}

AsyncCommandAction

函数式接口，定义异步的命令动作，接受状态和配置参数并返回异步命令结果

java 复制代码

package com.alibaba.cloud.ai.graph.action;

import com.alibaba.cloud.ai.graph.OverAllState;
import com.alibaba.cloud.ai.graph.RunnableConfig;
import io.opentelemetry.context.Context;

import java.util.concurrent.CompletableFuture;
import java.util.function.BiFunction;

public interface AsyncCommandAction extends BiFunction<OverAllState, RunnableConfig, CompletableFuture<Command>> {

    static AsyncCommandAction nodeasync(CommandAction syncAction) {
       return (state, config) -> {
          Context context = Context.current();
          var result = new CompletableFuture<Command>();
          try {
             result.complete(syncAction.apply(state, config));
          }
          catch (Exception e) {
             result.completeExceptionally(e);
          }
          return result;
       };
    }

    static AsyncCommandAction of(AsyncEdgeAction action) {
       return (state, config) -> action.apply(state).thenApply(Command::new);
    }

}