# AI Agent 智能代理系统

## 概述

AI Agent是一个智能代理系统，能够理解用户需求并**自主选择和调用工具**完成任务。你只需要用自然语言描述需求，Agent会自动：

1. 理解你的意图
2. 提取关键词或分类
3. 选择合适的工具获取数据
4. 分析数据
5. 给出总结和建议

## 核心特性

### 🤖 自主决策
Agent会根据用户查询自动选择最合适的工具组合，无需手动指定。

### 🔧 工具集成
内置4个工具函数：
- `extract_search_keywords` - 提取搜索关键词
- `get_creative_guidance` - 获取创作指导数据
- `search_douyin_videos` - 搜索抖音视频
- `analyze_video_data` - 分析视频数据

### 📝 提示词驱动
通过修改 `prompts/agent_prompt.md` 就能控制Agent的行为逻辑。

### 🔄 迭代执行
Agent会多次调用工具，直到完成任务或达到最大迭代次数。

## 快速开始

### 方式一：API接口（推荐）

启动服务：
```bash
python api.py
```

调用Agent接口：
```bash
curl -X POST "http://localhost:8001/api/agent" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "帮我分析一下游戏类视频的热门趋势"
  }'
```

### 方式二：命令行

```bash
python ai_agent.py --query "帮我分析一下游戏类视频的热门趋势"
```

## 使用示例

### 示例1：分析分类趋势

**用户查询**：
```
帮我分析一下游戏类视频的热门趋势
```

**Agent执行流程**：
1. 识别用户想要"游戏"分类的数据
2. 调用 `get_creative_guidance(category="游戏")`
3. 调用 `analyze_video_data(videos=..., focus="热门趋势")`
4. 总结热门标签、热词、内容特征
5. 给出创作建议

**API调用**：
```bash
curl -X POST "http://localhost:8001/api/agent" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "帮我分析一下游戏类视频的热门趋势"
  }'
```

### 示例2：获取创作建议

**用户查询**：
```
我想做美食相关的内容，给我一些建议
```

**Agent执行流程**：
1. 识别用户需要"美食"分类的创作建议
2. 调用 `get_creative_guidance(category="美食")`
3. 调用 `analyze_video_data(videos=..., focus="创作建议")`
4. 分析高互动内容的特征
5. 给出具体的创作建议

**API调用**：
```bash
curl -X POST "http://localhost:8001/api/agent" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "我想做美食相关的内容，给我一些建议"
  }'
```

### 示例3：分析特定关键词

**用户查询**：
```
王者荣耀的视频现在什么内容最火？
```

**Agent执行流程**：
1. 识别关键词"王者荣耀"
2. 先调用 `get_creative_guidance(category="游戏")` 获取游戏类数据
3. 如果需要更具体的数据，调用 `search_douyin_videos(keyword="王者荣耀")`
4. 调用 `analyze_video_data` 分析数据
5. 总结最火的内容类型

**API调用**：
```bash
curl -X POST "http://localhost:8001/api/agent" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "王者荣耀的视频现在什么内容最火？"
  }'
```

### 示例4：多分类对比

**用户查询**：
```
对比一下游戏和美食两个分类的热门趋势
```

**Agent执行流程**：
1. 识别需要对比"游戏"和"美食"两个分类
2. 调用 `get_creative_guidance(category="游戏")`
3. 调用 `get_creative_guidance(category="美食")`
4. 分别调用 `analyze_video_data` 分析两个分类
5. 对比分析结果，给出差异和建议

## API响应格式

```json
{
  "success": true,
  "final_answer": "## 📊 数据概览\n...\n## 🔥 关键发现\n...",
  "iteration": 3,
  "tool_calls": [
    {
      "iteration": 1,
      "tool_name": "get_creative_guidance",
      "arguments": {"category": "游戏"},
      "result": {...}
    },
    {
      "iteration": 2,
      "tool_name": "analyze_video_data",
      "arguments": {"videos": [...], "focus": "热门趋势"},
      "result": {...}
    }
  ],
  "error": null
}
```

## 自定义Agent行为

### 修改提示词

编辑 `prompts/agent_prompt.md` 来控制Agent的行为：

```markdown
# AI Agent 系统提示词

你是一个智能的抖音数据分析助手...

## 工作流程

当用户提出需求时，你应该：

### 1. 理解用户意图
...

### 2. 制定执行计划
...

### 3. 执行工具调用
...
```

### 添加新工具

在 `ai_agent.py` 中添加新工具：

