内容
# 分解智能代理 🏠
**自主的西班牙房地产估价代理** — 将地址转换为完整的估价 + 翻新投资回报率文件（PDF），约30秒，基于**官方西班牙开放数据**，而非大型语言模型的猜测。
为 **Google for Startups AI Agents Challenge — Track 3 (重构)** 而构建：[Decomind](https://decomind.es) 的生产文件（Azure Functions）重构为 Google Cloud 原生代理架构。
> 🔗 **在线演示：** https://decomind-agent-ui-ajrpcon4fq-ew.a.run.app
> *(输入地址或选择示例，观看 9 个工具调用实时流，下载 PDF)*
---
## 功能
给定一个房产（地址、面积、状况），代理自主地：
1. **地理编码** 地址（OpenStreetMap）
2. 拉取**官方地籍数据** — 建设年份、用途、参考（Catastro）
3. 获取**实际交易价格** 按邮政编码（Notariado — 实际的公证销售，黄金标准）
4. 与**官方评估价值** 进行交叉检查（MITMA）
5. 使用**享乐模型** 计算价值（6 个校准因素）
6. 建立**逐房间翻新预算**
7. 计算**投资回报率** 和结论
8. 渲染带有图表的**品牌 PDF**
大型语言模型**编排**；确定性代码**计算**。每个数字都可追溯到官方来源，并且可重现。
## 架构
```
浏览器 → Cloud Run（网页）→ ADK 代理（Gemini 3.5 Flash，Vertex AI）
│ 编排
┌──────────┬──────────┬────┴─────┬───────────┬────────────┐
地理编码 地籍 公证 市场研究 翻新 文件 PDF ← 6 MCP 服务器（Cloud Run）
│ │ │ │ │ │
OpenStreetMap 地籍 公证 MITMA 费率 reportlab→GCS
```
13 个联合 Google Cloud 服务，无需下载密钥（OIDC + IAM）。同一个代理也部署在 **Vertex AI 代理引擎** （托管，带有游乐场）。
## 技术栈
`ADK 2.1` · `Gemini 3.5 Flash (Vertex AI)` · `MCP` · `Cloud Run` ·
`代理引擎` · `Cloud Build` · `Artifact Registry` · `IAM/OIDC` ·
`Cloud Storage` · `Cloud Trace` · `FastAPI` · `FastMCP`
## 数据源（官方、免费、无爬虫）
| 来源 | 内容 | 类型 |
|---|---|---|
| **Notariado** | 按邮政编码的实际销售价格 | 实际交易 |
| **MITMA** | 评估价值 | 官方参考 |
| **Catastro** | 年份、面积、用途 | 物理记录 |
## 快速入门（本地）
```bash
python -m venv .venv && . .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
pip install -e .
cp .env.example .env # 设置您的 GCP 项目
python -m agent.main # 烟雾测试
```
运行评估套件（针对真实官方 API）：
```bash
python -m evals.run # 5 个案例，55 个检查
```
## 仓库布局
```
agent/ ADK 代理（编排器）+ 指令
mcp_servers/ 6 个 MCP 工具服务器（地理编码、地籍、公证、
市场研究 [+ 享乐模型]、翻新、文件 PDF）
evals/ 可重现的评估套件（100%，与真实 API 对比）
frontend/ FastAPI 网页 UI，带有实时工具调用流（SSE）
scripts/ 部署脚本（Cloud Run、Agent Engine）+ 数据解析器
docs/ 架构、FAQ、控制台导航、商业案例
```
## 文档
- [`docs/arquitectura-resumen.md`](docs/arquitectura-resumen.md) — 架构，3 个级别（+ Azure 等价物）
- [`docs/system-overview.md`](docs/system-overview.md) — 完整的技術概述 + 逐步示例
- [`docs/faq-tecnico.md`](docs/faq-tecnico.md) — 技术 FAQ（为什么使用 MCP、安全、数据、业务）
- [`docs/google-cloud-manual.md`](docs/google-cloud-manual.md) — GCP 服务解释
- [`docs/business-case.md`](docs/business-case.md) — 商业案例
## 生产就绪性
- **可观察性：** Cloud Logging + Trace；实时工具调用在 UI 中流式传输
- **防护措施：** 输入/输出验证器，源协议检查带有人工审查标志，确定性配置（`temperature=0`）
- **评估：** 可重现的套件（100%）针对真实官方 API
- **安全：** 联邦身份（OIDC），最小特权 IAM，零密钥
- **成本：** 缩放至零，约 €0.005 每文件
## 已知限制（路线图）
个别真实可比物（Idealista Data / 财产登记）是路线图 M2 — 当前来源是按区域划分的官方汇总。渲染和（V1 中存在）是未来的附加项。
---
_与 Decomind 生产环境隔离（在 Azure 上运行）。参见 [`docs/isolation-rules.md`](docs/isolation-rules.md)。_
