基于Java与Langchain4j的多智能体银行助手：企业级AI应用实战

在当今企业数字化转型浪潮中，AI Agent（智能体）技术正成为连接自然语言交互与核心业务系统的关键桥梁。其核心原理在于，通过大语言模型（LLM）的理解与规划能力，将用户指令转化为可执行的操作序列。这项技术的核心价值在于，它能安全、可靠地将前沿的生成式AI能力融入现有稳健的微服务架构，而非构建孤立的AI玩具。典型的应用场景包括智能客服、自动化流程助手和内部知识系统等，尤其适用于金融、电商等对操作准

Omoo

546人浏览 · 2026-04-24 14:42:58

Omoo · 2026-04-24 14:42:58 发布

1. 项目概述：一个基于Java与Langchain4j的多智能体银行助手

如果你正在寻找一个能真正将生成式AI与企业级Java后端、微服务架构结合起来的实战项目，那么这个“多智能体银行助手”绝对值得你花时间深入研究。它不是一个简单的聊天机器人Demo，而是一个完整的、生产就绪的PoC（概念验证），模拟了一个真实的个人银行AI助手场景。想象一下，用户不再需要登录繁琐的网银，翻找层层菜单去查余额、看流水或付账单，而是直接像和朋友聊天一样，用自然语言提出需求：“我这个月工资到账了吗？”、“帮我付一下这张电费发票”，系统就能自动理解意图、调用正确的服务并完成操作。这个项目正是为了实现这个愿景而构建的。

它的核心价值在于，提供了一个基于 垂直多智能体架构 的完整实现蓝图。所谓“垂直”，是指每个智能体（Agent）都专注于一个特定的业务领域，比如账户管理、交易查询、支付处理。一个 监督者智能体（Supervisor Agent） 充当“总机”，分析用户对话的意图，然后将任务精准路由给对应的领域专家智能体去执行。这种架构清晰、解耦，非常贴合现代微服务的设计哲学。项目使用 Langchain4j 这个在Java生态中日益流行的AI应用框架来构建智能体，并创新性地通过 MCP（Model Context Protocol）工具 和 Spring AI ，将你现有的业务API（如账户服务、支付服务）无缝暴露给AI智能体调用，让AI能力真正融入你的业务系统，而不是一个孤立的玩具。

我之所以花大力气研究并部署这个项目，是因为它完美地展示了如何将前沿的AI Agent技术与稳健的企业级Java技术栈（Spring Boot、Azure Container Apps）相结合。它解决了AI落地中的一个关键痛点：如何让AI安全、可靠地操作你的核心业务数据和流程。接下来，我将带你从架构设计、核心实现到实操部署，完整地拆解这个项目，分享我在搭建和调试过程中踩过的坑和总结的经验。

2. 架构深度解析：垂直多智能体如何协同工作

理解这个项目的架构，是后续一切部署、开发和优化的基础。它采用的是一种清晰的分层和职责分离设计，我们可以把它想象成一个现代化的“AI驱动银行前台”加上“稳固的业务微服务后台”。

2.1 核心组件与数据流

整个系统可以划分为两大层次： 智能体协同层（Copilot层） 和 业务能力层（微服务层） 。它们之间的协作关系，构成了处理一次用户请求的完整闭环。

智能体协同层（Copilot App） ：这是一个独立的Spring Boot应用，部署在Azure Container Apps上。它是整个AI大脑的载体，包含了所有智能体逻辑。其核心是一个“监督者-工作者”模型：

监督者智能体（Supervisor Agent） ：这是与用户对话的 唯一入口 。它由GPT-4o或GPT-4o-mini驱动，负责进行 意图识别（Intent Classification） 。当用户说“我想看看最近的消费”，监督者会分析这句话，判断出用户的真实需求是“查询交易记录”，而不是“查看余额”或“进行支付”。识别后，它不会自己处理，而是将任务“派发”给最专业的智能体。
领域智能体（Domain Agents） ：包括账户智能体、交易智能体和支付智能体。每个智能体都装备了专属的“工具（Tools）”。例如，支付智能体就配备了“扫描发票”、“提交支付”、“检查是否已支付”等工具。监督者派发任务后，对应的领域智能体被激活，它根据任务描述，自主决定需要调用哪些工具、以什么顺序调用，来完成任务。

