如何用 AI-Meeting 搭建自己的 AI 助手:Agent 智能体配置与星云工作流绑定实战
如何用 AI-Meeting 搭建自己的 AI 助手:Agent 智能体配置与星云工作流绑定实战
AI-Meeting 是一个基于 Spring Boot 3 + Java 17 + Spring AI + MySQL + MongoDB + Redis 的 AI 智能助手后端项目,内置 AI 对话、智能体会话、AI 模拟面试、实时语音转写等能力。本文以"Agent 智能体配置"为核心,手把手带你把 AI-Meeting 的智能体接入讯飞星云工作流(XingChen Workflow),只需配好 4 个字段,就能让后端业务场景调用你自己编排好的 AI 工作流,轻松搭建属于你自己的 AI 助手。
先搞清楚:AI-Meeting 里的"智能体"到底是什么?
一句话:智能体 = 一条数据库记录 = 一组星云工作流的访问凭据 + 工作流 ID。
它对应的实体是 AgentPropertiesDO.java,映射到 MySQL 的 agent_properties 表,核心字段只有 4 个:
| 字段 | 含义 | 从哪来 |
|---|---|---|
agentName |
智能体名称(中文,如"面试出题官"),业务场景靠它绑定 | 自己起名 |
apiKey |
鉴权 key | 讯飞开放平台 API Key |
apiSecret |
鉴权密钥 | 讯飞开放平台 API Secret |
apiFlowId |
星云工作流 ID,决定实际调用哪个工作流 | 星云平台发布工作流后获得 |
除了这 4 个字段,还可以挂标签(前端、后端、人工智能等分类),标签类型定义在 AgentTagType.java。
💡 记住这个模型:改工作流不用改代码。想换提示词、换模型、加节点,去星云平台改完工作流、把新的
apiFlowId更新进数据库即可。
三步创建并配置你自己的 Agent 智能体
第一步:在星云平台编排并发布工作流
到讯飞星云(XingChen)大模型平台,用可视化画布编排你的工作流:拖入开始节点、大模型节点、结束节点,配置提示词和变量。发布后你会拿到一个 工作流 ID(FlowId)——后面配置要用。
项目里附带了 5 个现成的工作流模板(YAML 格式,可直接参考节点与变量定义):
打开任何一个模板看一眼,你会发现开始节点固定暴露了两个输入变量:
AGENT_USER_INPUT:用户本轮对话输入内容USER_FILE:用户文件(如简历 PDF)
这就是后端与星云工作流之间的"契约"——AI-Meeting 的 XingChenAIClient.java 每次调用都会把用户输入塞进 AGENT_USER_INPUT、上传后的文件地址塞进 USER_FILE(见 buildParameters 方法)。所以你的工作流只要遵守这个输入约定,就能无缝被后端调用。
第二步:把智能体录入 agent_properties
有三种录入方式,新手任选其一:
- 直接执行项目内置种子数据:agent_properties.sql 已经预置了"面试出题官""神态分析官""用户答案评分官""面试提问官"4 条记录,初始化数据库后即可开箱使用(其中的 Key 是示例值,请替换成你自己的)。
- 调用配置管理接口:AgentPropertiesController.java 提供了完整的 REST 接口(路径前缀
/api/xunzhi/v1/agent-properties):POST创建智能体PUT更新智能体(换 FlowId 就靠它)GET/GET /byName分页查询 / 按名称查询DELETE /{id}逻辑删除
- 直接操作数据库:手工 INSERT 一条记录,字段含义见上文表格。
创建时填写的请求体结构定义在 AgentPropertiesReqDTO.java,包含 agentName、apiKey、apiSecret、apiFlowId 以及可选的 tagCodes 标签列表。
第三步:把业务场景绑定到你的智能体
这是最关键、也是最容易忽略的一步——代码里的业务场景,是靠 agentName(中文名)找到你的智能体配置的。
AI-Meeting 预定义了 5 个业务场景(定义在 BusinessAgentScene.java):
| 场景 code | 默认智能体名 | 别名 | 干什么用 |
|---|---|---|---|
general-agent-chat |
通用智能体 | - | 通用 AI 聊天助手 |
interview-question-extraction |
面试出题官 | 面试题出题官 | 解析简历、生成面试题 |
interview-answer-evaluation |
用户答案评分官 | 面试答案评分官 | 给候选人回答打分 |
interview-demeanor |
神态分析官 | 神态评分面试官、表情分析面试官 | 仪态/表情分析 |
interview-question-asking |
面试提问官 | - | 面试提问 |
每个场景在 application.yaml 的 xunzhi-agent.agent-binding 下都有一个绑定配置,且支持用环境变量覆盖,例如:
interview-question-extraction: ${XUNZHI_AGENT_INTERVIEW_QUESTION_EXTRACTION:面试出题官}
意思是:默认用名为"面试出题官"的智能体;如果你把自己的智能体起名叫"我的出题专家",启动时设置环境变量 XUNZHI_AGENT_INTERVIEW_QUESTION_EXTRACTION=我的出题专家 即可完成绑定,全程零代码改动。
绑定解析的查找顺序:为什么有时候"配了却找不到"?
解析逻辑实现在 BusinessAgentResolver.java,规则非常清晰:
- 先读
agent-binding里配置的场景绑定名,若存在,优先用它去查agent_properties表; - 查不到,再依次尝试场景枚举中的默认名和别名;
- 第一个命中的智能体配置即生效,并打印
Resolved business agent scene=...日志; - 全部落空,则抛出
AGENT_CONFIG_NOT_FOUND异常。
配置名与数据库记录不一致时会有 fallback 告警日志,排查思路可以参考项目自带的避坑清单 agent-domain gotchas.md 和场景绑定说明 agent-binding.md,核心提醒只有一条:
⚠️ 改名要两处同步——改了
agent-binding里的配置名,就要保证agent_properties表里有同名记录;反之亦然。
另外,AgentPropertiesLoader.java 会在应用启动时把所有未删除的智能体加载进内存缓存,查询时先走缓存、未命中再回源数据库。所以更新智能体后重启应用或让缓存自然刷新是最稳妥的生效方式。
一次真实的调用链路长什么样?
以通用聊天为例,整条链路如下(源码均在 AgentController.java 与面试域服务中可查证):
- 前端
POST /api/xunzhi/v1/agents/sessions创建会话,后端按general-agent-chat场景解析出智能体,把它的id记到会话上; - 前端
POST /agents/sessions/{sessionId}/chat发起对话; - 后端取出该会话绑定的智能体配置(apiKey / apiSecret / apiFlowId),交给
XingChenAIClient请求星云工作流接口workflow/v1/chat/completions,请求头携带Authorization: Bearer {apiKey}:{apiSecret},请求体携带flow_id、chat_id(多轮记忆)和parameters(用户输入); - 支持 SSE 流式返回,前端实现打字机效果;面试域还叠加了分布式 Single-flight 防重、AI 调用防护等工程能力。
新手常见问题速查
| 现象 | 检查点 |
|---|---|
启动或对话时报 AGENT_CONFIG_NOT_FOUND |
agent_properties 表里是否存在与场景默认名/别名同名的记录 |
| 配了新 FlowId 但行为没变 | 是否走了更新接口/重启应用,让 AgentPropertiesLoader 缓存刷新 |
| 工作流侧收不到用户输入 | 开始节点是否定义了 AGENT_USER_INPUT 变量(契约见 XingChenAIClient.java 的 buildParameters) |
| 上传简历后工作流拿不到文件 | 开始节点是否声明了 USER_FILE 变量,且文件类型在白名单内(如 pdf) |
| 想给自己的场景绑一个完全自定义的智能体 | 用 agentName 起名 + 环境变量覆盖 agent-binding 配置,无需改代码 |
写在最后
回顾一下你刚才完成的事:
- ✅ 理解了"智能体 = 凭据 + FlowId"的核心模型;
- ✅ 用模板或星云平台编排了工作流,并遵守
AGENT_USER_INPUT/USER_FILE输入契约; - ✅ 通过 agent_properties.sql 或 REST 接口录入智能体;
- ✅ 借助
xunzhi-agent.agent-binding配置把业务场景绑定到你的智能体。
至此,AI-Meeting 的后端业务已经由你的星云工作流在驱动——改提示词、加节点、换模型都不再需要动 Java 代码。想深入细节,可以继续阅读 Agent 场景索引 与 Agent 模块源码目录 agent/,把这套"配置即智能体"的思路迁移到你自己的 Spring Boot AI 项目里。




