# 腾讯广告自动化投放 Agent 系统

基于 Reson Agent 框架（v0.3.0）和腾讯广告 Marketing API v3.0 的自动化投放系统。

## 系统架构

### 主 Agent + 6 个子 Agent

- **main**：投放决策中枢，任务拆解与全局调度
- **audience**：人群定向分析与策略制定
- **creative**：素材效果分析与优化建议
- **budget**：预算分配与出价优化
- **system_ops**：腾讯广告 API 操作执行
- **monitor**：实时异常检测与自动熔断
- **data_analyst**：数据查询与分析（只读）

### 业务场景

- 推广产品：小程序 + 公众号关注
- 营销目的：用户增长（拉新）
- 出价方式：oCPM（固定）
- 优化目标：关键页面访问、点击
- 人群定向：自有人群包 + 年龄定向

## 快速开始

### 1. 环境准备

```bash
# 安装依赖
pip install -r requirements.txt

# 配置环境变量
export TENCENT_AD_ACCESS_TOKEN="your_access_token"
export TENCENT_AD_ACCOUNT_ID="your_account_id"
```

### 2. 运行系统

```bash
cd /Users/liulidong/project/agent/Agent
python examples/auto_ad_placement/run.py
```

### 3. 示例任务

```
# 查询账户信息
> 查询账户 123456 的余额和今日消耗

# 创建广告
> 为小程序 xxx 创建测试广告，日预算 1 万，目标 CPA 50 元

# 优化投放
> 分析账户 123456 昨日投放效果，优化预算分配

# 监控熔断
> 检查账户 123456 是否有异常广告需要熔断
```

## 目录结构

```
examples/auto_ad_placement/
├── config.py              # 运行配置
├── run.py                 # 主入口
├── task.prompt            # 主 Agent 任务描述
├── presets.json           # 多 Agent 预设定义
├── tools/                 # 自定义工具
│   ├── ad_api.py          # 腾讯广告 API 封装
│   ├── data_query.py      # 数据仓库查询
│   ├── budget_calc.py     # 预算计算引擎
│   ├── audience_tools.py  # 人群定向工具
│   └── monitor_tools.py   # 监控告警工具
├── skills/                # 领域知识
│   ├── ad_domain.md       # 广告投放领域知识
│   ├── budget_strategy.md # 预算策略知识
│   ├── audience_strategy.md # 人群定向策略
│   ├── creative_strategy.md # 素材策略知识
│   └── monitor_rules.md   # 监控规则知识
├── prompts/               # 子 Agent 专用 prompt
│   ├── audience.prompt
│   ├── creative.prompt
│   ├── budget.prompt
│   ├── system_ops.prompt
│   └── monitor.prompt
└── outputs/               # 运行输出
```

## 腾讯广告 3.0 关键知识

### 层级结构（2层）

```
旧版（2.0）：计划（Campaign）→ 广告组（AdGroup）→ 创意（Creative）
新版（3.0）：广告（Ad）→ 创意（Dynamic Creative）
```

⚠️ **重要**：
- API 端点 `/v3.0/adgroups/add` 创建的是"广告"（业务概念），不是"广告组"
- 返回字段 `adgroup_id` 实际是广告 ID
- Campaign 层已完全移除

### 核心策略

- 旧策略：堆砌大量"广告+创意"组合（拼基建）
- 新策略：**少广告、多素材**（拼素材），系统自动优选

## 工具说明

### ad_api.py — 腾讯广告 API 封装

- `ad_create`：创建广告（3.0 顶层单位）
- `ad_update`：修改广告（出价/预算/定向/状态）
- `ad_batch_update_status`：批量修改状态
- `ad_get_list`：查询广告列表
- `ad_get_report`：获取数据报表
- `creative_create`：创建创意
- `creative_update`：修改创意
- `creative_get_report`：查询创意效果
- `account_get_info`：查询账户信息
- `audience_get_list`：查询人群包列表
- `asset_get_list`：查询素材库

### data_query.py — 数据查询

- `data_query`：多维度数据查询（账户汇总/广告明细/人群分析/素材效果/成本趋势）
- `data_aggregate`：数据聚合分析（趋势/环比/同比）

⚠️ **注意**：需要实现 `_query_warehouse()` 连接实际数据仓库

### budget_calc.py — 预算计算

- `budget_calculate`：计算预算分配方案（等额/ROI加权/性能加权）
- `budget_allocate`：执行预算分配

### audience_tools.py — 人群定向

- `audience_build_targeting`：生成 targeting 结构体
- `audience_recommend_targeting`：推荐最优定向组合

### monitor_tools.py — 监控告警

- `monitor_check_metrics`：检查指标异常
- `monitor_circuit_break`：执行熔断

## 开发指南

### 添加新工具

```python
# examples/auto_ad_placement/tools/my_tool.py
from agent.tools import tool, ToolResult

@tool(description="我的自定义工具")
async def my_custom_tool(param: str) -> ToolResult:
    # 实现逻辑
    return ToolResult(output="结果")
```

在 `run.py` 中导入：
```python
from examples.auto_ad_placement.tools.my_tool import my_custom_tool
```

### 添加新 Skill

```markdown
<!-- examples/auto_ad_placement/skills/my_skill.md -->
---
name: my-skill
description: 我的领域知识
---

## 使用场景
...
```

在 `config.py` 中添加到 skills 列表。

## 注意事项

1. **数据查询工具未实现**：`data_query.py` 中的 `_query_warehouse()` 需要连接实际数据仓库
2. **API 限制**：单账户 QPS 限制 10，批量操作单次最多 50 条
3. **单位转换**：出价和预算单位为分（1元 = 100分）
4. **审核时间**：普通素材 2-4 小时，节假日可能延长至 24 小时
5. **数据延迟**：实时数据 15-30 分钟，转化数据 1-2 小时

## 参考资料

- 腾讯广告 API 文档：https://developers.e.qq.com/v3.0/docs
- Reson Agent 框架：`agent/README.md`
- 计划文档：`~/.claude/plans/moonlit-soaring-turtle.md`

---

**最后更新**: 2026-04-07