大家好，我是直奔標杆！专注于分享企业级AI落地实战经验，今天给大家带来一篇干货满满的实战教程——从0到1搭建基于Java+Spring AI+Skill架构的金融智能体，全程干货无废话，包含完整架构图、接口定义、核心代码、启动流程，可直接复用为项目、毕设或面试作品，新手也能跟着上手，看完必有所获～

导读：在大模型爆发的当下，90%的开发者还停留在“调用API实现简单聊天”的浅层阶段。但真正能落地到金融、医疗、政企等核心生产环境的AI系统，必须满足可计算、可审计、可扩展、可管控四大核心要求。今天就带大家从头到尾，完整实现一套AI智能体+Skill双层架构+Java/Python混合计算+金融级审计的生产可用系统，一起跳出“聊天demo”，迈向企业级AI落地！

一、项目定位：为什么一定要用Agent+Skill架构？

1.1 传统大模型应用的致命缺陷（金融场景必避坑）

在金融场景中，单纯调用大模型接口，根本无法满足生产需求，主要有四大致命问题，也是很多开发者落地失败的关键：

1. 计算不准：DCF估值、VaR风险价值、波动率等金融核心计算，要求绝对精确，而大模型的“幻觉”问题会直接导致计算失真，无法用于实际业务；

2. 不可管控：技能无法插拔、无法覆盖更新，也没有完善的审计机制，不符合金融行业的管控要求；

3. 性能拉胯：全量加载Prompt，容易出现Token爆炸、系统启动缓慢的问题，影响用户体验；

4. 不合规：缺乏完整的日志记录、AI自动质检和风险校验，无法通过金融监管审核，根本无法进入核心业务环节。

正是这些问题，让很多大模型应用停留在demo阶段，无法真正落地到金融生产环境。

1.2 解决方案：AI智能体 + Skill工具链（企业级落地核心）

结合金融场景的特殊性，我们设计了一套清晰易懂、可落地的架构方案，核心逻辑一句话讲明白：

LLM = 大脑：只负责理解用户需求、逻辑推理、决策下一步操作，不做具体计算和执行；

Skill = 专业能力包：封装金融领域知识、标准化执行流程、指令规范，相当于给AI大脑配备“专业知识库”；

Tool = 执行手脚：负责精确计算、脚本调用、外部接口访问，解决大模型计算不准的问题；

Agent = 指挥官：统一管理Skill、调度Tool，同时负责会话管理、日志记录，确保系统可管控、可审计。

简单总结：LLM负责想，Skill负责专业，Tool负责干，Agent负责管，各司其职、协同发力，完美解决传统大模型应用的痛点。

1.3 项目核心亮点（落地优势，值得收藏）

这套系统之所以能作为企业级落地标杆，核心亮点如下，也是大家实际项目中最需要的功能：

• 双层Skill存储架构：内置只读（基础技能，保障安全）+ 外部可写（灵活扩展，适配业务迭代），兼顾安全与合规；

• Skill三阶段加载：发现→激活→执行，避免全量加载，节省Token、提升系统启动速度；

• Agent可插拔设计：支持动态挂载技能，一键切换不同类型的金融顾问，适配多场景需求；

• Java+Python混合计算：发挥Java的稳定性优势，借助Python的计算强项，兼顾系统可靠与计算精准；

• 全链路审计：完整记录对话日志，搭配AI自动质检，完全满足金融监管要求；

• SSE流式输出：和ChatGPT一样丝滑的交互体验，避免用户长时间等待；

• 多模态支持：图片、音频、文本统一处理，适配更多金融交互场景；

• DDD领域驱动架构：模块解耦，可维护、可扩展、可替换，便于后期迭代升级。

二、整体架构设计（图文解析，一看就懂）

2.1 项目模块结构图（Maven多模块，规范清晰）

项目采用Maven多模块设计，分层清晰、依赖明确，便于团队协作和后期维护，模块结构如下（建议收藏，实际项目可直接复用）：

fin-ai-agent（父工程）

├─ fin-ai-agent-domain 领域模型层（核心实体：Skill、AuditLog，纯业务无依赖）

├─ fin-ai-agent-framework 框架层（定义Agent、SkillPackage核心接口，系统骨架）

