play-deepagents/README.md

# Network Search Agent

一个符合 LangGraph Studio 标准的网络搜索 Agent 项目,使用 DeepAgents 框架和 Tavily 搜索 API。

## 📁 项目结构

```
NetworkSearchAgent/
├── agent.py                      # ⭐ LangGraph 入口 (定义 agent)
├── langgraph.json               # ⭐ LangGraph 配置
├── pyproject.toml               # 依赖管理
├── .env.example                 # 环境变量模板
├── README.md                    # 完整文档
└── network_search_agent/        # Agent 包
    ├── __init__.py              # 包初始化
    ├── tools.py                 # 工具: internet_search
    └── prompts.py               # 提示词: SYSTEM_PROMPT
```

## ✨ 功能特性

### 保留的核心功能
- ✅ **网络搜索工具** (`internet_search`) - 使用 Tavily API
- ✅ **DeepSeek 模型集成** - 作为推理引擎
- ✅ **系统提示词** - 定义 Agent 行为
- ✅ **LangGraph Studio 兼容** - 可在 Studio 中可视化调试

### 移除的功能
- ❌ Sub Agent (子代理)
- ❌ Think Tool (思考工具)
- ❌ 其他高级特性

## 🚀 快速开始

### 1. 安装依赖

使用 pip 安装:
```bash
cd NetworkSearchAgent
pip install -e .
```

或使用 uv (推荐):
```bash
cd NetworkSearchAgent
uv pip install -e .
```

### 2. 配置环境变量

复制环境变量模板:
```bash
cp .env.example .env
```

编辑 `.env` 文件,填入你的 API 密钥:
```env
DEEPSEEK_API_KEY=your_deepseek_api_key_here
DEEPSEEK_BASE_URL=https://api.deepseek.com
TAVILY_API_KEY=your_tavily_api_key_here
```

#### 获取 API 密钥
- **DeepSeek**: 访问 [https://www.deepseek.com/](https://www.deepseek.com/)
- **Tavily**: 访问 [https://tavily.com/](https://tavily.com/)

### 3. 使用 LangGraph CLI 运行

#### 启动开发服务器
```bash
langgraph dev
```

这将启动 LangGraph Studio 服务器,你可以在浏览器中访问可视化界面。

#### 测试 Agent
```bash
langgraph test
```

## 🎯 使用 LangGraph Studio

### 启动 Studio
```bash
cd NetworkSearchAgent
langgraph dev
```

启动后,访问浏览器打开的 Studio 界面,你可以:
- 📊 可视化查看 Agent 的执行流程
- 🔍 调试每一步的输入输出
- 🧪 交互式测试 Agent 功能
- 📝 查看工具调用详情

### Studio 特性
- **实时可视化**: 查看 Agent 的思考过程和工具调用
- **断点调试**: 在关键节点暂停并检查状态
- **历史记录**: 回顾之前的对话和执行流程
- **性能分析**: 查看每步的耗时和资源使用

## 📝 代码说明

### 核心文件

#### 1. `langgraph.json`
LangGraph 配置文件,定义 Agent 入口:
```json
{
  "dependencies": ["."],
  "graphs": {
    "simple_agent": "./agent.py:agent"
  },
  "env": ".env"
}
```

#### 2. `agent.py`
主 Agent 定义文件:
```python
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent
from network_search_agent.prompts import SYSTEM_PROMPT
from network_search_agent.tools import internet_search

# 初始化模型
model = init_chat_model(
    model="deepseek:deepseek-chat",
    temperature=0.0
)

# 创建 Agent (仅包含基础工具,无 sub-agent)
agent = create_deep_agent(
    model=model,
    tools=[internet_search],
    system_prompt=SYSTEM_PROMPT,
)
```

#### 3. `network_search_agent/tools.py`
工具定义:
```python
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """网络搜索工具"""
    result = tavily_client.search(...)
    return result
```

#### 4. `network_search_agent/prompts.py`
系统提示词定义:
```python
SYSTEM_PROMPT = """你是一个智能助手...
"""
```

## 🔧 自定义配置

### 更换模型

编辑 `agent.py` 中的模型配置:

```python
# 使用 OpenAI
model = init_chat_model(
    model="openai:gpt-4",
    temperature=0.0
)

# 使用 Anthropic
model = init_chat_model(
    model="anthropic:claude-3-5-sonnet-20241022",
    temperature=0.0
)
```

### 添加新工具

1. 在 `network_search_agent/tools.py` 中定义新工具:
```python
def my_new_tool(param: str):
    """My new tool description"""
    # 工具实现
    return result
```

2. 在 `agent.py` 中添加到工具列表:
```python
agent = create_deep_agent(
    model=model,
    tools=[internet_search, my_new_tool],  # 添加新工具
    system_prompt=SYSTEM_PROMPT,
)
```

3. 在 `network_search_agent/__init__.py` 中导出:
```python
from network_search_agent.tools import internet_search, my_new_tool

__all__ = ["internet_search", "my_new_tool", ...]
```

### 自定义提示词

编辑 `network_search_agent/prompts.py`:
```python
SYSTEM_PROMPT = """你的自定义提示词...
"""
```

## 📚 LangGraph Studio 文档

详细文档请参考:
- [LangGraph Studio 官方文档](https://docs.langchain.com/oss/python/langgraph/studio)
- [LangGraph CLI 使用指南](https://docs.langchain.com/oss/python/langgraph/cli)

## 🆚 与完整版的区别

| 特性 | 简化版 (本项目) | 完整版 |
|------|----------------|--------|
| 网络搜索 | ✅ | ✅ |
| 基础对话 | ✅ | ✅ |
| 系统提示词 | ✅ | ✅ |
| LangGraph Studio | ✅ | ✅ |
| Sub Agent | ❌ | ✅ |
| Think Tool | ❌ | ✅ |
| 复杂工作流 | ❌ | ✅ |

## 🐛 常见问题

### Q: 如何查看 Agent 执行日志?
启动时使用 `langgraph dev --verbose` 查看详细日志。

### Q: 如何在 Studio 中测试?
1. 运行 `langgraph dev`
2. 打开浏览器访问显示的 URL
3. 在界面中输入测试问题

### Q: 依赖安装失败?
确保 Python 版本 >= 3.11,使用 uv 或创建虚拟环境:
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
pip install -e .
```

### Q: 如何部署到生产环境?
参考 [LangGraph Cloud 部署文档](https://docs.langchain.com/oss/python/langgraph/cloud)

## 📄 许可证

MIT License

## 🔄 更新日志

### v0.1.0 (2025-12-02)
- ✅ 初始版本
- ✅ 符合 LangGraph Studio 标准结构
- ✅ 实现基础 Agent 功能
- ✅ 集成网络搜索工具
- ✅ 移除 sub-agent 和 think tool