适用场景：乘客已支付成功，但订单状态仍停留在 WAIT_PAY，系统需自动审核是否存在状态、支付幂等、事务一致性风险。
本文带你从 空白文件夹 开始，手把手搭建一套 可运行的企业级 Agent 审核系统，并最终接入 真实大模型（智谱 AI 免费版），实现智能审核。

---

📦 前置准备

• 操作系统：Windows（本文以 Windows 为例，Mac/Linux 命令类似）

• Python 版本：3.8+（建议 3.10+）

• 代码编辑器：PyCharm / VS Code 均可

• 网络：能访问国内镜像源（清华/阿里），无需翻墙

• 智谱 AI 账号：用于获取免费 API Key（https://open.bigmodel.cn）

---

🗂️ 第一步：创建项目目录与虚拟环境

打开终端（CMD / PowerShell），执行以下命令：

bash

# 1. 进入桌面
cd C:\Users\你的用户名\Desktop

# 2. 创建项目根目录并进入
mkdir agent-audit-system
cd agent-audit-system

# 3. 创建后端目录
mkdir backend
cd backend

# 4. 创建 Python 虚拟环境
python -m venv .venv

# 5. 激活虚拟环境（Windows）
.venv\Scripts\activate

激活成功后，终端提示符前会出现 (.venv)。

---

🔧 第二步：安装基础依赖（解决代理问题）

由于很多电脑配置了系统代理，直接 pip 会报错。先清除代理环境变量：

bash

set HTTP_PROXY=
set HTTPS_PROXY=

然后使用清华源安装必要库：

bash

pip install fastapi uvicorn[standard] pydantic python-dotenv -i https://pypi.tuna.tsinghua.edu.cn/simple

如果清华源仍不通，可换阿里云 HTTP 源：

bash

pip install fastapi uvicorn[standard] pydantic python-dotenv -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

出现 Successfully installed ... 即表示成功。

---

📁 第三步：创建项目结构

在 backend 目录下，我们需要以下文件夹和文件：

text

backend/
├── main.py
├── .env                        (稍后创建)
├── app/
│   ├── __init__.py
│   ├── api/
│   │   ├── __init__.py
│   │   └── routes.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   └── audit.py
│   ├── llm/
│   │   ├── __init__.py
│   │   └── client.py
│   └── agents/
│       ├── __init__.py
│       └── status_agent.py

一次性创建所有目录和空 __init__.py 文件：

bash

mkdir app
cd app
mkdir api schemas llm agents
cd ..

# 创建所有 __init__.py（Windows 用 echo. 创建空文件）
echo. > app\__init__.py
echo. > app\api\__init__.py
echo. > app\schemas\__init__.py
echo. > app\llm\__init__.py
echo. > app\agents\__init__.py

---

📝 第四步：编写核心代码

以下每个文件都需要在对应位置创建并粘贴代码。

4.1 主入口 main.py

python

from dotenv import load_dotenv
load_dotenv()  # 加载 .env 中的环境变量

from fastapi import FastAPI
from app.api.routes import router

app = FastAPI(title="企业级Agent审核系统", version="1.0.0")
app.include_router(router)

