SpringAI写第一个Agent-把工单循环跑起来

Spring AI 写第一个 Agent:把工单循环跑起来

之前把工具调用讲成工单循环:模型写一张 JSON 工单,你的代码去跑腿,结果回填,模型接着说话。纸上谈兵到此为止。这篇用 Spring AI 把这个循环真正跑起来:一个查天气的工具,一次真实的调用,工单的报文全程可见。写完你手里会有一个能跑的 agent,以及看懂所有 agent 文档的底气。

先搭台子

新建一个 Spring Boot 工程(3.x,Java 17+),添加依赖。Spring AI 从 1.0 起按模型供应商拆分模块,用哪家模型就加哪家的 starter,下面以 OpenAI 兼容接口为例(版本口径:Spring AI 2.0.1,核验于 2026-10-25,动手前请对照官方快速开始页)。

xml 复制代码
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

配置就两行,模型的地址和密钥。

yaml 复制代码
spring:
  ai:
    openai:
      api-key: ${AI_API_KEY}
      base-url: https://api.example.com/v1   # 用哪家填哪家

工具就是一个带注解的方法

工单哲学在 Spring AI 里的落点出奇地朴素:工具就是一个普通 Bean 里的普通方法,加一个 @Tool 注解,方法签名就是工单的参数表。文档确认的包路径是 org.springframework.ai.tool.annotation.Tool。

java 复制代码
@Component
public class WeatherTools {

    @Tool(description = "查询指定城市的当前天气")
    public String getWeather(@ToolParam("城市名") String city) {
        // 真实场景在这里发 HTTP,这里返回模拟数据
        return city + ",晴,25 度";
    }
}

方法名和参数名会被翻译成工单里的工具名和参数名,description 会被翻译成给模型看的说明书。你写的还是 Java,模型看到的是一张接口文档。
#mermaid-svg-EK2dW4ggm9yZxrWK{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-EK2dW4ggm9yZxrWK .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-EK2dW4ggm9yZxrWK .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-EK2dW4ggm9yZxrWK .error-icon{fill:#552222;}#mermaid-svg-EK2dW4ggm9yZxrWK .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-EK2dW4ggm9yZxrWK .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-EK2dW4ggm9yZxrWK .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-EK2dW4ggm9yZxrWK .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-EK2dW4ggm9yZxrWK .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-EK2dW4ggm9yZxrWK .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-EK2dW4ggm9yZxrWK .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-EK2dW4ggm9yZxrWK .marker{fill:#333333;stroke:#333333;}#mermaid-svg-EK2dW4ggm9yZxrWK .marker.cross{stroke:#333333;}#mermaid-svg-EK2dW4ggm9yZxrWK svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-EK2dW4ggm9yZxrWK p{margin:0;}#mermaid-svg-EK2dW4ggm9yZxrWK .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-EK2dW4ggm9yZxrWK .cluster-label text{fill:#333;}#mermaid-svg-EK2dW4ggm9yZxrWK .cluster-label span{color:#333;}#mermaid-svg-EK2dW4ggm9yZxrWK .cluster-label span p{background-color:transparent;}#mermaid-svg-EK2dW4ggm9yZxrWK .label text,#mermaid-svg-EK2dW4ggm9yZxrWK span{fill:#333;color:#333;}#mermaid-svg-EK2dW4ggm9yZxrWK .node rect,#mermaid-svg-EK2dW4ggm9yZxrWK .node circle,#mermaid-svg-EK2dW4ggm9yZxrWK .node ellipse,#mermaid-svg-EK2dW4ggm9yZxrWK .node polygon,#mermaid-svg-EK2dW4ggm9yZxrWK .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-EK2dW4ggm9yZxrWK .rough-node .label text,#mermaid-svg-EK2dW4ggm9yZxrWK .node .label text,#mermaid-svg-EK2dW4ggm9yZxrWK .image-shape .label,#mermaid-svg-EK2dW4ggm9yZxrWK .icon-shape .label{text-anchor:middle;}#mermaid-svg-EK2dW4ggm9yZxrWK .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-EK2dW4ggm9yZxrWK .rough-node .label,#mermaid-svg-EK2dW4ggm9yZxrWK .node .label,#mermaid-svg-EK2dW4ggm9yZxrWK .image-shape .label,#mermaid-svg-EK2dW4ggm9yZxrWK .icon-shape .label{text-align:center;}#mermaid-svg-EK2dW4ggm9yZxrWK .node.clickable{cursor:pointer;}#mermaid-svg-EK2dW4ggm9yZxrWK .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-EK2dW4ggm9yZxrWK .arrowheadPath{fill:#333333;}#mermaid-svg-EK2dW4ggm9yZxrWK .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-EK2dW4ggm9yZxrWK .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-EK2dW4ggm9yZxrWK .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-EK2dW4ggm9yZxrWK .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-EK2dW4ggm9yZxrWK .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-EK2dW4ggm9yZxrWK .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-EK2dW4ggm9yZxrWK .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-EK2dW4ggm9yZxrWK .cluster text{fill:#333;}#mermaid-svg-EK2dW4ggm9yZxrWK .cluster span{color:#333;}#mermaid-svg-EK2dW4ggm9yZxrWK div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-EK2dW4ggm9yZxrWK .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-EK2dW4ggm9yZxrWK rect.text{fill:none;stroke-width:0;}#mermaid-svg-EK2dW4ggm9yZxrWK .icon-shape,#mermaid-svg-EK2dW4ggm9yZxrWK .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-EK2dW4ggm9yZxrWK .icon-shape p,#mermaid-svg-EK2dW4ggm9yZxrWK .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-EK2dW4ggm9yZxrWK .icon-shape .label rect,#mermaid-svg-EK2dW4ggm9yZxrWK .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-EK2dW4ggm9yZxrWK .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-EK2dW4ggm9yZxrWK .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-EK2dW4ggm9yZxrWK :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} tool_use 工单

