Spring AI Alibaba 智能 Agent 开发实战

配置与运行

在 application.yml 中配置 API Key，或使用环境变量：

spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}

启动应用后访问 http://localhost:8080/chat?query=你好 即可测试。

核心概念

ReactAgent

这是最基础的 Agent 实现，遵循 ReAct 范式。它会在推理（Reasoning）和行动（Acting）之间循环，直到解决问题。

基本用法如下：

ReactAgent agent = ReactAgent.builder()
    .name("MyAgent")
    .model(chatModel)
    .instruction("你是一个专业的助手")
    .tools(tool1, tool2)
    .enableLogging(true)
    .build();

AssistantMessage response = agent.call("用户的问题");

工具（Tools）

工具是 Agent 执行外部操作的关键，比如调用 API 或查询数据库。自定义工具需要实现 BiFunction 接口：

public class CalculatorTool implements BiFunction<CalculatorRequest, ToolContext, String> {
    public static final String DESCRIPTION = "执行数学计算";

    @Override
    public String apply(CalculatorRequest request, ToolContext context) {
        double result = request.a + request.b;
        return String.valueOf(result);
    }

    // 定义请求参数结构
    public static class CalculatorRequest {
        @JsonProperty(required = true)
        @JsonPropertyDescription("第一个数字")
        public double a;

        @JsonProperty(required = true)
        @JsonPropertyDescription("第二个数字")
        public double b;
    }

    // 创建回调
    public static ToolCallback createToolCallback() {
        return FunctionToolCallback.builder("calculator", new CalculatorTool())
                .description(DESCRIPTION)
                .inputType(CalculatorRequest.class)
                .build();
    }
}

注册后即可在 Agent 中使用：

ReactAgent agent = ReactAgent.builder()
    .name("CalculatorAgent")
    .model(chatModel)
    .tools(CalculatorTool.createToolCallback())
    .build();

状态管理

Agent 使用 OverAllState 来管理全局状态，适合复杂流程中的数据共享：

Optional<OverAllState> state = agent.invoke("问题");
if (state.isPresent()) {
    OverAllState overallState = state.get();
    Optional<Object> messages = overallState.value("messages");
}

Agent Framework 使用指南

多 Agent 编排

当单一 Agent 无法满足需求时，可以使用编排模式。

SequentialAgent（顺序执行）

前一个 Agent 的输出作为下一个的输入，适合流水线作业：

// 写作 Agent
ReactAgent writer = ReactAgent.builder()
    .name("writer")
    .model(chatModel)
    .instruction("你是一个作家")
    .outputKey("content")
    .build();

// 编辑 Agent
ReactAgent editor = ReactAgent.builder()
    .name("editor")
    .model(chatModel)
    .instruction("你是一个编辑")
    .inputKey("content")
    .outputKey("edited_content")
    .build();

SequentialAgent sequentialAgent = SequentialAgent.builder()
    .name("writing-pipeline")
    .rootAgent(writer)
    .subAgents(List.of(editor))
    .build();

AssistantMessage result = sequentialAgent.call("写一篇关于春天的文章");

ParallelAgent（并行执行）

多个 Agent 同时工作，最后合并结果：

ParallelAgent parallelAgent = ParallelAgent.builder()
    .name("multi-writer")
    .rootAgent(proseWriter)
    .subAgents(List.of(poemWriter, summaryWriter))
    .mergeStrategy(new ParallelAgent.DefaultMergeStrategy())
    .maxConcurrency(3)
    .build();

Hooks 与 Interceptors

通过钩子和拦截器可以增强 Agent 的控制力。

• HumanInTheLoopHook: 关键决策点暂停，等待人工确认。
• SummarizationHook: 长对话自动摘要，节省 Token。
• ToolRetryInterceptor: 失败的工具调用自动重试。

示例配置：

SummarizationHook hook = SummarizationHook.builder()
    .trigger(10000)
    .clearAtLeast(6000)
    .keep(4)
    .build();

ReactAgent agent = ReactAgent.builder()
    .name("agent")
    .model(chatModel)
    .hooks(hook)
    .build();

Graph Core 使用指南

Graph Core 提供了更底层的图计算能力，适合复杂的工作流编排。

定义状态图

使用 StateGraph 定义节点和边：

OverAllStateFactory stateFactory = () -> {
    OverAllState state = new OverAllState();
    state.registerKeyAndStrategy("input", new ReplaceStrategy());
    state.registerKeyAndStrategy("output", new ReplaceStrategy());
    return state;
};

StateGraph graph = new StateGraph("MyWorkflow", stateFactory)
    .addNode("node1", node_async(nodeAction1))
    .addNode("node2", node_async(nodeAction2))
    .addEdge(START, "node1")
    .addEdge("node1", "node2")
    .addEdge("node2", END);

编译与执行

将图编译为 CompiledGraph 后可直接调用：

CompiledGraph compiledGraph = stateGraph.compile();
OverAllState initialState = new OverAllState();
initialState.put("input", "任务数据");
Optional<OverAllState> result = compiledGraph.invoke(initialState);

高级特性

A2A 通信

支持分布式 Agent 之间的协作，需集成 Nacos 服务发现。

动态配置与监控

• Nacos 配置: 支持运行时动态调整 Agent 行为。
• OpenTelemetry: 集成可观测性，监控链路追踪。

MCP 支持

通过 Model Context Protocol 集成外部工具，扩展 Agent 能力边界。

最佳实践

1. 单一职责: 每个 Agent 专注特定任务，避免臃肿。
2. 指令清晰: 系统提示词要具体，减少幻觉。
3. 错误处理: 配置重试机制和超时控制。
4. 安全: 敏感信息走环境变量，工具调用限制权限。

常见问题

Q: 如何选择合适的 Agent 类型？ 简单任务用 ReactAgent，顺序处理用 SequentialAgent，复杂工作流建议直接用 Graph Core。

Q: 如何处理长对话？ 启用 SummarizationHook 自动压缩上下文，避免超出 Token 限制。

Q: 如何调试？ 开启日志 enableLogging(true)，检查 OverAllState 中的中间状态，或使用 Studio UI 可视化调试。

参考资料

• GitHub 仓库
• 官方文档
• 示例代码