业务能力层（微服务） ：这是一组标准的Spring Boot微服务，代表了银行的核心业务系统。它们通过REST API提供数据和服务。项目的巧妙之处在于，这些API被 双重暴露 ：

传统REST API ：供其他传统系统或前端直接调用。
MCP工具 ：通过 spring-ai-mcp 库，将API描述（通常是OpenAPI规范）自动封装成AI可理解和调用的“工具”。智能体看到的不是一个需要自己构造HTTP请求的端点，而是一个像 getAccountBalance(userId: String): Double 这样的函数。这极大地降低了智能体调用业务的复杂度，也提高了可靠性。

前端交互层 ：一个基于React和Fluent UI构建的单页面应用（SPA）。它提供了美观的聊天界面，并支持一个关键功能： 图片上传 。用户可以直接把发票、账单的JPEG/PNG图片拖进聊天框，支付智能体就能调用后端的Azure Document Intelligence服务进行OCR识别，提取付款信息。

整个数据流可以概括为：用户在前端输入文本或上传图片 -> 请求发送至Copilot App -> 监督者智能体分析意图 -> 路由至特定领域智能体 -> 领域智能体规划并调用一个或多个MCP工具 -> 工具调用对应的业务微服务API -> 获取结果并经由智能体整理 -> 返回自然语言回复给前端用户。

2.2 技术选型背后的考量

为什么是这些技术栈？每个选择都有其深意：

Langchain4j ：在Java生态中，它是构建AI应用事实上的标准框架之一。相比直接调用OpenAI SDK，它提供了更高层次的抽象，如智能体（Agent）、工具（Tool）、链（Chain）、记忆（Memory）等概念，让开发者能更专注于业务逻辑而非底层的API交互。它的社区活跃，与Spring Boot集成良好，是Java后端团队引入AI能力相对平滑的选择。
GPT-4o / GPT-4o-mini ：项目默认使用 gpt-4o-mini ，这是一个在成本、速度和能力上取得很好平衡的模型。对于智能体场景，模型的 规划（Planning） 和 工具调用（Tool Calling） 能力至关重要。 gpt-4o-mini 在这方面经过优化，足以处理大多数银行助手的场景。如果对复杂意图识别的准确率有极致要求，可以升级到更强大的 gpt-4o ，但需要权衡其更高的成本和略慢的响应速度。
Azure Document Intelligence ：处理发票扫描的不二之选。它提供了预训练的 prebuilt-invoice 模型，能直接从发票图片中结构化地提取收款方、金额、日期、发票号等关键字段，准确率远高于自己训练OCR模型。这直接将一个复杂的CV问题变成了简单的API调用。
Azure Container Apps (ACA) ：作为部署平台，ACA是容器化微服务和Serverless工作负载的绝佳选择。它简化了Kubernetes的复杂性，内置了服务发现、自动扩缩容和流量管理。对于这种由多个独立服务（Copilot + 多个业务微服务）组成的应用，ACA能很好地管理其生命周期和网络互通。
Azure Developer CLI (azd) ：这是项目快速上手的“加速器”。azd通过一个 azure.yaml 和Bicep模板，将资源编排、环境配置、应用部署流水线化。你不需要手动在Azure Portal里点击创建十几个服务，一条 azd up 命令就能搞定从零到一的整个环境，极大地降低了复现和实验的门槛。