├─ fin-ai-agent-infrastructure 基础设施层（Skill加载、Python执行、仓储实现，支撑核心功能）

├─ fin-ai-agent-agents 智能体层（具体智能体实现，如金融顾问Agent）

└─ fin-ai-agent-api 接口层（提供HTTP、流式、多模态接口，对外提供服务）

依赖方向：api → agents → infrastructure → framework → domain（分层解耦，降低依赖耦合度）

2.2 运行流程图（两步理清，新手也能看懂）

启动流程（简单5步，系统快速启动）

1. 启动SpringBoot项目；

2. 自动扫描@Component、@Service等组件，完成Bean初始化；

3. 并行加载双层Skill（内置+外部），完成技能初始化；

4. 创建Agent实例，注入对应的Skill包，注册到AgentRegistry（智能体注册中心）；

5. 启动Web服务，等待前端请求。

对话流程（核心流程，理解系统运转逻辑）

1. 前端发起HTTP请求，访问接口：/api/chat/stream；

2. 根据请求参数中的agentName，匹配对应的Agent；

3. 准备上下文信息（会话ID、Tool工具集）；

4. Agent调用LLM进行思考，分析用户需求；

5. LLM根据需求，选择合适的Skill和Tool；

6. 调用Python脚本执行精确计算（如DCF、VaR）；

7. 通过SSE流式返回结果，提升用户体验；

8. 记录全链路审计日志，完成AI自动质检，确保合规。

三、领域层设计（Domain）—— 架构的灵魂，纯业务无侵入

领域层是整个系统最稳定的部分，只关注业务实体，不依赖任何框架和技术，便于后期扩展和替换。核心实体类如下，可直接复制到项目中使用：

3.1 Skill实体类（技能核心实体）

@Data
@Builder
public class Skill {
    private String name;          // 技能唯一标识（不可重复）
    private String description;   // 技能描述（说明技能用途）
    private String instructions;  // 执行指令（技能的具体执行逻辑）
    private String fullContent;   // 完整SKILL.md内容（存储技能完整信息）
}

3.2 审计日志实体（合规核心实体）

@Data
@Builder
public class AuditLog {
    private String sessionId;       // 会话ID（关联单次对话）
    private String skillName;       // 调用的技能名称
    private String userMessage;     // 用户提问内容
    private String agentResponse;   // AI回答内容
    private String evaluation;      // AI质检结果（合规校验）
    private LocalDateTime timestamp;// 操作时间戳
    private long durationMs;        // 接口耗时（性能监控）
}

设计意义：纯业务逻辑封装，脱离框架依赖，即使后期替换框架，领域层代码也无需修改，保证系统的稳定性和可维护性。

四、框架层设计（Framework）—— 系统骨架，定义核心标准

框架层负责定义系统的核心接口和模板类，统一规范Agent和Skill的实现标准，让后续开发更规范、更高效。

4.1 SkillPackage接口（技能包标准）

public interface SkillPackage {
    String getName();              // 获取技能包名称
    String getDescription();       // 获取技能包描述
    String getContent();           // 获取技能包内容
    boolean isAvailable();         // 判断技能包是否可用
    Map<String, Object> getProperties(); // 获取技能包配置属性
}

4.2 SkillPackage实现类（接口具体实现）

@Data
@Builder
public class SkillPackageImpl implements SkillPackage {
    private String name;
    private String description;
    private String content;
    private boolean available;
    private Map<String, Object> properties;
}

4.3 Agent核心接口（智能体标准）

public interface Agent {
    String getId();                // 获取智能体ID
    String getName();              // 获取智能体名称
    List<SkillPackage> getSkillPackages(); // 获取智能体拥有的技能包
    void addSkillPackage(SkillPackage skillPackage); // 新增技能包
    Flux<String> processStream(String message, Map<String, Object> context); // 流式处理对话
    boolean isAvailable();         // 判断智能体是否可用
}

4.4 BaseAgent模板类（最核心代码，可直接复用）

BaseAgent实现了Agent接口的通用方法，定义了智能体的基础逻辑，后续所有智能体（如金融顾问）都可继承此类，减少重复开发。

