内容
---
title: FarmAssist
emoji: 🌾
colorFrom: green
colorTo: yellow
sdk: streamlit
sdk_version: "1.42.0"
app_file: app.py
pinned: false
---
# 🌾 FarmAssist — AI 农场顾问 为印度农民
> 多智能体AI助手，基于 **谷歌智能体开发工具包（ADK）** 和 **Gemini Vision** 构建。
> 帮助印度农民进行作物管理，市场价格查询，以及通过照片诊断病虫害。
[](https://python.org)
[](https://google.github.io/adk-docs/)
[](https://streamlit.io)
[](https://huggingface.co/spaces/shivam-hf/farmassist)
---
## 🌍 问题陈述
印度小农户农民（平均土地持有量：1.1 公顷）每季都会因以下原因损失大量收入：
- **农事操作时机不当** — 在雨水冲走投入之前喷洒或施肥
- **在错误的时间出售** — 在市场价格低迷时将产品带到集市
- **延迟病虫害应对** — 不知道疾病是什么或如何负担得起治疗，直到作物受损严重
获得农业推广员的机会有限（许多印度州每800名农民只有1名推广员）。FarmAssist 通过简单的聊天 + 照片界面，将人工智能咨询服务提供给农民。
---
## 🤖 为什么使用智能体？
单一的大型语言模型（LLM）提示无法很好地解决这个问题，因为：
- **领域分离很重要** — 作物建议，市场时机和病虫害诊断需要不同的专业知识和工具
- **多主题查询很常见** — "下雨了，价格很低 — 我应该喷洒还是出售？" 需要结合天气感知农业建议 和 市场数据
- **工具必须独立可测试** — 每个专业智能体都有自己的工具，测试用例和通过/失败标准
智能体架构将每个查询路由到正确的专业智能体（或多个智能体），并将它们的输出组合成一个连贯的答案。
---
## 🏗️ 架构
```
用户（Streamlit UI / CLI）
│
▼
┌─────────────────────────────────────────┐
│ 安全防护层 │
│ （提示注入过滤，路径 │
│ 遍历保护，长度检查） │
└──────────────────┬──────────────────────┘
│ 验证查询
▼
┌─────────────────────────────────────────┐
│ 协调智能体 │
│ （Gemini 2.0 Flash + Vision） │
│ 读取图像 → 描述 → 路由 │
└──────┬─────────────┬──────────┬─────────┘
│ │ │
智能体工具 智能体工具 智能体工具
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ 作物 │ │ 市场 │ │ 病虫害 │
│ 顾问 │ │ 观察 │ │ 侦察员 │
│ │ │ │ │ │
│ 作物_ │ │ 市场_ │ │ 获取病虫害_│
│ 建议() │ │ 建议() │ │治疗 │
└──────────┘ └──────────┘ └──────────┘
│
▼
┌─────────────────┐
│ MCP 服务器 │ ← 相同的工具通过
│ mcp_server.py │ 模型上下文协议暴露
└─────────────────┘
```
### 关键设计决策
| 决策 | 理由 |
|---|---|
| **`智能体工具`（不是`子智能体`）** | 给协调者功能调用控制 — 它可以在一次调用中为混合查询调用多个智能体 |
| **协调层视觉** | ADK 的 `智能体工具` 在智能体之间传递文本；图像仅对协调者可见，协调者描述图像后转发给病虫害侦察员 |
| **防护措施作为独立模块** | 安全逻辑独立可测试，并在查询到达LLM之前运行 |
| **MCP服务器与ADK智能体并行** | 通过模型上下文协议暴露相同的工具，因此任何MCP兼容的客户端都可以调用它们，而无需了解FarmAssist的内部架构 |
| **天气和价格的模拟数据** | 没有免费，可靠的Agmarknet/IMD API；架构设计允许替换为真实的API调用 |
---
## 📁 项目结构
```
farmassist/
├── agents/
│ ├── orchestrator.py # 根智能体 — 路由 + 视觉 + 合成
│ ├── crop_advisor.py # 天气感知作物管理建议
│ ├── market_watch.py # 市场价格查询和销售时机
│ ├── pest_scout.py # 病虫害诊断，从症状文本
│ └── __init__.py
├── security/
│ ├── guardrails.py # 输入验证（注入，遍历，长度）
│ ├── policy_server.py # 基于角色的工具允许列表
│ └── __init__.py
├── tests/
│ └── eval_harness.py # 非确定性评估套件
├── .github/
│ └── workflows/ci.yml # GitHub Actions CI（lint + import 检查）
├── app.py # Streamlit UI（主要部署接口）
├── main.py # CLI 入口点（智能体技能演示）
├── mcp_server.py # MCP 服务器（通过MCP协议暴露工具）
├── requirements.txt
└── README.md
```
---
## 🚀 本地设置和运行
### 先决条件
- Python 3.10+
- 谷歌 Gemini API 密钥（免费获取） **或** 启用了 Vertex AI 的 GCP 项目
### 1. 克隆和安装
```bash
git clone https://github.com/skjha08/farmassist.git
cd farmassist
pip install -r requirements.txt
```
### 2. 配置凭证
**选项 A — Gemini API 密钥（AI Studio，免费层）：**
```bash
cp .env.example .env
# 编辑 .env 并设置：
# GEMINI_API_KEY=您的密钥
```
**选项 B — Vertex AI（GCP，更高配额）：**
```bash
# 在 .env 中：
# GOOGLE_GENAI_USE_VERTEXAI=TRUE
# GOOGLE_CLOUD_PROJECT=您的项目ID
# GOOGLE_CLOUD_LOCATION=us-central1
gcloud auth application-default 登录
```
### 3. 运行 Streamlit UI
```bash
streamlit run app.py
```
在浏览器中打开 http://localhost:8501。
### 4. 运行 CLI（智能体技能演示）
```bash
python main.py
```
### 5. 运行 MCP 服务器
```bash
python mcp_server.py
# 启动一个stdio-transport MCP服务器，暴露crop_advice，
# market_advice，和 get_pest_treatment 作为MCP工具。
```
### 6. 运行评估套件
```bash
python tests/eval_harness.py
# 运行 3 个测试用例 × 3 次，并报告通过率。
# 需要有效的 Gemini / Vertex AI 凭证。
```
---
## 🧑🤝🧑 智能体能力
### 🌱 作物顾问
**工具：** `crop_advice(crop, location)`
返回天气感知的农业建议，包含三个具体行动项：
- 是否喷洒 / 施肥（或延迟）
- 排水检查说明
- 是否持有或将产品运往市场
### 📈 市场观察
**工具：** `market_advice(crop, location)`
返回当前市场价格与季节平均值的比较，并提供明确的持有/出售建议和具体的卢比/夸特尔数字。
### 🔬 病虫害侦察员
**工具：** `get_pest_treatment(symptoms)`
将症状描述（孔洞，斑点，枯萎，变色）映射到：
- 诊断（虫害损伤 / 真菌 / 枯萎 / 一般）
- 经济实惠的治疗方案（首先基于印楝油，化学品作为备用）
- 紧急程度指导
### 🛡️ 安全层
- **提示注入过滤器** — 在LLM接收之前阻止"忽略前一条指令"和越狱模式
- **路径遍历保护** — 验证图像文件路径
- **长度检查** — 拒绝超过2000字符的查询
- **基于角色的工具允许列表** — `policy_server.py` 定义每个角色可以调用哪些工具
### 🔌 MCP 服务器
`mcp_server.py` 通过 **模型上下文协议** 暴露所有三个工具函数，使它们可以从任何MCP兼容的客户端（Claude Desktop，ADK `MCPToolset`，Agents CLI）调用，而无需了解FarmAssist的内部多智能体结构。
---
## 🌐 直播演示
**Hugging Face Spaces:** https://huggingface.co/spaces/shivam-hf/farmassist
> ⚠️ 直播演示运行在 Gemini 免费层。如果您看到速率限制消息，请等待 30–60 秒并重试。
---
## 🛠️ 技术栈
| 组件 | 技术 |
|---|---|
| 智能体框架 | Google 智能体开发工具包（ADK）2.3.0 |
| LLM / Vision | Gemini 2.0 Flash（通过 Vertex AI 或 AI Studio） |
| MCP 协议 | `mcp` Python SDK ≥ 1.0 |
| UI | Streamlit |
| 部署 | Hugging Face Spaces |
| CI | GitHub Actions |
| 认证 | python-dotenv + GCP Application Default Credentials |
---
## 📜 环境变量
| 变量 | 是否必需 | 描述 |
|---|---|---|
| `GEMINI_API_KEY` | 如果使用 AI Studio | 来自 [aistudio.google.com](https://aistudio.google.com/) 的 API 密钥 |
| `GOOGLE_GENAI_USE_VERTEXAI` | 如果使用 Vertex | 设置为 `TRUE` 以使用 Vertex AI 代替 AI Studio |
| `GOOGLE_CLOUD_PROJECT` | 如果使用 Vertex | GCP 项目 ID |
| `GOOGLE_CLOUD_LOCATION` | 如果使用 Vertex | 地区（例如 `us-central1`） |
| `GEMINI_MODEL` | 否 | 模型覆盖。默认为 `gemini-2.0-flash` |
---
## 🔒 安全注意事项
**此仓库中不提交任何 API 密钥或凭证。**
`.env` 和 `ci-key.json` 被包含在 `.gitignore` 中。
在 HF Spaces 中，秘密通过 Space Secrets UI 设置，并在运行时作为环境变量注入。