实操心得：关于智能体路由的稳定性 在实际测试中我发现，监督者智能体的意图识别准确率是体验的关键。对于简单的查询如“我的余额”， gpt-4o-mini 基本无误。但当用户意图模糊或涉及多轮对话（如“付一下这个”，然后上传图片）时，偶尔会出现路由错误。这时，除了考虑升级模型，更务实的做法是在 提示词工程（Prompt Engineering） 上下功夫。在定义监督者智能体时，需要非常清晰地描述每个领域智能体的职责边界，并给出大量明确的例子（Few-shot Learning）。例如，明确告诉它“如果用户提到了‘图片’、‘发票’、‘账单’等词汇，或上传了文件，优先路由给支付智能体”。

3. 从零开始：环境搭建与一键部署实战

理论讲完，我们动手把项目跑起来。项目提供了极其便捷的部署方式，无论是用云端的GitHub Codespaces，还是在本地开发，都能快速搭建。

3.1 前期准备与资源规划

在敲下任何命令之前，有几点必须明确，这能帮你避免后续的权限和费用问题：

Azure账户与权限 ：你需要一个有效的Azure订阅。最关键的是，你的账户必须在目标资源组或订阅级别拥有 所有者（Owner） 或 用户访问管理员（User Access Administrator） 角色。因为部署过程中，azd需要为托管身份（Managed Identity）分配角色（如让Container Apps访问Azure OpenAI），这需要 Microsoft.Authorization/roleAssignments/write 权限。如果权限不足，部署会在中途失败。
区域选择 ：不是所有Azure区域都支持本项目所需的所有服务。你需要特别注意：
- Azure OpenAI ：确保你的订阅已获批使用Azure OpenAI服务，并且 gpt-4o-mini 模型在你选择的区域可用。项目默认使用 eastus （美国东部）， swedencentral （瑞典中部）也是已验证可用的区域。你可以在 Azure OpenAI模型可用性页面查询最新信息。
- Azure Document Intelligence (v4.0) ：新版API目前仅在 eastus 、 westus2 、 westeurope 等有限区域开放。务必选择支持的区域，否则发票扫描功能将无法工作。
- 建议：为了简化，首次部署时 统一使用 eastus 区域 ，它能满足所有服务的需求。
成本预估 ：这是一个完整的生产级样板，部署后会产生费用。主要成本构成包括：
- Azure Container Apps ：按实际使用的vCPU和内存资源（Consumption计划）计费。每月有免费额度（180,000 vCPU秒等），对于轻度试用可能不会产生费用。
- Azure OpenAI ：按Token消耗计费。每次对话都会消耗输入和输出的Token。 gpt-4o-mini 价格相对低廉，但持续对话也会累积成本。
- Azure Document Intelligence ：按每页文档的分析次数计费。项目提供了切换到免费SKU的选项，但免费版仅处理每份文档的前2页。
- 其他：Blob存储、Application Insights等也会有少量费用。
重要提示 ：完成实验后，务必使用 azd down 命令或在Azure门户中删除整个资源组，以避免产生持续的费用。

3.2 使用Azure Developer CLI (azd) 一键部署

这是最推荐的方式，它能自动化所有繁琐步骤。确保你已安装 Azure Developer CLI 。

# 1. 克隆仓库
git clone https://github.com/Azure-Samples/agent-openai-java-banking-assistant.git
cd agent-openai-java-banking-assistant

# 2. 登录Azure
azd auth login
# 这会打开浏览器，完成Azure账户认证。

# 3. 一键部署（从零开始）
azd up

执行 azd up 后，你会进入一个交互式流程：

选择订阅 ：如果你有多个Azure订阅，azd会列出它们让你选择。
选择区域 ：输入支持的区域，如 eastus 。
输入环境名称 ：给这次部署起个名字，例如 my-banking-agent-dev 。azd会以此名称创建资源组（格式： rg-<环境名> ）。接下来，azd会开始它的魔法：

预配（Provision） ：根据 infra/ 目录下的Bicep模板，在Azure上创建所有必要的资源，包括资源组、Container Apps环境、Azure OpenAI服务、Document Intelligence服务、容器注册表（ACR）、Log Analytics工作区等。
部署（Deploy） ：构建项目中的所有Docker镜像（Copilot App、前端、各个业务微服务），并将它们推送到ACR，最后部署到对应的Container Apps上。

