Agent/examples/auto_put_ad

腾讯广告自动化投放 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. 环境准备

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

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

2. 运行系统

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：执行熔断

开发指南

添加新工具

# 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 中导入：

from examples.auto_ad_placement.tools.my_tool import my_custom_tool

添加新 Skill

<!-- 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