@app.get("/")
async def root():
    return {"message": "Agent审核系统已启动，请访问 /docs 查看API文档"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

4.2 数据模型 app/schemas/audit.py

python

from pydantic import BaseModel
from typing import Optional, List

class AuditRequest(BaseModel):
    order_id: str
    user_id: str
    payment_id: Optional[str] = None
    amount: float
    current_status: str
    expected_status: str = "PAID"

class AuditResult(BaseModel):
    agent_name: str
    passed: bool
    reason: str
    confidence: float

class AuditResponse(BaseModel):
    trace_id: str
    risk_score: float
    passed: bool
    results: List[AuditResult]
    recommendation: str

4.3 LLM 客户端（先写模拟版，后续替换） app/llm/client.py

python

import json

class LLMClient:
    def __init__(self, api_key: str = None, model: str = "mock"):
        pass

    def chat(self, prompt: str, system_prompt: str = None) -> str:
        # 模拟 AI 逻辑：检测 WAIT_PAY 与 PAID 的关系
        if "WAIT_PAY" in prompt and "PAID" in prompt:
            result = {
                "passed": False,
                "reason": "订单状态为 WAIT_PAY，但预期为 PAID，可能存在状态更新事务未提交或支付回调丢失。",
                "confidence": 0.88
            }
        else:
            result = {
                "passed": True,
                "reason": "订单状态与预期一致，未发现明显风险。",
                "confidence": 0.95
            }
        return json.dumps(result, ensure_ascii=False)

4.4 审核 Agent app/agents/status_agent.py

python

import json
from app.llm.client import LLMClient

class StatusAuditAgent:
    def __init__(self):
        self.llm = LLMClient()

    def audit(self, order_id: str, current_status: str, expected_status: str) -> dict:
        prompt = f"""
你是一个订单状态审核专家。请判断订单状态是否存在不一致风险。

订单ID: {order_id}
当前状态: {current_status}
期望状态: {expected_status}

请输出 JSON:
{{"passed": boolean, "reason": string, "confidence": float (0~1)}}
只输出 JSON。
"""
        response = self.llm.chat(prompt, "你是一个严谨的AI助手。")
        try:
            return json.loads(response)
        except:
            return {"passed": False, "reason": "AI返回异常", "confidence": 0.0}

4.5 API 路由 app/api/routes.py

python

from fastapi import APIRouter
import uuid
from app.schemas.audit import AuditRequest, AuditResponse, AuditResult
from app.agents.status_agent import StatusAuditAgent

router = APIRouter(prefix="/api/v1/audit", tags=["订单审核"])
agent = StatusAuditAgent()

@router.post("/order", response_model=AuditResponse)
async def audit_order(request: AuditRequest):
    trace_id = str(uuid.uuid4())
    ai_result = agent.audit(
        request.order_id,
        request.current_status,
        request.expected_status
    )
    result = AuditResult(
        agent_name="StatusAuditAgent",
        passed=ai_result.get("passed", False),
        reason=ai_result.get("reason", "未知原因"),
        confidence=ai_result.get("confidence", 0.0)
    )
    risk_score = 0.0 if result.passed else 0.75
    recommendation = "无需处理" if result.passed else "建议人工复核订单状态"
    return AuditResponse(
        trace_id=trace_id,
        risk_score=risk_score,
        passed=result.passed,
        results=[result],
        recommendation=recommendation
    )

---

▶️ 第五步：启动模拟版，验证骨架

在终端（确保位于 backend 目录，且虚拟环境已激活）执行：

bash

python main.py

看到如下输出即成功：

text

INFO:     Uvicorn running on http://127.0.0.1:8000

打开浏览器访问 http://127.0.0.1:8000/docs，即可看到 Swagger 文档。点击 POST /api/v1/audit/order → Try it out，输入：

json

{
  "order_id": "ORD123",
  "user_id": "U001",
  "payment_id": "PAY456",
  "amount": 99.90,
  "current_status": "WAIT_PAY"
}

点击 Execute，会返回模拟审核结果。至此，骨架完全跑通。

---

🤖 第六步：接入真实 AI（智谱免费模型）

现在将模拟 LLM 替换为真实大模型，实现智能审核。

6.1 获取智谱 API Key

• 访问 https://open.bigmodel.cn

• 注册登录，进入控制台 → API Keys → 创建 API Key，复制 sk-xxxxx。

6.2 安装 OpenAI 兼容库

回到终端，清除代理，安装 openai：

bash

set HTTP_PROXY=
set HTTPS_PROXY=
pip install openai -i https://pypi.tuna.tsinghua.edu.cn/simple

6.3 替换 app/llm/client.py 为真实版

将原文件内容替换为以下代码：

python

import os
from openai import OpenAI

class LLMClient:
    def __init__(self, api_key: str = None, model: str = "glm-4-flash"):  # 免费模型
        self.api_key = api_key or os.getenv("ZHIPU_API_KEY")
        if not self.api_key:
            raise ValueError("请在 .env 中设置 ZHIPU_API_KEY")
        self.client = OpenAI(
            api_key=self.api_key,
            base_url="https://open.bigmodel.cn/api/paas/v4/"
        )
        self.model = model

    def chat(self, prompt: str, system_prompt: str = None) -> str:
        messages = []
        if system_prompt:
            messages.append({"role": "system", "content": system_prompt})
        messages.append({"role": "user", "content": prompt})
        response = self.client.chat.completions.create(
            model=self.model,
            messages=messages,
            temperature=0.3,
            max_tokens=1024
        )
        return response.choices[0].message.content

6.4 配置环境变量

在 backend 目录下新建 .env 文件（注意前面有点），写入：

text

ZHIPU_API_KEY=sk-你的真实Key

6.5 重启服务，体验真 AI

再次运行 python main.py，用相同测试数据调用接口。这次返回的 reason 将是智谱大模型实时生成的、逻辑严谨的根因分析，而不再是固定字符串。

---

🧠 第七步（进阶展望）：接入 Eino 框架

Eino 是字节跳动开源的 Go 语言 AI 应用框架，适合构建高性能、可编排的企业级应用。如果未来你将系统重构为 Go + Eino，你的 Python 组件会映射为：

Python 组件	Go + Eino 组件
main.py (FastAPI)	main.go (Hertz/Gin)
routes.py	Gin 路由 + Handler
status_agent.py	Eino 的 adk.ChatModelAgent
client.py	Eino 的 ChatModel 组件（可插拔）
工具函数	实现 BaseTool 接口
流程控制	Eino 的 Graph / Workflow 编排

接入 Eino 可带来更好的并发性能、可视化的流程编排和人机协同能力，适合长期演进。

---

✅ 总结

通过本教程，你已完成了：

• ✅ 从零创建 Python 虚拟环境

• ✅ 构建 FastAPI 项目骨架

• ✅ 编写数据模型、路由、Agent、LLM 客户端

• ✅ 运行模拟审核系统

• ✅ 接入真实大模型（智谱免费 API）

• ✅ 了解了未来接入 Eino 的方向

现在你拥有一个 可扩展的、智能的订单审核系统。后续可在此基础上增加更多 Agent（幂等性、事务一致性）、引入 RAG 检索历史案例、集成 MCP 工具标准化等，使其真正成为企业级解决方案。

---

有任何问题欢迎留言交流，祝你编码愉快！ 🚀