整个过程大约需要15-25分钟，取决于网络速度和Azure后台处理速度。当你在终端看到绿色的“SUCCESS”字样和一个Web应用URL时，就大功告成了。点击那个URL，就能打开银行助手的前端界面。

3.3 使用已有Azure资源进行部署

如果你已经有一些现成的Azure服务（比如之前创建的OpenAI服务），可以复用它们，避免重复创建。

# 设置环境变量，指向现有资源
azd env set AZURE_RESOURCE_GROUP my-existing-rg
azd env set AZURE_LOCATION eastus

azd env set AZURE_OPENAI_SERVICE my-openai-service
azd env set AZURE_OPENAI_RESOURCE_GROUP my-openai-rg
# 如果OpenAI资源在另一个区域，需要单独设置
azd env set AZURE_OPENAI_SERVICE_LOCATION westus

azd env set AZURE_DOCUMENT_INTELLIGENCE_SERVICE my-doc-intel-service
azd env set AZURE_DOCUMENT_INTELLIGENCE_RESOURCE_GROUP my-doc-intel-rg

# 设置完成后，再运行 azd up
azd up

azd会读取这些环境变量，在部署时跳过对应资源的创建，而是使用你指定的现有资源。这非常适合团队共享开发资源或成本控制。

3.4 本地开发与调试

对于开发者来说，在本地运行和调试至关重要。项目贴心地提供了Docker Compose配置，可以在本地模拟整个环境。

# 进入应用目录
cd app

# 根据你的操作系统运行启动脚本
# Windows (PowerShell)
.\start-compose.ps1

# Linux/Mac
./start-compose.sh

这个脚本会启动多个容器：前端React应用、Copilot Spring Boot应用、以及三个业务微服务（Account, Payment, Transaction）。它假设你已经通过 az login 登录了Azure，并且本地有足够的权限访问你Azure订阅中的OpenAI和Document Intelligence服务（脚本会使用你的本地Azure CLI凭证）。

启动完成后，在浏览器中访问 http://localhost 即可。本地运行的优势是 调试方便 。你可以用IDE（如IntelliJ IDEA或VS Code）连接到本地运行的Copilot应用，打断点，观察智能体是如何解析意图、调用工具的，这对于理解内部机制和排查问题有巨大帮助。

避坑指南：本地Docker Compose的常见问题

端口冲突 ：确保本地80、8080等端口没有被其他程序占用。

Azure认证失败 ：确保 az login 成功，并且账户有相应资源的访问权限。有时需要重启终端或IDE使凭证生效。

镜像构建慢 ：首次运行会从Docker Hub拉取基础镜像并构建项目镜像，请保持网络通畅。如果遇到Maven依赖下载慢，可以考虑配置国内镜像源，但需要修改Dockerfile，略为复杂。

内存不足 ：同时运行多个Java Spring Boot容器对本地内存有一定要求（建议16GB以上）。如果电脑内存紧张，可以尝试在 docker-compose.yml 中调低每个服务的 mem_limit 。

4. 核心实现拆解：智能体、工具与业务API的融合

部署成功只是第一步，理解代码如何实现AI与业务的连接，才是掌握这个项目的关键。我们深入到Copilot应用的核心，看看智能体和工具是如何被定义和使用的。

4.1 监督者智能体：智能路由的大脑

在 CopilotApplication 或相关的配置类中，你会找到监督者智能体的定义。它本质上是一个特殊的Langchain4j Agent，其核心是一个精心设计的 System Prompt（系统提示词） 。这个提示词定义了它的角色、职责和可用的“下属”。

