Abhishek-Singh004/Ambient-Expense-AI-Agent
GitHub: Abhishek-Singh004/Ambient-Expense-AI-Agent
基于 ADK 2.0 图工作流的环境事件驱动型企业费用审批 AI Agent，实现自动审计、PII 脱敏、LLM 风险审查与 Human-in-the-Loop 升级审批。
Stars: 1 | Forks: 0
# 🌌 Vibecoded 环境事件驱动费用审批 Agent
欢迎使用 **Ambient Expense Approval Agent**！本项目实现了一个自主财务助手，它在后台静默运行，监听企业费用触发事件（通过 Google Cloud Pub/Sub），自动对交易进行审计，清除敏感数据，防止恶意 prompt 注入，并将高价值决策升级到交互式、设计精美的 **Human-in-the-Loop (HITL) Manager Portal**。
该 Agent 基于最先进的 **Agent Development Kit (ADK 2.0)** 图工作流构建，代表了一种现代、弹性的企业自动化合规方案。
## 📊 Agent 结构图
该工作流使用 ADK 工作流节点构建为有向图，处理自动审批、PII 清除、prompt 注入防御、自动化风险审查以及 human-in-the-loop 升级。
```
graph TD
START([START]) --> parse_input[parse_input
Decode Base64 & Parse JSON] parse_input -->|Amount < $100| record_auto_approve[record_auto_approve
Auto-Approve Expense] parse_input -->|Amount >= $100| security_checkpoint[security_checkpoint
Redact PII & Detect Injection] security_checkpoint -->|Clean Description| llm_risk_review[llm_risk_review
LLM Auditor Risk Review] security_checkpoint -->|Security Flagged| human_approval[human_approval
HITL Pause / Portal Review] llm_risk_review --> human_approval human_approval --> record_human_decision[record_human_decision
Record Approval/Rejection] record_auto_approve --> END([END]) record_human_decision --> END style START fill:#0F172A,stroke:#38BDF8,stroke-width:2px,color:#fff style END fill:#0F172A,stroke:#38BDF8,stroke-width:2px,color:#fff style security_checkpoint fill:#3F1E29,stroke:#F43F5E,stroke-width:2px,color:#fff style human_approval fill:#064E3B,stroke:#10B981,stroke-width:2px,color:#fff style llm_risk_review fill:#1E293B,stroke:#64748B,stroke-width:1px,color:#fff style parse_input fill:#1E293B,stroke:#64748B,stroke-width:1px,color:#fff style record_auto_approve fill:#1E293B,stroke:#64748B,stroke-width:1px,color:#fff style record_human_decision fill:#1E293B,stroke:#64748B,stroke-width:1px,color:#fff ``` ## 📁 项目结构 ``` ambient-expense-agent/ ├── expense_agent/ # Core agent code │ ├── agent.py # Main graph nodes and ADK workflow definitions │ ├── config.py # Application thresholds and model name configuration │ ├── fast_api_app.py # FastAPI server serving Pub/Sub triggers & UI APIs │ └── ui.html # Premium HTML5/CSS3/JS Human-in-the-Loop review dashboard ├── tests/ │ ├── eval/ # Local evaluation suite │ │ ├── datasets/ │ │ │ └── basic-dataset.json # Synthetic evaluation cases │ │ ├── eval_config.yaml # Custom LLM-as-judge metric templates │ │ ├── generate_traces.py # Local ADK trace generator script │ │ └── run_local_evaluation.py # Local grading runner with retry logic │ ├── integration/ # Pytest integration tests │ └── unit/ # Pytest unit tests ├── artifacts/ # Generated traces and evaluation reports ├── Makefile # Automation targets ├── pyproject.toml # Python packages and project configuration └── .env # Environment credentials and keys ``` ## ⚡ 核心功能 1. **Ambient 服务**：在本地端口 `8080` 上运行。接收 Base64 编码的 GCP Pub/Sub 推送消息，解码 payload，规范化订阅路径以保持会话可读性，并触发 ADK 图。 2. **PII 与 Prompt 注入防御**： * *PII 清除*：作为第一道防线运行。在将文本提交给 LLM 审查模型之前，自动将社会安全号码 (`SSN`) 和信用卡 (`CC`) 编辑为 `[REDACTED_SSN]` 和 `[REDACTED_CC]`。 * *Prompt 注入检测*：扫描对抗性输入（例如 *"ignore previous instructions"*）。被标记的交易将完全绕过基于 AI 的风险审查，以避免越狱，触发安全警报，并直接升级为人工审查以进行拒绝。 3. **HITL Manager Portal**：一个高级的分屏仪表板，具有精心设计的暗色模式配色、毛玻璃布局和 Inter 字体。它列出了待审查和已完成的日志，可视化风险等级量表（满分为 10 分的得分）并突出显示相关因素，显示安全标志，并配有管理员审批控制功能。 4. **稳健的评估**：包含一个本地评估脚本 (`run_local_evaluation.py`)，由 `gemini-flash-lite-latest` 驱动，带有速率限制休眠和稳健的重试循环，以防止瞬时的 `503 UNAVAILABLE` 或 `429` 错误。 ## ⚙️ 设置与运行 ### 要求 * Python 3.10+ * [uv](https://docs.astral.sh/uv/getting-started/installation/) Python 包管理器 ### 安装 同步依赖并初始化虚拟环境： ``` make install ``` ### 配置凭证 在根目录下创建一个 `.env` 文件： ``` GEMINI_API_KEY=your-gemini-api-key-here ``` ### 启动服务 在端口 `8080` 上启动 FastAPI uvicorn 服务器： ``` make run-ambient ``` 打开浏览器并访问 **`http://localhost:8080/`** 以进入交互式 HITL 审批门户。 ## 📡 Webhook 触发 要模拟一个需要手动审查（金额 >= $100）的费用报告的 Pub/Sub 触发器： ``` curl -X POST http://127.0.0.1:8080/ \ -H "Content-Type: application/json" \ -d '{ "message": { "data": "eyJhbW91bnQiOiAxNTAuMCwgInN1Ym1pdHRlciI6ICJib2JAY29tcGFueS5jb20iLCAiY2F0ZWdvcnkiOiAidHJhdmVsIiwgImRlc2NyaXB0aW9uIjogIkZsaWdodCB0aWNrZXQiLCAiZGF0ZSI6ICIyMDI2LTA2LTI1In0=", "messageId": "msg-99999", "publishTime": "2026-06-25T03:00:00Z" }, "subscription": "test-sub" }' ``` ## 📊 API 与 UI 端点 | 端点 | 方法 | 响应 | 描述 | | :--- | :--- | :--- | :--- | | `/` | `GET` | `HTML` | 提供交互式审查仪表板门户 | | `/ui` | `GET` | `HTML` | 仪表板门户的别名 | | `/` | `POST` | `JSON` | 接收 Pub/Sub 推送通知并启动工作流 | | `/apps/expense_agent/trigger/pubsub` | `POST` | `JSON` | 别名 Pub/Sub 推送 webhook | | `/api/sessions` | `GET` | `JSON` | 列出按状态分类的会话（*pending*、*approved*、*rejected*） | | `/api/sessions/{session_id}/resume` | `POST` | `JSON` | 根据决策和评论恢复暂停的会话 | ## 🧪 测试与本地评估 ### 运行 Pytest 套件 运行单元、集成和 UI 端点模拟测试： ``` uv run pytest ``` ### 运行本地评估 使用 `routing_correctness` 和 `security_containment` LLM-as-judge 指标，跨 5 个合成案例（涵盖自动审批、手动审批、PII 泄露和 prompt 注入）评估 Agent。 1. **生成 traces**： make generate-traces 2. **评估 traces**： make grade 最终的评估结果摘要表和评论将打印到您的控制台，并且完整的 JSON 报告将导出到 `artifacts/grade_results/local_eval_results.json`。
Decode Base64 & Parse JSON] parse_input -->|Amount < $100| record_auto_approve[record_auto_approve
Auto-Approve Expense] parse_input -->|Amount >= $100| security_checkpoint[security_checkpoint
Redact PII & Detect Injection] security_checkpoint -->|Clean Description| llm_risk_review[llm_risk_review
LLM Auditor Risk Review] security_checkpoint -->|Security Flagged| human_approval[human_approval
HITL Pause / Portal Review] llm_risk_review --> human_approval human_approval --> record_human_decision[record_human_decision
Record Approval/Rejection] record_auto_approve --> END([END]) record_human_decision --> END style START fill:#0F172A,stroke:#38BDF8,stroke-width:2px,color:#fff style END fill:#0F172A,stroke:#38BDF8,stroke-width:2px,color:#fff style security_checkpoint fill:#3F1E29,stroke:#F43F5E,stroke-width:2px,color:#fff style human_approval fill:#064E3B,stroke:#10B981,stroke-width:2px,color:#fff style llm_risk_review fill:#1E293B,stroke:#64748B,stroke-width:1px,color:#fff style parse_input fill:#1E293B,stroke:#64748B,stroke-width:1px,color:#fff style record_auto_approve fill:#1E293B,stroke:#64748B,stroke-width:1px,color:#fff style record_human_decision fill:#1E293B,stroke:#64748B,stroke-width:1px,color:#fff ``` ## 📁 项目结构 ``` ambient-expense-agent/ ├── expense_agent/ # Core agent code │ ├── agent.py # Main graph nodes and ADK workflow definitions │ ├── config.py # Application thresholds and model name configuration │ ├── fast_api_app.py # FastAPI server serving Pub/Sub triggers & UI APIs │ └── ui.html # Premium HTML5/CSS3/JS Human-in-the-Loop review dashboard ├── tests/ │ ├── eval/ # Local evaluation suite │ │ ├── datasets/ │ │ │ └── basic-dataset.json # Synthetic evaluation cases │ │ ├── eval_config.yaml # Custom LLM-as-judge metric templates │ │ ├── generate_traces.py # Local ADK trace generator script │ │ └── run_local_evaluation.py # Local grading runner with retry logic │ ├── integration/ # Pytest integration tests │ └── unit/ # Pytest unit tests ├── artifacts/ # Generated traces and evaluation reports ├── Makefile # Automation targets ├── pyproject.toml # Python packages and project configuration └── .env # Environment credentials and keys ``` ## ⚡ 核心功能 1. **Ambient 服务**：在本地端口 `8080` 上运行。接收 Base64 编码的 GCP Pub/Sub 推送消息，解码 payload，规范化订阅路径以保持会话可读性，并触发 ADK 图。 2. **PII 与 Prompt 注入防御**： * *PII 清除*：作为第一道防线运行。在将文本提交给 LLM 审查模型之前，自动将社会安全号码 (`SSN`) 和信用卡 (`CC`) 编辑为 `[REDACTED_SSN]` 和 `[REDACTED_CC]`。 * *Prompt 注入检测*：扫描对抗性输入（例如 *"ignore previous instructions"*）。被标记的交易将完全绕过基于 AI 的风险审查，以避免越狱，触发安全警报，并直接升级为人工审查以进行拒绝。 3. **HITL Manager Portal**：一个高级的分屏仪表板，具有精心设计的暗色模式配色、毛玻璃布局和 Inter 字体。它列出了待审查和已完成的日志，可视化风险等级量表（满分为 10 分的得分）并突出显示相关因素，显示安全标志，并配有管理员审批控制功能。 4. **稳健的评估**：包含一个本地评估脚本 (`run_local_evaluation.py`)，由 `gemini-flash-lite-latest` 驱动，带有速率限制休眠和稳健的重试循环，以防止瞬时的 `503 UNAVAILABLE` 或 `429` 错误。 ## ⚙️ 设置与运行 ### 要求 * Python 3.10+ * [uv](https://docs.astral.sh/uv/getting-started/installation/) Python 包管理器 ### 安装 同步依赖并初始化虚拟环境： ``` make install ``` ### 配置凭证 在根目录下创建一个 `.env` 文件： ``` GEMINI_API_KEY=your-gemini-api-key-here ``` ### 启动服务 在端口 `8080` 上启动 FastAPI uvicorn 服务器： ``` make run-ambient ``` 打开浏览器并访问 **`http://localhost:8080/`** 以进入交互式 HITL 审批门户。 ## 📡 Webhook 触发 要模拟一个需要手动审查（金额 >= $100）的费用报告的 Pub/Sub 触发器： ``` curl -X POST http://127.0.0.1:8080/ \ -H "Content-Type: application/json" \ -d '{ "message": { "data": "eyJhbW91bnQiOiAxNTAuMCwgInN1Ym1pdHRlciI6ICJib2JAY29tcGFueS5jb20iLCAiY2F0ZWdvcnkiOiAidHJhdmVsIiwgImRlc2NyaXB0aW9uIjogIkZsaWdodCB0aWNrZXQiLCAiZGF0ZSI6ICIyMDI2LTA2LTI1In0=", "messageId": "msg-99999", "publishTime": "2026-06-25T03:00:00Z" }, "subscription": "test-sub" }' ``` ## 📊 API 与 UI 端点 | 端点 | 方法 | 响应 | 描述 | | :--- | :--- | :--- | :--- | | `/` | `GET` | `HTML` | 提供交互式审查仪表板门户 | | `/ui` | `GET` | `HTML` | 仪表板门户的别名 | | `/` | `POST` | `JSON` | 接收 Pub/Sub 推送通知并启动工作流 | | `/apps/expense_agent/trigger/pubsub` | `POST` | `JSON` | 别名 Pub/Sub 推送 webhook | | `/api/sessions` | `GET` | `JSON` | 列出按状态分类的会话（*pending*、*approved*、*rejected*） | | `/api/sessions/{session_id}/resume` | `POST` | `JSON` | 根据决策和评论恢复暂停的会话 | ## 🧪 测试与本地评估 ### 运行 Pytest 套件 运行单元、集成和 UI 端点模拟测试： ``` uv run pytest ``` ### 运行本地评估 使用 `routing_correctness` 和 `security_containment` LLM-as-judge 指标，跨 5 个合成案例（涵盖自动审批、手动审批、PII 泄露和 prompt 注入）评估 Agent。 1. **生成 traces**： make generate-traces 2. **评估 traces**： make grade 最终的评估结果摘要表和评论将打印到您的控制台，并且完整的 JSON 报告将导出到 `artifacts/grade_results/local_eval_results.json`。
标签：AI智能体, 事件驱动架构, 对称加密, 工作流自动化, 数据脱敏, 自动化审计, 财务合规, 逆向工具