基于Harness与Langfuse构建企业级财务分析智能体实战指南

在AI技术快速发展的今天，如何将前沿的LLM能力稳定、可靠地集成到企业核心业务流程中，是每个技术团队面临的挑战。特别是在财务分析这类对准确性、可追溯性和合规性要求极高的领域，一个“玩具级”的智能体Demo与一个“企业级”的生产系统之间，存在着巨大的鸿沟。本文将围绕 Harness架构 与 Langfuse评估平台 ，手把手带你构建一个面向财务分析的智能体项目，并深入探讨AI工程化落地的完整闭环。无论你是希望将AI能力引入现有业务的后端工程师，还是对Agent开发与评估感兴趣的研究者，都能从这套覆盖环境搭建、核心开发、全面评估到生产部署的实战教程中获得直接可复用的经验。

1. 项目背景与核心概念解析

在深入代码之前，我们有必要厘清几个核心概念，理解它们如何共同支撑起一个企业级的AI应用。

1.1 什么是AI工程化与财务分析智能体？

AI工程化 远不止是调用一个API。它是一套系统工程方法，旨在将机器学习模型，特别是大语言模型，转化为稳定、可维护、可扩展且安全的软件系统。这涵盖了从数据准备、模型开发、持续集成/持续部署、监控、评估到迭代优化的全生命周期管理。其核心目标是解决AI项目“实验室有效，生产环境失效”的难题。

财务分析智能体 则是AI工程化在垂直领域的具体实践。它不是一个简单的问答机器人，而是一个具备特定领域知识的AI助手，能够理解复杂的财务术语（如EBITDA、现金流折现）、处理结构化数据（Excel、数据库报表）、执行多步骤推理（如趋势分析、风险预警），并生成符合业务规范的洞察报告。其挑战在于确保输出的 准确性、一致性与可审计性 。

1.2 Harness：AI应用的生产就绪框架

Harness是一个开源的AI应用开发框架与平台。你可以将其理解为AI时代的“Spring Boot”。它旨在简化构建、评估和部署生产级AI应用的复杂度。其核心价值在于：

• 标准化开发模式 ：提供统一的 Agent 、 Tool 、 Workflow 抽象，让开发者聚焦业务逻辑，而非胶水代码。
• 内置可观测性 ：自动追踪每次调用的链路、耗时、Token消耗和成本，为优化提供数据基础。
• 生产部署支持 ：提供易于扩展的服务器架构，方便将开发好的智能体部署为API服务。

近期，Harness因其与DeepSeek等模型的深度集成而受到广泛关注，但其设计是模型无关的，同样支持OpenAI、Anthropic等主流模型。

1.3 Langfuse：LLM应用的评估与监控平台

如果说Harness负责“建造”智能体，那么Langfuse就负责“质检”和“监护”。它是一个开源的LLM应用可观测性与评估平台，主要解决两大问题：

1. 评估 ：如何科学地衡量一个AI应用的表现？Langfuse允许你定义评估指标（如正确性、相关性、安全性），并通过人工评分、模型评分或自动化测试等方式，对智能体的历史运行记录进行批量评估，生成可视化报告。
2. 监控 ：在生产中，智能体的表现是否稳定？成本是否超标？Langfuse提供实时追踪、告警和数据分析功能，帮助团队及时发现并响应问题。

将Harness与Langfuse结合，就形成了一套从开发、评估到监控的完整AI工程化闭环。

2. 环境准备与项目初始化

我们将构建一个名为 FinanceAnalystAgent 的智能体，它能够读取上传的财务报表，进行关键指标计算和初步分析。

2.1 基础环境要求

• 操作系统 ：Linux/macOS/Windows (WSL2推荐)
• Python版本 ：3.10 或 3.11（确保稳定性）
• 包管理工具 ：Poetry（推荐）或 pip
• 模型API ：准备一个可用的OpenAI API Key（或DeepSeek、Anthropic等）。本文以OpenAI为例。

2.2 创建项目并安装核心依赖

首先，创建项目目录并初始化虚拟环境。

# 创建项目目录
mkdir finance-analyst-agent && cd finance-analyst-agent

# 使用Poetry初始化项目（如果未安装，请先安装：pip install poetry）
poetry init -n

接下来，编辑生成的 pyproject.toml 文件，添加项目依赖。这是企业级项目的关键一步，锁定依赖版本以确保环境一致性。