// 这是一个概念性代码，展示监督者智能体的配置思路
@Bean
public Agent supervisorAgent(OpenAiChatModel chatModel,
                             AccountAgent accountAgent,
                             TransactionsAgent transactionsAgent,
                             PaymentsAgent paymentsAgent) {

    String systemPrompt = """
            你是一个银行助手系统的总调度员（监督者）。你的唯一职责是分析用户的请求，并决定由哪个专业助手来处理。
            你有以下三个专业助手：
            1. 账户助手（Account Agent）：专门处理与账户信息相关的问题，例如查询余额、查询绑定的支付方式、查询收款人列表。
            2. 交易助手（Transactions Agent）：专门处理与交易记录相关的问题，例如查询最近交易、按金额/日期/收款人筛选交易。
            3. 支付助手（Payments Agent）：专门处理支付相关操作，例如扫描发票并支付、提交新的支付指令、查询支付状态。

            用户可能上传图片（如发票）。如果请求中涉及图片或明确提到“发票”、“账单”、“支付”，你必须将其交给支付助手。

            请严格根据用户意图选择其中一个助手。你的回复只能是以下格式之一：
            - 如果交给账户助手: ACCOUNT
            - 如果交给交易助手: TRANSACTIONS
            - 如果交给支付助手: PAYMENTS

            不要解释，不要添加任何其他文字。
            """;

    return Agent.builder()
            .chatLanguageModel(chatModel) // 使用注入的GPT模型
            .systemPrompt(systemPrompt)
            .build();
}

监督者智能体本身不调用任何业务工具。它只做一件事：文本分类。它将用户的输入（可能包含上传图片的描述）映射到三个固定的输出之一。后端的路由逻辑（一个 @RestController ）会根据这个输出，调用相应的领域智能体。

4.2 领域智能体与MCP工具：让AI调用你的API

领域智能体是真正干活的专家。以 PaymentsAgent 为例，它被赋予了一系列“工具”。在Langchain4j中，一个工具可以是一个简单的Java方法。但本项目的高级之处在于，它利用 Spring AI MCP 将整个微服务的API变成了智能体的工具箱。

传统方式（手动定义工具） ：

@Tool("根据发票图片扫描并提取信息")
public InvoiceData scanInvoice(@P("发票图片的Base64编码字符串") String imageBase64) {
    // 手动调用Azure Document Intelligence API
    // 解析结果，返回结构化的InvoiceData对象
}

本项目方式（基于MCP自动生成工具） ：

业务微服务 （如Payment Service）正常编写REST API，并生成OpenAPI (Swagger) 规范文件（ openapi.yaml ）。
Copilot应用 通过 spring-ai-mcp 依赖，在启动时读取这个 openapi.yaml 文件。
自动工具注册 ：Spring AI MCP框架会解析OpenAPI文件，将每个API端点（如 POST /api/payments ）转换成一个Langchain4j可识别的 Tool 。它会自动从API描述中提取参数名、类型和说明。
智能体装配 ：在配置 PaymentsAgent 时，可以直接注入这些自动生成的工具。

# 示例：Payment Service的 openapi.yaml 片段
paths:
  /api/payments:
    post:
      summary: 提交一笔支付
      operationId: submitPayment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: 支付成功

这样， PaymentsAgent 就自动拥有了一个名为 submitPayment 的工具，其描述和参数都来自OpenAPI定义。当智能体决定要调用这个工具时，Langchain4j会处理与LLM的交互，提取出必要的参数（如金额、收款方），然后通过MCP客户端调用实际的Payment Service API。

实操心得：MCP工具的优势与调试 使用MCP的最大好处是 维护性 。当你的业务API更新时（比如增加一个字段），你只需要更新微服务的代码和OpenAPI文档。Copilot应用在下一次启动或通过配置热加载后，智能体就能“看到”新的API结构，无需修改智能体本身的代码。调试时，关键是要查看日志。启用Application Insights后，你可以追踪一次聊天请求的完整链路，看到监督者智能体的输出（是 ACCOUNT 还是 PAYMENTS ），看到领域智能体生成的“思考过程”（它计划调用哪些工具），以及每个MCP工具调用的请求和响应详情。这能帮你快速定位是意图识别错了，还是工具调用参数提取有误。

