# ai_agents_demo

**Repository Path**: ailark/ai_agents_demo

## Basic Information

- **Project Name**: ai_agents_demo
- **Description**: AI Agent培训示例代码。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-19
- **Last Updated**: 2025-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 AI Agents Demo（CrewAI + Streamlit）

一个基于 CrewAI 与 Streamlit 的新闻搜集与分析助手。通过两个协作的 AI Agent（研究员与写作专家），自动检索指定主题的最新新闻并生成结构化的 Markdown 分析报告，同时在界面中实时展示 Agent 的工作与 LLM 交互日志。

## 功能亮点
- 双 Agent 协作：`研究员`负责检索与要点提取，`写作专家`负责整合与报告撰写。
- 工具接入：使用 `SerperDevTool` 进行高质量网络检索（需 `SERPER_API_KEY`）。
- 模型选择：支持 DeepSeek 模型（`deepseek-chat` / `deepseek-reasoner`），通过 CrewAI 的 `LLM` 接入。
- 实时日志：分面板展示 LLM 交互与 Agent 执行过程，便于观察推理链与动作。
- 一键运行：完整的 Streamlit 界面，输入密钥与主题后点击按钮即可生成报告。

## 目录结构
- `app.py`：主应用入口（Streamlit 页面与 CrewAI 编排逻辑）。
- `requirements.txt`：依赖清单。
- `LICENSE`：开源许可证（Apache 2.0）。
- `.gitignore`：Git 忽略规则。

## 环境要求
- 推荐 Python `3.10+`。
- 建议使用虚拟环境（`venv` 或 `conda`）。

## 安装与启动
1. 创建并激活虚拟环境（示例为 venv）：
   - `python -m venv .venv`
   - `source .venv/bin/activate`（macOS/Linux）或 `.\.venv\\Scripts\\activate`（Windows）
2. 安装依赖：
   - `pip install -r requirements.txt`
3. 运行应用：
   - `streamlit run app.py`
4. 浏览器自动打开页面（或访问终端输出的本地地址），在左侧边栏完成配置后点击按钮开始。

## 密钥配置说明
本项目不主动读取本地 `.env` 文件。密钥可通过以下两种方式提供：

- 方式 A：环境变量（适合本地或部署环境）
  - `DEEPSEEK_API_KEY`：DeepSeek 的 API Key
  - `SERPER_API_KEY`：Serper 的 API Key
  - 可在终端设置：
    - macOS/Linux：`export DEEPSEEK_API_KEY=your_key && export SERPER_API_KEY=your_key`
    - Windows（PowerShell）：`$env:DEEPSEEK_API_KEY="your_key"; $env:SERPER_API_KEY="your_key"`

- 方式 B：在应用侧边栏输入（适合快速试用）
  - 启动后，在左侧输入框中以密码形式输入两项密钥即可。

> 兼容说明：代码在设置 `DEEPSEEK_API_KEY` 后，会同时设置 `OPENAI_API_KEY` 与 `OPENAI_BASE_URL` 指向 DeepSeek，使部分 OpenAI 风格库可以直接调用 DeepSeek API。

## 使用步骤
- 在左侧边栏：
  - 输入 `DEEPSEEK_API_KEY` 与 `SERPER_API_KEY`（若未通过环境变量提供）。
  - 选择 DeepSeek 模型（`deepseek-chat` 或 `deepseek-reasoner`）。
  - 勾选是否开启“实时日志”。
- 在页面主体：
  - 输入“新闻主题”（默认示例：`中国电力市场新型储能技术发展`）。
  - 点击 `🚀 开始搜集与撰写报告` 按钮。
- 输出：
  - 页面将展示一份 Markdown 格式的分析报告。
  - 两个日志面板分别显示 LLM 交互与 Agent 工作过程，便于观察与调试。

## 工作流程概述
- Agent 设置：
  - `研究员（Senior Industry Researcher）`：使用 `SerperDevTool` 搜索主题相关最新 5 条权威新闻，提取标题、来源与关键摘要。
  - `写作专家（Professional Tech Writer）`：整合研究员输出，撰写约 800 字的结构化分析报告（Markdown）。
- 任务编排：
  - 使用 `Crew(process=Process.sequential)` 顺序执行任务：先检索后写作。
- 日志机制：
  - 自定义 `DualStreamlitLogger` 将标准输出流实时推送至 Streamlit 面板，抽取并展示与 LLM 相关的交互日志。

## 常见问题与排查
- 报错“请在左侧输入 API Keys”：
  - 未提供 `DEEPSEEK_API_KEY` 或 `SERPER_API_KEY`。请通过环境变量或侧边栏输入。
- DeepSeek 连接失败或返回 401：
  - 请确认密钥有效，或检查网络与代理设置；必要时更换模型或稍后重试。
- 检索结果为空或质量不佳：
  - 更换检索关键词，或确保 `SERPER_API_KEY` 额度充足。
- 本地 `.env` 未生效：
  - 设计上不读取 `.env`；请改用环境变量或侧边栏输入。

## 可扩展方向
- 增加更多角色（如数据分析师、图表生成器），形成多 Agent 协作。
- 将流程改为并行：`Process.parallel`（需注意依赖关系）。
- 引入持久化与缓存，提高追踪与复用能力。
- 针对特定领域扩展检索策略与写作模板。

## 许可协议
本项目采用 Apache-2.0 许可证，详见 `LICENSE` 文件。

## 致谢
- [CrewAI](https://github.com/joaomdmoura/crewai)：Agent 编排与任务流。
- [Streamlit](https://streamlit.io/)：快速构建交互式数据应用。
- [DeepSeek](https://www.deepseek.com/)：高性能语言模型服务。
- [Serper](https://serper.dev/)：Google 搜索 API（SerperDevTool）。