Spring AI 集成 Anthropic Skills：Agent 工具调用实践

代码评审 Skill 同理：调用 code-review-skill/scripts/... 并返回报告文本即可。

2. 把 Tool 注册成 Spring AI Function

Spring AI 推荐通过 @Bean Function<Req,Resp> 或 @Tool 暴露工具，让 ChatClient / ChatModel 知道有哪些函数可用。

package com.example.ai.config;

import com.example.ai.tools.DataAnalysisSkillTool;
import com.example.ai.tools.CodeReviewSkillTool;
import com.example.ai.tools.dto.*;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.function.Function;

@Configuration(proxyBeanMethods = false)
public class SkillsConfig {
    @Bean
    public Function<DataAnalysisSkillRequest, DataAnalysisSkillResponse> internalDataAnalysis(DataAnalysisSkillTool tool) {
        return tool::run; // 函数名 internalDataAnalysis = Skill 名
    }

    @Bean
    public Function<CodeReviewSkillRequest, CodeReviewSkillResponse> codeReviewAssistant(CodeReviewSkillTool tool) {
        return tool::run;
    }
}

在 Spring AI 里，这两个 Bean 名（internalDataAnalysis / codeReviewAssistant）就是 LLM 能看到的工具名，你可以在 prompt 中让模型了解它们的用途，也可以只靠 JSON Schema 自动推断。

3. ChatClient：让 Agent 自己选用 Skill

3.1 定义一个「数据分析 Agent」服务

package com.example.ai.agent;

import com.example.ai.tools.dto.DataAnalysisSkillRequest;
import com.example.ai.tools.dto.DataAnalysisSkillResponse;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;

@Service
public class DataAnalysisAgentService {
    private final ChatClient chatClient;

    public DataAnalysisAgentService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    public String analyze(String userQuestion, String constraints) {
        var sysPrompt = """
            你是公司内部的数据分析助手。
            你可以使用名为 internalDataAnalysis 的工具，它会基于数据仓库执行查询和分析，并返回一份结构化的中文报告草稿。
            当用户的问题涉及具体的数据指标、时间范围、渠道/地区对比时，应优先调用该工具，而不是凭空猜测。
            """;
        // 这里不直接 new DataAnalysisSkillRequest，而是让 LLM 自己构造参数并调用工具
        return chatClient
            .prompt()
            .system(sysPrompt)
            .user(userSpec -> userSpec
                .text("用户问题：{q}\n约束条件（可为空）：{c}")
                .param("q", userQuestion)
                .param("c", constraints == null ? "" : constraints))
            .functions("internalDataAnalysis")
            .call()
            .content(); // 最终答案：模型在工具结果基础上生成的回答
    }
}

模型流程示意：

1. 收到用户问题 → 判断需要具体数据 → 选择调用 internalDataAnalysis。
2. 构造 DataAnalysisSkillRequest 的 JSON 入参。
3. Spring AI 执行 Java Function → 调 Python Skill 脚本 → 拿到报告文本。
4. Spring AI 把报告作为新一轮对话上下文喂回模型。
5. 模型基于报告，生成最终面向业务同学的自然语言回答。

3.2 控制器层简单暴露 HTTP 接口

package com.example.ai.web;

import com.example.ai.agent.DataAnalysisAgentService;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/analysis")
public class DataAnalysisController {
    private final DataAnalysisAgentService agentService;

    public DataAnalysisController(DataAnalysisAgentService agentService) {
        this.agentService = agentService;
    }

    @PostMapping
    public String analyze(@RequestParam("question") String question,
                          @RequestParam(value = "constraints", required = false) String constraints) {
        return agentService.analyze(question, constraints);
    }
}

4. Python 侧：包装 Skill 为统一入口（可选但推荐）

上面的 Java Tool 调用了一个假想的 run_analysis_skill.py，它可以作为 Skill 的统一入口，内部再去调用 run_query.py 和 clean_and_aggregate.py，并基于结果拼出完整报告文本（按照你在 SKILL.md 中定义的结构）。

伪代码示例：

# internal-data-analysis-skill/scripts/run_analysis_skill.py
import argparse
import textwrap

# 这里导入或复用 run_query.py / clean_and_aggregate.py 中的逻辑
def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--request", required=True)
    parser.add_argument("--constraints", default="")
    args = parser.parse_args()

    # 1. 解析 request / constraints -> 决定查询模板
    # 2. 生成 SQL，调用 run_query.py 获得 result.csv
    # 3. 调用 clean_and_aggregate.py 做清洗与聚合
    # 4. 按 SKILL.md 中的报告结构拼出一份文本，print 到 stdout
    report = textwrap.dedent(f"""
        内部数据分析报告（示例）
        一、分析诉求 - {args.request}
        - 约束条件：{args.constraints or "无"}
        二、关键指标（示例说明）
        - ...
        三、主要发现
        - ...
        四、风险与局限
        - ...
        五、后续建议
        - ...
    """).strip()
    print(report)

if __name__ == "__main__":
    main()

这样有三个好处：

• Java 只关心「给脚本字符串 → 拿报告字符串」，无需理解 SQL 细节。
• Skill 的演进主要在 Python + SKILL.md 里完成，不影响 Java 侧接口。
• 以后如果换成 MCP / 远程服务，也可以保持 Java 侧函数签名不变，只调整内部实现。

5. 同理挂载其它 Skill（如代码评审）

代码评审 Skill 的集成方式完全相同，只是：

• DTO 换成 CodeReviewSkillRequest/Response；
• Tool 内部调用的是 code-review-skill/scripts/...；
• Agent 的 system prompt 改成「你是代码评审助手，可以调用 codeReviewAssistant 工具……」。

Spring AI 会自动把两个工具的 Schema 一起发给模型，这样一个更通用的「工程生产力 Agent」就可以根据用户问题自动选择是「查数据」还是「审代码」了。

下一步可以一起细化两点：

• 根据当前用的具体模型（OpenAI、Anthropic 代理、Mistral 等），调整 application.yml 中 Spring AI 的模型配置和函数调用选项。
• 把「Skill 元数据（目录扫描） + MCP」结合起来，让 Spring AI 在运行时动态发现新的 Skill，而不仅仅是写死在配置中的两个函数。