# pyproject.toml
[tool.poetry]
name = "finance-analyst-agent"
version = "0.1.0"
description = "An enterprise-grade financial analysis agent built with Harness and Langfuse."
authors = ["Your Name <your.email@example.com>"]

[tool.poetry.dependencies]
python = "^3.10"
harness = "^0.1.0"  # 请检查Harness的最新版本
langfuse = "^3.0.0"  # Langfuse Python SDK
openai = "^1.0.0"
pandas = "^2.0.0"  # 用于处理财务数据
python-dotenv = "^1.0.0"  # 管理环境变量
pydantic = "^2.0.0"  # 数据验证
pydantic-settings = "^2.0.0"  # 配置管理

[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"
black = "^24.0.0"
isort = "^5.12.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

然后，安装依赖并激活虚拟环境：

poetry install
poetry shell

2.3 配置环境变量与密钥管理

永远不要将API密钥硬编码在代码中。我们使用 .env 文件和 pydantic-settings 来安全管理配置。

1. 创建 .env 文件：

   # .env
   OPENAI_API_KEY=sk-your-openai-api-key-here
   LANGFUSE_SECRET_KEY=sk-lf-your-langfuse-secret-key-here
   LANGFUSE_PUBLIC_KEY=pk-lf-your-langfuse-public-key-here
   LANGFUSE_HOST=https://cloud.langfuse.com  # 或你的自托管地址
   HARNESS_LOG_LEVEL=INFO
   

   注意：你需要去OpenAI和Langfuse官网注册并获取相应的密钥。Langfuse提供云服务和自托管选项。

2. 创建配置管理模块 config.py ：

   # src/config.py
   from pydantic_settings import BaseSettings
   from pydantic import Field
   
   class Settings(BaseSettings):
       """应用配置，自动从环境变量和.env文件加载"""
       openai_api_key: str = Field(..., alias="OPENAI_API_KEY")
       langfuse_secret_key: str = Field(..., alias="LANGFUSE_SECRET_KEY")
       langfuse_public_key: str = Field(..., alias="LANGFUSE_PUBLIC_KEY")
       langfuse_host: str = Field("https://cloud.langfuse.com", alias="LANGFUSE_HOST")
       harness_log_level: str = Field("INFO", alias="HARNESS_LOG_LEVEL")
   
       class Config:
           env_file = ".env"
           extra = "ignore"  # 忽略未定义的额外环境变量
   
   settings = Settings()  # 全局配置实例
   

3. 核心模块开发：构建财务分析智能体

我们将按照Harness的架构模式，分别构建 Tool 、 Agent 和 Workflow 。

3.1 定义财务分析工具

智能体的能力通过 Tool 来扩展。我们先创建两个核心工具：一个用于解析财务报表CSV，另一个用于计算财务比率。

# src/tools/financial_tools.py
import pandas as pd
from typing import Dict, Any, Optional
from harness.tool import tool
from pydantic import BaseModel, Field

class FinancialData(BaseModel):
    """财务数据结构"""
    revenue: float
    gross_profit: float
    net_income: float
    total_assets: float
    total_liabilities: float
    equity: float
    period: str  # e.g., "2025-Q4"

@tool
def parse_financial_statement(file_path: str) -> Dict[str, FinancialData]:
    """
    解析上传的财务报表CSV文件，将其转换为结构化的财务数据。
    
    Args:
        file_path: 财务报表CSV文件的路径。文件应包含列：period, revenue, gross_profit, net_income, total_assets, total_liabilities, equity。
    
    Returns:
        一个字典，键为期间（period），值为对应的FinancialData对象。
    """
    try:
        df = pd.read_csv(file_path)
        # 数据清洗与验证
        required_columns = {"period", "revenue", "gross_profit", "net_income", "total_assets", "total_liabilities", "equity"}
        if not required_columns.issubset(df.columns):
            missing = required_columns - set(df.columns)
            raise ValueError(f"CSV文件缺少必要的列: {missing}")
        
        financial_data = {}
        for _, row in df.iterrows():
            data = FinancialData(
                period=row["period"],
                revenue=float(row["revenue"]),
                gross_profit=float(row["gross_profit"]),
                net_income=float(row["net_income"]),
                total_assets=float(row["total_assets"]),
                total_liabilities=float(row["total_liabilities"]),
                equity=float(row["equity"])
            )
            financial_data[row["period"]] = data
        return financial_data
    except Exception as e:
        return {"error": f"解析财务报表失败: {str(e)}"}

@tool
def calculate_financial_ratios(financial_data: Dict[str, FinancialData]) -> Dict[str, Any]:
    """
    基于结构化的财务数据，计算关键财务比率。
    
    Args:
        financial_data: 由parse_financial_statement工具输出的财务数据字典。
    
    Returns:
        包含各期间财务比率的字典。例如：{"2025-Q4": {"gross_margin": 0.45, "roe": 0.15, ...}}
    """
    ratios_by_period = {}
    for period, data in financial_data.items():
        # 计算毛利率
        gross_margin = data.gross_profit / data.revenue if data.revenue != 0 else 0
        # 计算净资产收益率
        roe = data.net_income / data.equity if data.equity != 0 else 0
        # 计算资产负债率
        debt_to_asset = data.total_liabilities / data.total_assets if data.total_assets != 0 else 0
        # 计算净利率
        net_margin = data.net_income / data.revenue if data.revenue != 0 else 0
        
        ratios_by_period[period] = {
            "gross_margin": round(gross_margin, 4),
            "return_on_equity": round(roe, 4),
            "debt_to_asset_ratio": round(debt_to_asset, 4),
            "net_margin": round(net_margin, 4),
            "revenue_growth": None  # 需要多期数据计算
        }
    
    # 计算收入增长率（如果有多期数据）
    periods = sorted(ratios_by_period.keys())
    for i in range(1, len(periods)):
        current_period = periods[i]
        previous_period = periods[i-1]
        current_rev = financial_data[current_period].revenue
        previous_rev = financial_data[previous_period].revenue
        if previous_rev != 0:
            growth = (current_rev - previous_rev) / previous_rev
            ratios_by_period[current_period]["revenue_growth"] = round(growth, 4)
    
    return ratios_by_period

3.2 创建财务分析智能体

智能体是协调工具调用和LLM推理的核心。我们使用Harness的 Agent 类来定义。

# src/agents/financial_analyst.py
from harness.agent import Agent, Handoff
from harness.memory import Memory
from harness.tool import ToolRegistry
from openai import OpenAI
from src.config import settings
from src.tools.financial_tools import parse_financial_statement, calculate_financial_ratios
import json

# 初始化OpenAI客户端
client = OpenAI(api_key=settings.openai_api_key)

# 创建工具注册表并注册工具
tool_registry = ToolRegistry()
tool_registry.register(parse_financial_statement)
tool_registry.register(calculate_financial_ratios)

# 定义系统提示词，塑造智能体的角色和能力
SYSTEM_PROMPT = """
你是一位资深财务分析师。你的任务是帮助用户分析财务报表数据，提供专业、准确、易于理解的财务洞察。

## 你的能力：
1.  **解析数据**：你可以解析用户上传的财务报表CSV文件，理解其中的收入、利润、资产、负债等关键数据。
2.  **计算比率**：你可以自动计算关键的财务比率，如毛利率、净资产收益率、资产负债率、净利率和收入增长率。
3.  **生成分析**：基于原始数据和计算出的比率，你能用通俗的语言总结财务状况，指出优势、风险和趋势。

## 你的工作流程：
1.  当用户提供财务报表文件路径时，首先调用`parse_financial_statement`工具获取结构化数据。
2.  然后，调用`calculate_financial_ratios`工具计算财务比率。
3.  最后，综合以上信息，撰写一份简要的财务分析报告。

## 输出要求：
- 报告应包含对盈利能力、偿债能力、运营效率等方面的评价。
- 使用具体的数字和比率支持你的观点。
- 如果发现异常值（如负的利润率、极高的负债率），应明确指出并提醒潜在风险。
- 保持回答专业且友好。
"""

class FinancialAnalystAgent(Agent):
    """财务分析智能体"""
    
    def __init__(self):
        super().__init__(
            name="FinancialAnalyst",
            model="gpt-4-turbo-preview",  # 可根据需要更换模型
            client=client,
            system_prompt=SYSTEM_PROMPT,
            tools=tool_registry,
            memory=Memory()  # 启用对话记忆
        )
    
    async def analyze_statement(self, file_path: str) -> str:
        """
        主分析方法：协调工具调用并生成最终分析报告。
        
        Args:
            file_path: 财务报表CSV文件的路径。
        
        Returns:
            财务分析报告文本。
        """
        # 步骤1：解析财务报表
        parse_result = await self.use_tool(
            tool_name="parse_financial_statement",
            arguments={"file_path": file_path}
        )
        
        if "error" in parse_result:
            return f"数据解析阶段出错：{parse_result['error']}。请检查文件格式和内容。"
        
        financial_data = parse_result
        
        # 步骤2：计算财务比率
        ratio_result = await self.use_tool(
            tool_name="calculate_financial_ratios",
            arguments={"financial_data": financial_data}
        )
        
        # 步骤3：请求LLM生成分析报告
        analysis_prompt = f"""
        以下是一家公司的财务数据及计算出的关键比率：
        
        原始财务数据（按期间）：
        {json.dumps({k: v.dict() for k, v in financial_data.items()}, indent=2, default=str)}
        
        计算出的财务比率：
        {json.dumps(ratio_result, indent=2)}
        
        请基于以上信息，撰写一份专业的财务分析简报。报告应涵盖：
        1. 整体财务状况概述。
        2. 盈利能力分析（重点关注毛利率和净利率）。
        3. 偿债能力与财务风险分析（重点关注资产负债率）。
        4. 成长性分析（重点关注收入增长率）。
        5. 主要发现与建议。
        
        请确保引用具体数据，并指出任何需要关注的异常或风险点。
        """
        
        response = await self.run(prompt=analysis_prompt)
        return response.content

3.3 集成Langfuse进行追踪与评估

为了监控智能体的每次运行并评估其表现，我们需要将Langfuse集成到Harness的调用链路中。Harness通常提供了与可观测性平台集成的接口或中间件。

# src/integrations/langfuse_integration.py
from langfuse import Langfuse
from langfuse.callback import CallbackHandler
from harness.integrations.base import BaseIntegration
from src.config import settings
import asyncio
from contextlib import asynccontextmanager

class LangfuseIntegration(BaseIntegration):
    """Langfuse集成类，用于追踪和评估Agent运行"""
    
    def __init__(self):
        self.langfuse_client = Langfuse(
            secret_key=settings.langfuse_secret_key,
            public_key=settings.langfuse_public_key,
            host=settings.langfuse_host
        )
        self.handler = CallbackHandler(
            client=self.langfuse_client,
            debug=False
        )
    
    async def on_agent_start(self, agent_name: str, session_id: str, input_data: dict):
        """Agent开始运行时调用，创建追踪"""
        trace = self.langfuse_client.trace(
            name=f"FinancialAnalysis - {agent_name}",
            session_id=session_id,
            input=input_data,
            metadata={"agent": agent_name}
        )
        # 可以将trace对象存储在上下文或任务本地变量中供后续步骤使用
        # 这里简化处理，实际项目中可能需要更复杂的上下文管理
        return trace
    
    async def on_tool_call(self, trace, tool_name: str, input_args: dict):
        """记录工具调用"""
        if trace:
            trace.span(
                name=tool_name,
                input=input_args,
                metadata={"type": "tool"}
            )
    
    async def on_llm_call(self, trace, model: str, prompt: str, completion: str):
        """记录LLM调用"""
        if trace:
            trace.generation(
                name="Financial Analysis Generation",
                model=model,
                input=prompt,
                output=completion,
                metadata={"model": model}
            )
    
    async def on_agent_end(self, trace, output: str, metrics: dict = None):
        """Agent运行结束时调用，提交追踪并记录输出和评估指标"""
        if trace:
            trace.output = output
            if metrics:
                trace.metadata = {**trace.metadata, **metrics}
            # 可以在这里触发自动评估（例如，调用另一个LLM对输出进行评分）
            # await self._trigger_evaluation(trace, output)
            self.langfuse_client.flush()  # 确保数据发送到Langfuse服务器

# 初始化全局集成实例
langfuse_integration = LangfuseIntegration()

接下来，我们需要修改Agent，使其在运行时接入这个集成。一种常见的方式是使用装饰器或中间件包装 run 方法。

# 对src/agents/financial_analyst.py进行补充
import uuid
from src.integrations.langfuse_integration import langfuse_integration

class FinancialAnalystAgent(Agent):
    # ... __init__ 部分保持不变 ...
    
    async def analyze_statement_with_tracing(self, file_path: str, user_id: str = "default_user") -> str:
        """
        带有完整追踪和评估的财务分析方法。
        
        Args:
            file_path: 财务报表文件路径。
            user_id: 用户标识，用于会话追踪。
        
        Returns:
            财务分析报告。
        """
        session_id = str(uuid.uuid4())
        input_data = {"file_path": file_path, "user_id": user_id}
        
        # 1. 开始追踪
        trace = await langfuse_integration.on_agent_start(
            agent_name=self.name,
            session_id=session_id,
            input_data=input_data
        )
        
        try:
            # 2. 解析数据（记录工具调用）
            await langfuse_integration.on_tool_call(trace, "parse_financial_statement", {"file_path": file_path})
            parse_result = await self.use_tool(
                tool_name="parse_financial_statement",
                arguments={"file_path": file_path}
            )
            if "error" in parse_result:
                output = f"数据解析错误：{parse_result['error']}"
                await langfuse_integration.on_agent_end(trace, output, {"status": "error"})
                return output
            
            financial_data = parse_result
            
            # 3. 计算比率（记录工具调用）
            await langfuse_integration.on_tool_call(trace, "calculate_financial_ratios", {"financial_data": "...[数据摘要]..."})
            ratio_result = await self.use_tool(
                tool_name="calculate_financial_ratios",
                arguments={"financial_data": financial_data}
            )
            
            # 4. 生成分析（记录LLM调用）
            analysis_prompt = f"""...同前..."""
            await langfuse_integration.on_llm_call(trace, self.model, analysis_prompt[:500] + "...", "")
            response = await self.run(prompt=analysis_prompt)
            output = response.content
            await langfuse_integration.on_llm_call(trace, self.model, analysis_prompt[:500] + "...", output[:500] + "...")
            
            # 5. 成功结束追踪
            await langfuse_integration.on_agent_end(
                trace, 
                output, 
                metrics={
                    "status": "success",
                    "data_periods": len(financial_data),
                    "ratios_calculated": len(ratio_result)
                }
            )
            return output
            
        except Exception as e:
            # 6. 异常结束追踪
            error_msg = f"智能体运行异常：{str(e)}"
            await langfuse_integration.on_agent_end(trace, error_msg, {"status": "exception", "error": str(e)})
            return error_msg

4. 完整实战：从数据到分析报告

现在，让我们将所有部分组合起来，运行一个端到端的示例。

4.1 准备示例财务数据

创建一个示例CSV文件 sample_financials.csv ，模拟一家公司连续四个季度的数据。

period,revenue,gross_profit,net_income,total_assets,total_liabilities,equity
2025-Q1,1000000,400000,150000,2000000,800000,1200000
2025-Q2,1200000,500000,180000,2200000,900000,1300000
2025-Q3,1150000,460000,160000,2100000,850000,1250000
2025-Q4,1300000,550000,200000,2400000,1000000,1400000

4.2 编写主执行脚本

创建一个主文件 main.py ，用于启动智能体并执行分析。

# main.py
import asyncio
import sys
from pathlib import Path
sys.path.append(str(Path(__file__).parent))

from src.agents.financial_analyst import FinancialAnalystAgent

async def main():
    """主函数：初始化智能体并分析财务报表"""
    
    # 1. 初始化智能体
    print("正在初始化财务分析智能体...")
    agent = FinancialAnalystAgent()
    
    # 2. 指定数据文件路径
    file_path = "sample_financials.csv"
    if not Path(file_path).exists():
        print(f"错误：找不到数据文件 '{file_path}'。请确保文件存在。")
        return
    
    # 3. 使用带追踪的分析方法
    print(f"开始分析文件: {file_path}")
    print("-" * 50)
    
    analysis_report = await agent.analyze_statement_with_tracing(
        file_path=file_path,
        user_id="demo_user_001"
    )
    
    print("财务分析报告：")
    print("-" * 50)
    print(analysis_report)
    print("-" * 50)
    print("分析完成！本次运行已被追踪至Langfuse平台。")

if __name__ == "__main__":
    asyncio.run(main())

4.3 运行与结果验证

在终端中运行脚本：

python main.py

预期你将看到类似以下的输出：

正在初始化财务分析智能体...
开始分析文件: sample_financials.csv
--------------------------------------------------
财务分析报告：
--------------------------------------------------
**财务分析简报：XYZ公司（2025财年）**

**1. 整体财务状况概述**
基于2025年四个季度的数据，公司展现出稳健的成长与盈利能力。总收入从Q1的1,000,000美元增长至Q4的1,300,000美元，增幅达30%。净资产也从1,200,000美元增长至1,400,000美元。

**2. 盈利能力分析**
- **毛利率**：全年维持在较高水平，介于40.0%至42.3%之间（Q4为42.3%），表明核心业务具有较强的成本控制与定价能力。
- **净利率**：从Q1的15.0%稳步提升至Q4的15.4%，显示公司在收入增长的同时，有效管理了运营费用和税负。

**3. 偿债能力与财务风险分析**
- **资产负债率**：在41.7%左右波动（Q4为41.7%），处于相对健康、稳健的水平。负债主要由经营性负债构成，长期偿债风险较低。

**4. 成长性分析**
- **收入增长率**：Q2环比增长20%，Q3略有回调（-4.2%），Q4重拾强劲增长（13.0%）。全年增长趋势积极，但需关注季度波动。

**5. 主要发现与建议**
- **优势**：盈利能力强，财务结构稳健。
- **关注点**：Q3收入小幅下滑，需结合市场环境分析原因。
- **建议**：维持当前的财务策略，可考虑将部分利润用于再投资以巩固增长势头，并持续监控季度收入波动。
--------------------------------------------------
分析完成！本次运行已被追踪至Langfuse平台。

4.4 在Langfuse平台查看追踪与评估

1. 登录你的Langfuse账户（云服务或自托管地址）。
2. 进入“Traces”页面，你应该能看到一条名为“FinancialAnalysis - FinancialAnalyst”的追踪记录。
3. 点击进入详情，可以清晰地看到完整的执行链路：
   • Agent Start ：记录了输入参数。
   • Tool Call (parse_financial_statement) ：记录了输入的文件路径。
   • Tool Call (calculate_financial_ratios) ：记录了输入的数据摘要。
   • LLM Generation ：记录了发送给模型的提示词（截断）和返回的分析报告。
   • Agent End ：记录了最终输出和自定义的指标（如 data_periods ）。
4. 你可以在该Trace上直接进行 人工评分 （例如，对报告准确性、有用性打分），或配置 自动化评估 （例如，使用另一个LLM判断报告是否包含关键指标）。

5. 企业级工程化扩展与最佳实践

一个可用的Demo与一个企业级应用之间的差距，主要体现在可维护性、安全性和扩展性上。

5.1 配置管理与环境隔离

最佳实践 ：严格区分开发、测试、生产环境。

• 创建多个 .env 文件： .env.development , .env.staging , .env.production 。
• 使用 pydantic-settings 根据 ENVIRONMENT 变量动态加载配置。
• 密钥使用Vault或云服务商密钥管理服务，而非直接写在 .env 文件中。

# 增强的config.py
import os
from pydantic_settings import BaseSettings
from pydantic import Field, validator

class Settings(BaseSettings):
    environment: str = Field("development", alias="ENVIRONMENT")
    openai_api_key: str = Field(..., alias="OPENAI_API_KEY")
    # ... 其他配置 ...
    
    @validator("environment")
    def validate_environment(cls, v):
        allowed = ["development", "staging", "production"]
        if v not in allowed:
            raise ValueError(f"ENVIRONMENT must be one of {allowed}")
        return v
    
    class Config:
        env_file = f".env.{os.getenv('ENVIRONMENT', 'development')}"
        secrets_dir = "/run/secrets"  # Docker Secrets支持

5.2 异步、重试与超时机制

生产环境网络不稳定，必须为所有外部调用（LLM API、工具函数）添加健壮的异常处理。

# src/utils/async_utils.py
import asyncio
from typing import Any, Callable, TypeVar
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
from openai import APIConnectionError, APIError

T = TypeVar('T')

def create_retry_decorator(max_attempts: int = 3):
    """创建用于LLM API调用的重试装饰器"""
    return retry(
        stop=stop_after_attempt(max_attempts),
        wait=wait_exponential(multiplier=1, min=2, max=10),
        retry=retry_if_exception_type((APIConnectionError, APIError, asyncio.TimeoutError)),
        reraise=True
    )

@create_retry_decorator()
async def reliable_llm_call(client, *args, **kwargs) -> Any:
    """带有重试和超时的LLM调用"""
    return await asyncio.wait_for(
        client.chat.completions.create(*args, **kwargs),
        timeout=30.0  # 设置30秒超时
    )

# 在Agent的run方法中，替换原始的client调用
# response = await self.client.chat.completions.create(...)
# 改为：
# response = await reliable_llm_call(self.client, ...)

5.3 数据安全与隐私合规

财务数据高度敏感，必须确保：

• 静态加密 ：存储的CSV文件、数据库中的中间数据必须加密。
• 传输安全 ：所有API调用必须使用HTTPS。
• 数据脱敏 ：在日志和追踪系统中，对敏感字段（如具体金额、客户信息）进行脱敏处理。可以在Langfuse集成层进行过滤。

# 在Langfuse集成中脱敏数据
async def on_tool_call(self, trace, tool_name: str, input_args: dict):
    sanitized_args = input_args.copy()
    if tool_name == "parse_financial_statement":
        # 脱敏文件路径中的敏感信息（示例）
        if "file_path" in sanitized_args:
            sanitized_args["file_path"] = "[REDACTED_PATH]"
    # ... 记录脱敏后的参数

5.4 构建评估体系与持续迭代

利用Langfuse的核心功能建立评估闭环：

1. 定义评估指标 ：在Langfuse项目中创建Score。
   • correctness （正确性）：输出是否包含事实错误？
   • completeness （完整性）：是否涵盖了所有要求的分析维度？
   • actionability （可操作性）：建议是否具体可行？
2. 混合评估方式 ：
   • 人工评估 ：业务专家定期对重要报告进行评分。
   • 模型评估 ：配置一个“裁判”LLM，根据规则对输出进行自动评分。
   • 自动化测试 ：对固定的输入数据集，断言输出必须包含某些关键词或数值范围。
3. 分析与迭代 ：定期查看Langfuse的Dashboard，分析得分趋势。针对低分项，优化提示词、工具逻辑或模型参数。

5.5 部署与监控

部署 ：使用Docker容器化你的智能体应用，并通过Kubernetes或云服务进行编排，确保高可用性。

# Dockerfile
FROM python:3.10-slim
WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry config virtualenvs.create false && poetry install --no-dev
COPY . .
CMD ["python", "main.py"]

监控 ：

• 业务监控 ：通过Langfuse监控每次调用的延迟、Token消耗和成本。
• 系统监控 ：使用Prometheus+Grafana监控容器资源使用率、API健康状态。
• 告警 ：设置当错误率超过阈值、平均响应时间过长或成本异常时触发告警。

6. 常见问题与排查思路

在开发和部署过程中，你可能会遇到以下典型问题。

7. 总结：从项目到平台

通过本教程，我们完成了一个基于Harness和Langfuse的企业级财务分析智能体从零到一的构建。这个过程清晰地展示了AI工程化的核心步骤：

1. 框架选型与搭建 ：使用Harness这类生产级框架，能快速构建结构清晰、易于维护的智能体应用，避免从零造轮子。
2. 领域能力封装 ：将财务专业知识固化为可复用的 Tool ，是智能体具备专业性的关键。
3. 可观测性集成 ：在开发初期就集成Langfuse，为评估和迭代打下数据基础，这是项目能否持续优化的生命线。
4. 生产就绪考量 ：配置管理、错误处理、安全合规、部署监控，这些是Demo与生产系统的分水岭。

下一步的探索方向 ：

• 复杂工作流 ：将单个智能体扩展为多智能体协作的工作流，例如，一个负责数据提取，一个负责风险识别，一个负责报告生成。
• 评估自动化 ：深入利用Langfuse的API，构建自动化的评估流水线，在每次代码更新后自动运行测试集并生成评估报告。
• 持续学习 ：利用Langfuse收集的高质量人工反馈，对智能体进行微调，使其分析能力越来越贴近顶尖财务专家的水平。

这个项目只是一个起点。真正的AI工程化之路，是将这个闭环流程——开发、评估、部署、监控、迭代——变成团队日常工作中稳定、可重复的一部分。当你能够系统化地管理和提升AI应用的质量时，它才真正从“实验项目”转变为“业务支柱”。