# Qurio Python 后端（FastAPI + Agno）

本后端以 Agno SDK 为核心，实现与前端 **无感切换** 的对话与工具能力。

## 关键逻辑（当前 Agno 架构）

1. **模型选择**

- `provider == gemini`：使用 Agno 的 `Gemini` 模型类。
- **除 Gemini 外全部走 OpenAI‑compatible**：统一使用 `OpenAILike`（参见 Agno OpenAI‑like 文档）。
- 模型与 base_url 以请求参数为主，未传则用环境变量默认值。

2. **消息与流式**

- 不做角色映射（`developer` 会原样透传）。
- 流式输出通过 `Agent.run(stream=True, stream_events=True)` 转成 SSE JSON 事件：
  - `text / thought / tool_call / tool_result / done / error`

3. **工具体系（前端可选）**

- **本地自定义工具（local）**：`QurioLocalTools`（calculator / local*time / summarize_text / extract_text / json_repair / webpage_reader / interactive_form / Tavily*\* 等）。
- **Agno 内置工具（agno）**：按勾选加载 Toolkit：
  - TavilyTools / DuckDuckGoTools / ArxivTools / WikipediaTools / YFinanceTools
- **用户工具（custom）**：HTTP/MCP 工具通过 `build_user_tools_toolkit` 统一封装。

4. **存储**

- 当前 **不启用 Agno DB**（前端自行写入 Supabase）。

5. **CORS**

- 由 `AgentOS(cors_allowed_origins=...)` 与兜底中间件同时保证浏览器可访问。

---

## 主要文件用途（backend-python/src）

- `main.py`
  - FastAPI 应用入口，启动 AgentOS。

- `config.py`
  - 读取环境变量（HOST/PORT/CORS/DEBUG 等）。

- `services/agent_os_app.py`
  - 组装 FastAPI + AgentOS，注册路由，设置 CORS 与兜底响应。

- `services/agent_registry.py`
  - **核心模型/工具装配**：
    - 选择 `Gemini` 或 `OpenAILike`
    - 注入本地工具、Agno 工具、用户工具
    - 处理工具选择策略（`tool_choice`）

- `services/stream_chat.py`
  - **流式对话主服务**，将 Agno 事件转为 SSE JSON。
  - 支持本地时间自动注入与工具提示。

- `services/tool_registry.py`
  - 工具清单与分类：`LOCAL_TOOLS / AGNO_TOOLS / ALL_TOOLS`。

- `services/custom_tools.py`
  - 本地工具实现（安全计算、时间、摘要、网页读取、Tavily 搜索等）。

- `services/user_tools.py`
  - 用户工具封装（HTTP/MCP），支持参数模板、域名白名单、超时与大小限制。

- `services/tools.py`
  - 兼容旧逻辑的本地工具执行入口（仅认 local tools）。

- `services/generation.py`
  - 标题、相关问题、自动 agent 选择、research plan 等非流式生成。

- `routes/*.py`
  - 具体 API 端点（stream-chat / title / related-questions / research-plan / deep-research 等）。

---

## 相关配置（backend-python/.env）

- `HOST` / `PORT`
- `FRONTEND_URLS`（逗号分隔）
- `OPENAI_BASE_URL` / `OPENAI_MODEL`
- 其他 provider 的 base_url / model（如 siliconflow、glm、minimax 等）
- `TAVILY_API_KEY`

---

## 与前端约定

- SSE 数据格式不变（前端无感）。
- 工具列表通过 `/api/tools` 返回，按 `category` 分组：
  - `custom` = 自定义工具
  - `agno` = Agno 内置工具
  - 其他 = 本地工具分类（math/time/text/web/search...）