4.3 前端与后端的通信：SSE实现流式响应

前端聊天界面与Copilot后端通过Server-Sent Events (SSE) 进行通信。这是处理AI生成式回复的常见模式，因为它支持流式传输（Streaming），可以让用户看到答案一个字一个字地出现，体验更好。

// 前端概念代码
const eventSource = new EventSource(`/api/chat/stream?message=${encodeURIComponent(userInput)}`);
eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'content') {
        // 追加到聊天框
        appendToChat(data.content);
    } else if (data.type === 'tool_call') {
        // 显示“AI正在调用XX工具...”的提示
        showToolCall(data.toolName);
    } else if (data.type === 'end') {
        eventSource.close();
    }
};

后端Spring Boot控制器会返回一个 SseEmitter ，在智能体生成回复的每个“块”（chunk）时，通过 emitter.send() 推送到前端。同时，当智能体开始调用工具时，也会发送一个特殊事件，前端可以据此显示一个状态提示（如“正在查询账户余额...”），极大地提升了交互的透明度和用户体验。

5. 进阶配置、监控与问题排查

项目跑起来之后，你可能会想根据实际情况进行调整，或者需要诊断为什么智能体没有按预期工作。

5.1 切换AI模型与版本

默认的 gpt-4o-mini 性价比高，但如果你需要更强的推理能力，可以切换到 gpt-4o 。

# 在项目根目录下，使用azd环境变量进行切换
azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4o
azd env set AZURE_OPENAI_CHATGPT_VERSION 2024-05-13 # 使用最新的稳定版本
azd env set AZURE_OPENAI_CHATGPT_DEPLOYMENT gpt-4o # 部署名称，通常与模型名一致

# 更新环境后，重新部署Copilot应用即可
azd deploy

azd deploy 只会重新构建和部署应用代码，不会重新预配Azure资源，速度更快。

5.2 利用Application Insights进行深度监控

项目默认启用了Application Insights，这是Azure上的全链路监控服务。它对于理解智能体行为至关重要。

查看性能 ：在Azure门户中，进入Application Insights资源，点击“性能”边栏。你可以看到所有HTTP请求的耗时。找到 /api/chat 这个端点，查看其平均响应时间。AI调用通常较慢，你可以在这里建立性能基线。
端到端事务追踪 ：这是最强大的功能。在性能页面，点击一个具体的 /api/chat 请求，然后点击“Drill into Samples” -> “End-to-end transaction details”。你会看到一个时间线，清晰展示了这次请求的完整生命周期：
- 请求进入Spring Boot控制器。
- 调用监督者智能体（一次OpenAI API调用）。
- 调用领域智能体（又一次OpenAI API调用，包含工具调用的规划）。
- 每个MCP工具的执行（对业务微服务的HTTP调用）。
- 最终响应返回。通过这个视图，你可以精确知道时间花在了哪里（是AI推理慢，还是某个业务API慢）。
查看日志与异常 ：在“失败”或“日志”边栏，你可以搜索到应用打印的所有日志。Copilot应用中将Langchain4j的对话和工具调用细节以INFO级别打印了出来。通过筛选这些日志，你可以看到AI模型接收到的完整提示词、返回的思考过程以及工具调用的具体参数，这对于调试智能体的决策逻辑是无可替代的。

5.3 常见问题与排查清单

即使按照步骤操作，你也可能会遇到一些问题。下面是我在多次部署和测试中总结的常见问题及解决方法：