@Slf4j
@Getter
@Setter
public abstract class BaseAgent implements Agent {
    protected String id;
    protected String name;
    protected String description;
    protected List&lt;SkillPackage&gt; skillPackages = new ArrayList<>();
    protected ChatClient chatClientWithSkills;
    protected File skillsDirectory;
    
    public BaseAgent(String name, String desc, ChatClient chatClient, ChatClient.Builder builder) {
        this.id = UUID.randomUUID().toString();
        this.name = name;
        this.description = desc;
        // 初始化带技能的ChatClient
        if (builder != null) {
            this.chatClientWithSkills = builder.defaultSystem(desc).build();
        } else {
            this.chatClientWithSkills = chatClient;
        }
    }
    
    // 设置技能目录，自动绑定SkillsTool
    public void setSkillsDirectory(File skillsDirectory) {
        this.skillsDirectory = skillsDirectory;
        try {
            var skillsTool = SkillsTool.builder()
                .addSkillsDirectory(skillsDirectory.getAbsolutePath())
                .build();
            // 重建带工具的客户端
            this.chatClientWithSkills = chatClientBuilder
                .defaultSystem(description)
                .defaultToolCallbacks(skillsTool)
                .build();
        } catch (Exception e) {
            log.error("初始化SkillsTool失败", e);
        }
    }
    
    // 流式处理对话（核心方法）
    @Override
    public Flux<String> processStream(String message, Map<String, Object> context) {
        if (!isAvailable()) {
            return Flux.just("当前智能体不可用");
        }
        String sessionId = (String) context.get("sessionId");
        Object tools = context.get("tools");
        var prompt = chatClientWithSkills.prompt().user(message);
        if (tools != null) {
            prompt.tools(tools);
        }
        if (sessionId != null) {
            prompt.advisors(a -> a.param(ChatMemory.CONVERSATION_ID, sessionId));
        }
        return prompt.stream().content();
    }
}

五、基础设施层（Infrastructure）—— 核心支撑，实现落地能力

基础设施层是系统的“后勤保障”，负责Skill加载、Python脚本执行、审计日志记录等核心支撑功能，解决系统落地的技术难题。

5.1 Skill解析器（SKILL.md → Java对象）

将编写的SKILL.md文件（技能描述文件）解析为Java中的Skill对象，便于系统识别和调用，核心代码如下：

@Slf4j
public class SkillParser {
    private static final Pattern PATTERN = Pattern.compile(
        "^---\\s*[\\r\\n]+name:\\s*(.+?)\\s*[\\r\\n]+description:\\s*(.+?)\\s*[\\r\\n]+---\\s*[\\r\\n]+(.*)$",
        Pattern.DOTALL
    );
    
    public static Skill parse(String content) {
        if (content == null || content.isBlank()) return null;
        Matcher matcher = PATTERN.matcher(content);
        if (matcher.find()) {
            return Skill.builder()
                .name(matcher.group(1).trim())
                .description(matcher.group(2).trim())
                .instructions(matcher.group(3).trim())
                .fullContent(content)
                .build();
        }
        log.warn("技能解析失败，请检查SKILL.md格式");
        return null;
    }
}

5.2 双层Skill加载器（核心功能，安全合规）

负责加载内置只读技能和外部可写技能，确保技能加载的安全性和灵活性，启动时自动加载，核心代码如下：

@Service
@Slf4j
public class SkillLoaderService {
    private final FileSystemSkillRepository repository;
    
    @PostConstruct
    public void loadAllSkills() {
        // 1. 加载内置技能（只读，不可修改，保障基础功能安全）
        int classpathCount = repository.loadFromPath("classpath:skills/**/SKILL.md");
        // 2. 加载外部技能（可写，可扩展，适配业务迭代）
        File dynamicDir = new File("data/skills");
        int fileCount = 0;
        if (dynamicDir.exists()) {
            fileCount = repository.loadFromPath("file:data/skills/**/SKILL.md");
        }
        log.info("技能加载完成：内置{}个，外部{}个，共{}个技能", classpathCount, fileCount, classpathCount + fileCount);
    }
}

5.3 Python脚本执行器（Java调Python，解决计算难题）

金融计算（如DCF、VaR）用Python更高效，因此封装了Python脚本执行器，实现Java调用Python脚本，核心代码如下：

