Declarative API#declarative-api这个Declarative API声明式 API确实和 Agent、Workflow 很有关系而且它对Spring Boot / Java 开发者来说是一个非常友好的设计思路。你可以先记住一句最核心的话Declarative API 的作用是让你用“声明”的方式描述 Agent/Workflow而不是自己手动写很多底层拼装代码。说白了它的重点不是“增加新能力”而是让你更容易定义 AI Agent 的行为、依赖、工作流和调用方式。一、先用最通俗的话解释什么叫 Declarative API1什么叫“声明式”“声明式”可以理解成你告诉框架“我要什么、规则是什么”至于具体怎么执行框架帮你处理。而“命令式”是你一步一步手写流程告诉程序先干嘛再干嘛。2Spring Boot 开发者怎么理解你其实已经天天在用“声明式”的东西了。比如Spring MVCGetMapping(/users)publicListUserlistUsers(){...}你只是声明这是个 GET 接口路径是/users至于怎么接 HTTP 请求怎么路由怎么参数绑定都是 Spring 帮你处理的。Spring 事务TransactionalpublicvoidcreateOrder(){...}你只是声明这个方法需要事务至于何时开启事务何时提交/回滚框架帮你做。FeignClientFeignClient(nameorder-service)publicinterfaceOrderClient{GetMapping(/orders/{id})OrdergetById(PathVariableLongid);}你只是声明了我要调用哪个服务调哪个接口至于 HTTP 请求怎么发Spring Cloud 帮你处理。3那 Agent 的 Declarative API 类似什么非常像Agent 版的 Feign Spring 注解风格接口定义。也就是说你不一定非要自己new 模型拼 prompt处理 tool 调用管执行链手写很多 glue code你可以通过声明式方式直接定义这个 Agent 是干什么的它用什么模型它有哪些 Tool它怎么参与 workflow它的输入输出是什么二、Declarative API 是干什么的核心作用它的核心目标是把 Agent 的定义从“手动编码组装”变成“接口/注解式声明”。这样做的好处是代码更简洁结构更清晰更接近 Java/Spring 开发习惯更容易维护更方便和 workflow 组合三、为什么会有 Declarative API因为如果全手写会比较麻烦。你可能得自己做很多事情组装 prompt定义 system message绑定 chat model注册 tools写 memory处理返回格式编排调用逻辑对于简单 Demo 还能接受但如果你开始做多个 Agent多个 workflow多种工具多种上下文多种模型选择手写方式会很快变乱。所以 Declarative API 的意义就是把“怎么定义 Agent”这件事标准化。四、它和 workflow 是什么关系你说得对它看起来像是配合 workflow 使用的这个理解是对的。因为 workflow 本质上是在讲多个步骤怎么组织多个 Agent 怎么协作什么时候调用哪个 Agent结果怎么传递那如果每个 Agent 都还要你自己低层组装就会很重。所以 Declarative API 提供的是一种更轻量、更统一的方式去定义 workflow 里的节点/角色。你可以把它理解成Workflow 流程图Declarative API 流程图里每个节点的定义方式五、你可以怎么理解声明式 vs 命令式1命令式写法你自己手工做ChatModelmodel...Tooltool...Memorymemory...Stringprompt请分析订单问题;Stringresponsemodel.chat(prompt);如果再复杂一点还要自己控制调哪个 Tool哪个步骤执行参数怎么拼结果怎么传这种就是命令式。2声明式写法你只定义一个接口或者一个 Agent 角色interfaceOrderAssistant{StringanalyzeOrder(StringuserMessage);}然后通过注解/配置告诉框架这是一个 Agent它的 system prompt 是什么它可以调用哪些 Tools它怎么返回结果至于底层调用逻辑框架帮你处理。这就是声明式。六、Declarative API 具体有什么作用下面我按“作用点”给你拆开讲。1. 定义 Agent 角色更简单你可以更自然地声明这个 Agent 是订单助手那个 Agent 是退款助手另一个 Agent 是报告分析助手不需要每个都自己手动写初始化和拼装。2. 更容易做多 Agent 协作如果 workflow 里有多个 Agent分类 Agent分析 Agent总结 Agent声明式 API 可以让这些 Agent 都像普通 Java 接口一样组织起来。这会让整体结构更清晰。3. 更适合和 Spring 风格整合Java 开发者很习惯这种模式定义接口用注解声明能力框架生成实现Declarative API 就是这种体验。4. 降低样板代码不然很多代码都在干重复的事情构造模型请求绑定 tool做输入输出映射声明式 API 可以减少这类代码。5. 让 workflow 节点更像“业务组件”比如你在工作流里写Step1分类Step2查询订单Step3生成说明如果每个步骤背后都能抽象成一个声明式 Agent 接口那结构就会很清楚。七、通俗案例电商智能客服我用你最容易代入的场景讲。场景你要做一个电商客服 AI有这些能力识别用户问题类型查询订单状态生成客服回复如果用 workflow 表示用户问题 ↓ 分类 Agent ↓ 订单查询 Agent / 退款 Agent / 投诉 Agent ↓ 回复生成 Agent如果不用声明式 API你可能要写很多手动组装代码new 各种模型配 prompt配 Tool写参数传递做结果封装这样代码比较散。如果用声明式 API你可以把每个 Agent 当成一个“声明出来的业务组件”分类 Agent负责识别意图订单 Agent负责处理订单相关问题回复 Agent负责把结果整理成人话这样在 workflow 里你就只是在“调用组件”。这会特别像你平时写UserServiceOrderServicePaymentService只不过这里变成IntentClassifierAgentOrderSupportAgentReplyWriterAgent八、Spring Boot 视角下Declarative API 怎么理解最合适我建议你这样理解Declarative API 用 Java 接口/注解风格定义 Agent就像定义 FeignClient、Mapper、Controller 一样。它不是让你去“手动操作模型底层”而是让你定义契约声明角色声明工具依赖声明行为入口然后由框架来帮你创建代理对象、执行 AI 调用。九、为什么说它适合 workflow因为 workflow 里往往有很多“节点”。例如一个 Sequential workflow1. 提取订单号 2. 查询订单 3. 生成回复如果每个节点都是你手工拼 prompt、调模型、绑工具workflow 就会很乱。但如果每个节点都能声明成一个明确的 Agent/组件OrderIdExtractorAgentOrderQueryAgentReplyFormatterAgentworkflow 层就只关心调谁顺序是什么结果怎么流转而不用关心每个 Agent 的底层细节。所以你说“好像是配合 workflow 使用的”本质上是因为Declarative API 让 workflow 中的每个 AI 节点更容易定义和复用。十、它的价值不在“更强”而在“更好组织代码”这个点很重要。Declarative API 不是说模型更聪明了Tool 更多了workflow 更多了它没有改变能力边界。它改变的是你写这些能力的方式。也就是从很多手工 glue code变成更像 Spring 风格的声明式开发十一、你可以怎么把它映射到项目结构里举个非常简单的结构controller/ AiController.java agent/ IntentClassifierAgent.java OrderAssistantAgent.java RefundAssistantAgent.java ReplyFormatterAgent.java workflow/ CustomerSupportWorkflow.java tool/ OrderTools.java RefundTools.java service/ OrderService.java RefundService.java这里tool你已有的工具能力agent通过声明式 API 定义的 Agentworkflow负责编排这些 Agent 的调用顺序和分支你会发现这和 Spring Boot 的分层非常自然。十二、一个简单流程图理解用户问我的订单怎么还没发货可能 workflow 是这样[IntentClassifierAgent] ↓ 判断为 ORDER_QUERY [OrderAssistantAgent] ↓ 调用 orderTool 查询订单状态 [ReplyFormatterAgent] ↓ 生成客服语气的最终回复如果这些 Agent 都是声明式定义的那 workflow 层写起来就很像StringintentintentClassifierAgent.classify(userMessage);OrderResultresultorderAssistantAgent.handle(userMessage);StringreplyreplyFormatterAgent.format(result);这就很像正常 Java 项目里的业务组件调用。十三、你在学习时最应该抓住什么我建议你重点抓住下面 4 点1. Declarative API 不是新能力是新写法它不改变 Agent 能做什么它改变的是你“怎么定义 Agent”。2. 它很适合 Java/Spring Boot 开发者因为它符合你熟悉的开发方式接口注解代理声明式定义3. 它特别适合多 Agent / workflow 场景如果只有一个非常简单的 Agent手写也能做但当 Agent 变多、流程变复杂时声明式 API 的价值会越来越明显。4. 它能让 workflow 更清晰workflow 负责流程编排declarative API 负责定义流程里的 AI 节点。十四、你可以把它和这些 Spring 概念类比为了让你更好记我给你几个类比像Controller声明一个接口入口像FeignClient声明一个远程能力调用接口像Mapper声明一个数据访问接口像Transactional声明一个方法该怎么被框架处理所以你可以把 Declarative API 看成Agent/Workflow 领域里的“Spring 风格声明式编程”。十五、它到底适合哪些场景尤其适合这些情况1多个 Agent比如分类 Agent审核 Agent报告 Agent2workflow 较多比如顺序流程路由流程条件流程3希望代码结构清晰尤其团队协作时更重要。4希望 Agent 可以复用声明式定义的 Agent往往更容易在不同 workflow 中复用。十六、用一句话总结这个 Declarative APIDeclarative API 就是用更像 Spring 的方式去定义 Agent把复杂的底层 AI 调用细节隐藏起来让你更专注于“这个 Agent 是干什么的”和“它在 workflow 里怎么协作”。十七、最后给你一个超短记忆版你可以直接背这个ToolAgent 能调用的后端能力Workflow多个步骤怎么组织Declarative API这些 Agent/步骤怎么更优雅地定义出来所以它确实和 workflow 很配套。