name= get_weather

input= city: 北京
模型
Spring AI 解析
调用 @Tool 方法

getWeather(北京)
结果回填 tool_result

这张图和之前画的工单循环是同一张,只是每个格子都有了 Spring 的落地。

把模型接进来

ChatClient 是发请求的入口,.tools(...) 把你的 Bean 注册成工具,剩下的循环它替你转。

java 复制代码
@Component
public class AgentRunner implements ApplicationRunner {

    private final ChatClient chatClient;
    private final WeatherTools weatherTools;

    public AgentRunner(ChatClient.Builder builder, WeatherTools weatherTools) {
        this.chatClient = builder.build();
        this.weatherTools = weatherTools;
    }

    @Override
    public void run(ApplicationArguments args) {
        String answer = chatClient.prompt()
                .user("北京今天多少度?")
                .tools(weatherTools)
                .call()
                .content();
        System.out.println("最终回答:" + answer);
    }
}

第一次跑通时,最值得做的事是把日志级别调高,看清这一来一回的报文。模型返回的 tool_use、你的方法被执行、结果被回填,整个过程在日志里一目了然,工单循环从图变成了你机器上的事实。

亲手跑

上面三段加上启动类就是一个完整工程,运行 mvn spring-boot:run 就能看结果。想先不碰真模型也行,把 API Key 随便填,看框架在发请求前打出的报文,工具的 JSON Schema 一样能见到,那正是模型看到的「接口文档」。

跑通之后有两个顺手的实验。把 question 换成「北京和上海今天多少度」,看模型会不会一次写两张工单,这是并行工单的入口。把 getWeather 改成真的抛异常,看错误怎么被包进 tool_result 回给模型,这是失败路径的入口。

记住一句话:@Tool 注解标记的不是魔法,是一张给模型看的接口文档,执行永远在你手里。

适用边界

这一篇管单工具、单轮的最小闭环。多轮对话的记忆、工具的权限边界,以及流式输出的接法,是接下来的篇目。Spring AI 各版本的注解包路径和配置前缀会微调,本文按 2026-10-25 的 2.x 口径整理,动手前对一下官方文档。跑通这个 demo 之后,你对所有 agent 框架的文档都有了阅读坐标,剩下的只是换语法。

相关推荐
Resean022317 分钟前
Spring 源码分析(二)配置类的解析与扫描
java·后端·spring
小毛球.37 分钟前
第 3 篇:IDEA 最新版下载与完整安装教程(Mac)
java·macos·intellij-idea·idea
学无止境小袁同学2 小时前
LangGraph 深度指南
语言模型·框架·agent·并发·上下文·langgraph·长期记忆
Misnearch2 小时前
ScheduledExecutorService
java·线程池
Cosolar2 小时前
2026 年 Java AI Agent 生态全景盘点:50+ Java 开源项目的分类、实测与选型判断
人工智能·架构·agent
ashiho3 小时前
【LeetCode hot 100】3. 无重复字符的最长子串 (三种解法)
java·数据结构·后端·算法·leetcode·滑动窗口
T_Wizard3 小时前
AI 回复为什么要转圈 3 秒才「啪」一下全出来?把流式输出拆开看,顺便踩了 6 个坑
java·ai编程
CoderYanger4 小时前
Java EE 进阶:9.MyBatis 操作数据库(进阶)(第二弹)
java·数据库·面试·职场和发展·java-ee·tomcat·mybatis
张一凡934 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
qinglongcn4 小时前
怎么让 200 轮的长任务不崩——三层保全策略
agent·ai编程