@Component
@Slf4j
public class PythonScriptExecutor {
    private final String pythonCommand;
    
    public PythonScriptExecutor() {
        this.pythonCommand = detectPython(); // 自动检测Python环境
    }
    
    // 自动检测系统中的Python命令（兼容python3和python）
    private String detectPython() {
        if (testCommand("python3")) return "python3";
        if (testCommand("python")) return "python";
        log.warn("未检测到Python环境，请先安装Python");
        return null;
    }
    
    // 执行Python脚本，返回执行结果
    public ScriptResult execute(String skillPath, String scriptName, String... args) {
        Path script = Paths.get("skills", skillPath, "scripts", scriptName);
        List<String> command = new ArrayList<>();
        command.add(pythonCommand);
        command.add("-u"); // 实时输出日志
        command.add(script.toString());
        Collections.addAll(command, args);
        
        try {
            Process process = new ProcessBuilder(command)
                .redirectErrorStream(true)
                .start();
            String output = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
            int exitCode = process.waitFor();
            return exitCode == 0 ? ScriptResult.success(output) : ScriptResult.error(output);
        } catch (Exception e) {
            log.error("执行Python脚本失败", e);
            return ScriptResult.error(e.getMessage());
        }
    }
}

5.4 审计日志服务（AI自动质检，满足金融合规）

记录全链路对话日志，并调用AI自动质检，确保对话内容合规，满足金融监管要求，核心代码如下：

@Service
@Slf4j
public class AuditLogService {
    private final EvaluationRepository repository;
    private final ChatClient.Builder chatClientBuilder;
    private final SkillLoaderService skillLoaderService;
    
    // 记录日志并进行AI自动质检
    public void logAndEvaluate(AuditLog log) {
        // 调用critic-agent技能，自动评估对话合规性
        Skill critic = skillLoaderService.findByName("critic-agent").orElse(null);
        if (critic != null) {
            String eval = chatClientBuilder.build()
                .prompt()
                .system(critic.getFullContent())
                .user(String.format("用户：%s\nAI：%s", log.getUserMessage(), log.getAgentResponse()))
                .call()
                .content();
            log.setEvaluation(eval); // 设置质检结果
        }
        repository.save(log); // 保存审计日志
    }
}

六、智能体层（Agents）—— 金融顾问具体实现

基于BaseAgent模板类，实现具体的金融顾问智能体，注入对应的技能包，完成金融场景的业务适配，可直接复用：

@Component
@Slf4j
public class SuperFinancialAdvisorAgent extends BaseAgent {
    public SuperFinancialAdvisorAgent(
            ChatClient.Builder chatClientBuilder,
            ResourceLoader resourceLoader) {
        super(
            "全能金融顾问大师", // 智能体名称
            "我提供投资分析、风控计算、组合优化、技术指标分析等金融核心服务", // 智能体描述
            chatClientBuilder.build(),
            chatClientBuilder
        );
        try {
            // 加载金融顾问对应的技能目录
            Resource resource = resourceLoader.getResource("classpath:skills/super-financial-advisor");
            setSkillsDirectory(resource.getFile());
        } catch (Exception e) {
            log.error("金融顾问技能目录加载失败", e);
        }
    }
}

七、接口层（API）—— 流式对话接口，对外提供服务

封装HTTP接口，提供SSE流式输出，让前端能实现丝滑的对话体验，核心接口代码如下（可直接复制到项目中）：

@RestController
@RequestMapping("/api/chat")
@Slf4j
public class ChatController {
    private final AgentRegistry agentRegistry;
    private final FinancialTools financialTools;
    private final AuditLogService auditLogService;
    
    // 流式对话接口（核心接口）
    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public SseEmitter stream(
            @RequestParam String agentName, // 智能体名称
            @RequestParam String message,   // 用户提问
            @RequestParam(defaultValue = "default-session") String sessionId) { // 会话ID
        // 设置超时时间（3分钟）
        SseEmitter emitter = new SseEmitter(180000L);
        // 根据名称获取智能体
        Agent agent = agentRegistry.getAgentByName(agentName).orElse(null);
        // 准备上下文信息
        Map<String, Object> context = new HashMap<>();
        context.put("sessionId", sessionId);
        context.put("tools", financialTools);
        
        // 流式处理对话并返回结果
        agent.processStream(message, context).subscribe(
            chunk -> {
                try {
                    emitter.send(SseEmitter.event().name("content").data(Map.of("chunk", chunk)));
                } catch (IOException e) {
                    log.error("流式返回失败", e);
                }
            },
            error -> emitter.completeWithError(error),
            () -> {
                try {
                    emitter.send(SseEmitter.event().name("done"));
                } catch (IOException e) {
                    log.error("流式结束通知失败", e);
                }
                emitter.complete();
            }
        );
        return emitter;
    }
}