```python
# 1. 定义工具函数
async def your_new_tool(param1: str, param2: int) -> Dict:
    """工具描述"""
    # 实现逻辑
    return {"success": True, "data": ...}

# 2. 在 create_agent() 中注册工具
def create_agent() -> AIAgent:
    agent = AIAgent(model="qwen-plus")
    
    agent.register_tool(
        name="your_new_tool",
        func=your_new_tool,
        description="工具的详细描述，AI会根据这个描述决定何时使用",
        parameters={
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "参数1的描述"
                },
                "param2": {
                    "type": "integer",
                    "description": "参数2的描述"
                }
            },
            "required": ["param1", "param2"]
        }
    )
    
    return agent
```

### 修改工具选择逻辑

在 `prompts/agent_prompt.md` 中添加新的场景：

```markdown
## 工作流程

### 2. 制定执行计划

**场景D：用户需要XXX**
- 使用 `your_new_tool` 做XXX
- 使用 `analyze_video_data` 分析结果
- 总结发现
```

## 高级用法

### 1. 控制迭代次数

```bash
curl -X POST "http://localhost:8001/api/agent" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "分析游戏类视频",
    "max_iterations": 5
  }'
```

### 2. 使用不同模型

```bash
curl -X POST "http://localhost:8001/api/agent" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "分析游戏类视频",
    "model": "qwen-max"
  }'
```

### 3. 自定义提示词文件

```bash
curl -X POST "http://localhost:8001/api/agent" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "分析游戏类视频",
    "system_prompt_file": "prompts/custom_agent_prompt.md"
  }'
```

## Python代码集成

```python
import asyncio
from ai_agent import create_agent

async def main():
    # 创建Agent
    agent = create_agent()
    
    # 运行Agent
    result = await agent.run(
        user_input="帮我分析一下游戏类视频的热门趋势",
        system_prompt_file="prompts/agent_prompt.md",
        max_iterations=10
    )
    
    if result["success"]:
        print(result["final_answer"])
        print(f"\n工具调用次数: {len(result['tool_calls'])}")
    else:
        print(f"执行失败: {result['error']}")

asyncio.run(main())
```

## 工作原理

### Function Calling流程

```
用户输入
    ↓
AI理解意图
    ↓
选择工具并生成参数
    ↓
执行工具函数
    ↓
将结果返回给AI
    ↓
AI决定：继续调用工具 or 给出最终答案
    ↓
返回结果给用户
```

### 示例执行日志

```
用户查询: 帮我分析一下游戏类视频的热门趋势

[迭代 1] 调用工具: get_creative_guidance
参数: {"category": "游戏"}
结果: {"success": true, "total_count": 50, "videos": [...]}

[迭代 2] 调用工具: analyze_video_data
参数: {"videos": [...], "focus": "热门趋势"}
结果: {"success": true, "summary": {...}, "high_engagement_videos": [...]}

[迭代 3] 生成最终答案
总迭代次数: 3
工具调用次数: 2
```

## 支持的分类

- 全部
- 美食
- 旅行
- 泛生活
- 汽车
- 科技
- 游戏
- 二次元

## 常见问题

### Q: Agent会调用哪些工具？
A: Agent会根据用户查询自动选择。你可以在 `prompts/agent_prompt.md` 中定义选择逻辑。

### Q: 如何控制Agent的行为？
A: 修改 `prompts/agent_prompt.md` 文件，定义不同场景下的工具选择策略。

### Q: 可以添加自己的工具吗？
A: 可以！在 `ai_agent.py` 中定义工具函数并注册即可。

### Q: Agent会无限循环吗？
A: 不会，有 `max_iterations` 参数限制最大迭代次数（默认10次）。

### Q: 如何调试Agent？
A: 查看返回结果中的 `tool_calls` 字段，可以看到每次工具调用的详细信息。

## 与普通分析接口的区别

| 特性 | 普通分析接口 | Agent接口 |
|------|------------|----------|
| 数据获取 | 需要手动先获取数据 | 自动获取数据 |
| 工具选择 | 需要手动调用不同接口 | 自动选择工具 |
| 分析深度 | 单次分析 | 多轮迭代分析 |
| 使用难度 | 需要了解API | 自然语言即可 |
| 灵活性 | 固定流程 | 动态调整 |

## 最佳实践

1. **清晰的查询**：查询越具体，Agent执行越准确
   - ✅ "分析游戏类视频的热门趋势"
   - ❌ "帮我看看"

2. **合理的期望**：Agent适合数据分析任务，不适合创作内容
   - ✅ "分析什么内容最火"
   - ❌ "帮我写一个视频脚本"

3. **提示词优化**：根据实际使用情况优化 `agent_prompt.md`

4. **工具扩展**：根据需求添加新工具，让Agent更强大

## 下一步

- 查看 [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md) 了解整体架构
- 修改 [prompts/agent_prompt.md](prompts/agent_prompt.md) 自定义行为
- 在 [ai_agent.py](ai_agent.py) 中添加新工具
- 访问 http://localhost:8001/docs 查看API文档