问题现象	可能原因	排查步骤与解决方案
`azd up` 失败，提示角色分配错误	当前Azure账户权限不足，无法创建角色分配。	1. 确认账户在订阅或资源组级别是“所有者”或“用户访问管理员”。 2. 联系订阅管理员为你分配相应权限。
部署成功，但前端页面打开后无法发送消息，控制台报错404或500。	后端服务未成功启动或服务间网络不通。	1. 在Azure门户中，进入Container Apps环境，检查所有容器应用（copilot, web, account等）的状态是否为“Running”。 2. 查看copilot应用的日志流（Log Stream），看是否有启动错误，如连接不上OpenAI（API密钥错误、区域不对）。
聊天可以回复，但一涉及具体操作（如查余额、付发票）就报错或回复“我无法处理”。	1. 智能体路由错误。 2. MCP工具连接业务API失败。 3. 业务API本身有错误。	1. 查看监督者输出：在Application Insights日志中搜索监督者智能体的回复，确认它是否正确输出了 `ACCOUNT` 、 `TRANSACTIONS` 或 `PAYMENTS` 。 2. 查看领域智能体日志：确认领域智能体被调用后，是否成功规划了工具调用。日志会显示 `Tool: xxx called with arguments: ...` 。 3. 检查MCP连接：确认Copilot应用能否访问业务微服务的URL。在Container Apps环境中，服务发现通常通过内部DNS（如 `http://account-app.internal` ）实现，检查这些地址是否可通。
上传发票图片后，支付智能体回复“无法识别”或提取信息错误。	1. Azure Document Intelligence服务未启用或密钥错误。 2. 发票图片质量太差。 3. 预建模型不支持该发票格式。	1. 在Azure门户检查Document Intelligence资源是否已成功创建且状态正常。 2. 检查Copilot应用的环境变量 `AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT` 和 `AZURE_DOCUMENT_INTELLIGENCE_KEY` 是否正确注入。 3. 尝试使用项目 `data/` 文件夹中提供的示例发票图片进行测试。 4. 查看Document Intelligence的API响应日志，确认返回了结构化数据。
本地Docker Compose运行失败，提示端口被占用或镜像构建错误。	1. 本地环境冲突。 2. 网络问题导致依赖下载失败。	1. 使用 `docker ps` 和 `netstat` 检查端口占用情况，修改 `docker-compose.yml` 中的端口映射。 2. 尝试先单独构建有问题的服务镜像： `docker build -t account-service ./account-service` 。 3. 清理Docker缓存： `docker system prune -a` ，然后重试。

5.4 集成到现有CI/CD流水线

项目自带了GitHub Actions工作流文件（ .github/workflows/azure-dev.yml ），可以实现在代码推送时自动构建和部署。要启用它，你需要完成几个关键配置步骤：

创建服务主体（Service Principal） ：这个SP将代表GitHub Actions在Azure中进行部署。你需要给它分配对资源组的“贡献者”角色和对容器注册表的“AcrPush”角色。
在GitHub仓库中配置机密（Secrets）和环境变量 ：将上一步获得的SP凭证（JSON格式）存入仓库的Secrets中，并设置好容器注册表名称、资源组名称等环境变量。
理解工作流触发 ：默认工作流在向 main 分支推送代码时触发。它会使用azd执行 azd deploy ，这意味着它只重新部署应用，而不会改动Azure基础设施（除非你修改了Bicep模板）。这种分离（基础设施变更手动执行 azd up ，应用变更自动部署）是符合IaC（基础设施即代码）的最佳实践。

这个自动化流水线确保了你的AI银行助手应用可以像其他微服务一样，享受持续集成和持续部署带来的效率与质量提升。

经过以上从架构到部署，从原理到实操的详细拆解，你应该对这个基于Java和Langchain4j的多智能体银行助手项目有了全面而深入的理解。它不仅仅是一个示例，更是一个 企业级AI应用的设计范式 。它展示了如何将强大的大语言模型以安全、可控、可维护的方式，集成到复杂的业务系统中。你可以以此为基础，将其智能体模式扩展到客服、运维、内部知识问答等任何需要自然语言交互与业务系统联动的场景。真正的挑战和乐趣，在于根据你自己的业务需求，去设计智能体的职责、打磨提示词、并构建可靠的工具集。这个项目为你打下了坚实的地基，剩下的就是发挥你的创造力，去建造属于你的AI智能大厦了。