八、四大金融Tool封装（核心业务工具，直接复用）

封装金融场景最常用的四大工具，结合Python脚本执行，实现精确计算，满足金融业务需求，核心代码如下：

@Component
@Slf4j
public class FinancialTools {
    private final PythonScriptExecutor executor;
    
    // DCF现金流折现估值工具（参数：现金流、折现率、终端增长率、流通股数）
    @Tool(description = "DCF现金流折现估值，参数：cashFlows、discountRate、terminalGrowth、sharesOutstanding")
    public String calculateDcf(double[] cashFlows, double discountRate, double terminalGrowth, double sharesOutstanding) {
        return executor.executeDcfCalculator(cashFlows, discountRate, terminalGrowth, sharesOutstanding).getOutput();
    }
    
    // 技术指标计算工具（MA、RSI、MACD）
    @Tool(description = "计算技术指标 MA、RSI、MACD，参数：股票价格数组")
    public String calculateTechnicalIndicators(double[] prices) {
        return executor.executeTechnicalIndicators(prices).getOutput();
    }
    
    // VaR风险价值计算工具（投资组合风险评估）
    @Tool(description = "计算投资组合VaR风险价值，参数：组合价值、平均收益率、标准差、置信水平")
    public String calculateVar(double portfolioValue, double meanReturn, double stdDev, double confidenceLevel) {
        return executor.executeVarCalculator(portfolioValue, meanReturn, stdDev, confidenceLevel).getOutput();
    }
    
    // 马科维茨投资组合优化工具（资产配置优化）
    @Tool(description = "马科维茨投资组合优化，参数：资产名称数组、预期收益率数组、无风险利率")
    public String optimizePortfolio(String[] assets, double[] expectedReturns, double riskFreeRate) {
        return executor.executePortfolioOptimizer(assets, expectedReturns, riskFreeRate).getOutput();
    }
}

九、项目启动与测试（新手必看，快速上手）

按照以下步骤操作，即可快速启动项目，进行测试，全程无坑：

1. 配置application.yml：根据自身需求，配置OpenAI、Azure或通义千问等大模型接口；

2. 准备技能文件：将SKILL.md文件和对应的Python脚本，放入指定的skills目录；

3. 启动项目：运行SkAgentApiApplication类，启动SpringBoot项目；

4. 测试接口：访问以下地址，即可进行流式对话测试（替换参数即可）：

http://localhost:8080/api/chat/stream?agentName=全能金融顾问大师&message=分析贵州茅台DCF估值

十、总结与学习建议（直奔標杆，共同进步）

本文完整实现了一套可直接上生产的AI智能体金融项目，从DDD领域驱动架构设计，到Skill标准化封装、Agent调度机制，再到Python混合计算、全链路审计、流式接口，全程打通，完美解决了大模型在金融场景落地的四大痛点：

• 可计算：借助Python实现精确金融计算，彻底解决大模型幻觉问题；

• 可管控：Skill可插拔、可覆盖、可审计，满足金融管控要求；

• 可扩展：模块解耦，支持多Agent、多Skill，便于后期业务迭代；

• 合规安全：双层技能存储、全链路日志、AI自动质检，符合金融监管规范。

对于开发者来说，这套项目不仅可以直接复用为自己的项目、毕设或面试作品，更能帮助大家理解企业级AI落地的核心逻辑——脱离“聊天demo”，聚焦“生产可用”。

我是直奔標杆，后续会持续分享更多企业级AI落地实战教程，欢迎大家关注、点赞、收藏，一起交流学习，共同成长，少走弯路，直奔技术标杆！

如果大家在搭建过程中有任何问题，欢迎在评论区留言，我会一一回复，一起解决问题～