auto_put_ad — 项目结构文档
定位: 腾讯广告自动化投放多 Agent 协作系统
最后更新: 2026-07-16
一、项目概述
auto_put_ad 是一个基于 Reson Agent 框架的多 Agent 广告投放系统，面向腾讯广告 Marketing API v3.0。系统由 8 个专业 sub-agent 组成，通过主 Agent 统一调度，覆盖预算/出价优化、受众定向、创意策略、监控告警、系统运维、数据分析等投放全链路。
当前成熟度
| Agent |
状态 |
说明 |
| main |
✅ 就绪 |
任务分发中枢 |
| budget |
✅ 就绪 |
预算约束下的出价调整 |
| execute |
✅ 就绪 |
审批后执行 API 操作 |
| audience |
🟡 部分就绪 |
定向推荐可用，A/B 测试待实现 |
| data_analyst |
🟡 部分就绪 |
基础查询可用，深度分析待实现 |
| creative |
🔴 未就绪 |
创意策略框架已搭建 |
| monitor |
🔴 未就绪 |
监控规则已定义，实时检测待实现 |
| system_ops |
🔴 未就绪 |
API 运维操作框架已搭建 |
与 auto_put_ad_mini 的关系: auto_put_ad_mini 是本项目中「监控调控 Agent」角色的独立落地版本，实际已演进出更完整的决策 + 创建双业务线。本项目当前的核心可用链路是 budget → execute 出价调整。
二、目录结构
examples/auto_put_ad/
│
├── run.py # 🔵 分析入口：交互式 Agent CLI
├── run_execute.py # 🟢 执行入口：审批后执行 API 操作
├── config.py # 运行配置（3 套 RunConfig + 工具白名单）
├── task.prompt # 主 Agent 任务描述
├── presets.json # 8 个 sub-agent 预设定义
├── odps_module.py # ODPS（MaxCompute）数据仓库客户端
├── test_budget.py # 出价调整独立测试脚本
│
├── README.md # 项目概览
├── TODO.md # 任务追踪（P0/P1/P2）
├── BID_ADJUSTMENT_README.md # 出价调整系统深度文档
├── EXECUTION_GUIDE.md # 生产部署与执行指南
├── IMPLEMENTATION_SUMMARY.md # 实现总结
│
├── configs/
│ └── budget_strategy_v1.json # 策略配置（阈值/决策矩阵/出价边界/保护规则）
│
├── docs/
│ ├── budget_decision_framework.md # 预算决策框架（scale_ratio、2×2 矩阵、保护机制）
│ ├── budget_strategy_detail.md # 预算策略详解
│ └── 腾讯广告智能投放策略研究-参考.md # 行业策略参考
│
├── prompts/ # 各 Agent 系统提示词
│ ├── main.prompt # 主调度 Agent
│ ├── budget.prompt # 预算/出价优化专家
│ ├── execute.prompt # 执行 Agent
│ ├── audience.prompt # 受众定向专家
│ ├── creative.prompt # 创意/素材专家
│ ├── monitor.prompt # 监控告警
│ └── system_ops.prompt # API 运维操作
│
├── skills/ # 领域知识（注入 Agent 上下文）
│ ├── ad_domain.md # 腾讯广告 3.0 平台知识
│ ├── budget_strategy.md # 预算/出价决策知识
│ ├── audience_strategy.md # 受众定向策略
│ ├── creative_strategy.md # 创意生命周期管理
│ └── monitor_rules.md # 异常检测规则
│
└── tools/ # 自定义工具（@tool 装饰器）
├── __init__.py
├── ad_api.py # 腾讯广告 API v3.0 封装（13 个工具）
├── data_query.py # ODPS 数据查询（3 个工具）
├── budget_calc.py # 出价计算引擎（6 个工具）
├── audience_tools.py # 受众定向工具（2 个工具）
├── monitor_tools.py # 监控工具（2 个工具）
├── execute_agent.py # 执行编排（1 个工具）
└── strategy_config.py # 策略配置管理（3 个工具）
三、入口点与执行流程
3.1 两个入口
| 入口 |
文件 |
用途 |
模型 |
工具范围 |
| 分析入口 |
run.py |
交互式分析，制定出价调整方案 |
qwen/qwen3.5-plus-02-15 |
ANALYSIS_TOOLS（只读+计算） |
| 执行入口 |
run_execute.py |
读取已审批的方案，执行 API 操作 |
qwen/qwen3.5-plus-02-15 (temp=0.1) |
EXECUTION_TOOLS（含写操作） |
3.2 分析流程（run.py）
用户输入："今天小程序预算 10 万"
│
▼
┌──────────────────────────────────────┐
│ Main Agent (投放决策中枢) │
│ System Prompt: prompts/main.prompt │
│ Skills: ad_domain.md │
│ Tools: ANALYSIS_TOOLS + agent tool │
└──────────────────────────────────────┘
│ 理解意图 → 分派 sub-agent
▼
┌──────────────────────────────────────┐
│ Budget Agent (预算出价Agent) │
│ System Prompt: prompts/budget.prompt│
│ Skills: ad_domain, budget_strategy │
│ │
│ 7 步工作流： │
│ ① load_strategy_config() 加载策略配置│
│ ② get_account_summary() 拉 ODPS 数据│
│ ③ 战略判断（周末？促销？是否调阈值） │
│ ④ compute_budget_thresholds() 分位数 │
│ ⑤ classify_ads() 2×2 分类 │
│ ⑥ compute_bid_adjustment() 出价方案 │
│ ⑦ 展示方案 → 等待用户确认 │
└──────────────────────────────────────┘
│ 用户确认后
▼
bid_adjustment_execute() → 批量 API 调用
│
▼
输出: outputs/adjustment_plan_YYYYMMDD_HHMMSS.xlsx
3.3 执行流程（run_execute.py）
用户输入："执行最新方案"
│
▼
自动发现 outputs/ 下最新的 Excel 方案文件
│
▼
┌──────────────────────────────────────┐
│ Execute Agent (投放执行系统) │
│ System Prompt: prompts/execute.prompt│
│ Skills: ad_domain, budget_strategy, │
│ monitor_rules │
│ Tools: EXECUTION_TOOLS │
└──────────────────────────────────────┘
│
▼
execute_adjustment_plan():
① 加载方案（Excel → 决策列表）
② 验证：冷启动跳过 / 赔付保护 / 出价边界 / 15% 振幅上限
③ dry_run=True → 仅输出模拟报告
④ dry_run=False → 执行：
a. 出价调整（increase/decrease）→ ad_update()
b. 广告关停（close）→ ad_batch_update_status()
c. 执行后监控 → monitor_check_metrics()
⑤ 输出执行报告
3.4 数据流架构
ODPS (MaxCompute) 腾讯广告 API (api.e.qq.com/v3.0)
├── creative_detail ├── /adgroups/update
├── ad_put_tencent_ad ├── /adgroups/add
├── ad_put_tencent_creative_day └── /dynamic_creatives/add
├── ad_put_tencent_creative_data_day
└── ad_put_tencent_account
│ ▲
▼ │
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ data_query.py│ → │ budget_calc │ → │ ad_api.py │
│ (ODPS SQL) │ │ (计算引擎) │ │ (API 调用) │
└──────────────┘ └──────────────┘ └──────────────┘
│ │
▼ ▼
pandas DataFrame 决策矩阵查找 → [action, ratio]
效率分 = fission0_count / cost
百分位阈值 (P70/P30 ROI, P50 消耗)
2×2 分类 (ROI × 消耗)
四、核心架构设计
4.1 策略驱动架构
所有决策参数外置在 configs/budget_strategy_v1.json，LLM 可在运行时通过 update_strategy_config() 调整策略（如周末放宽 ROI 阈值），变更自动版本化管理：
{
"thresholds": {
"roi_high_percentile": 0.70,
"roi_low_percentile": 0.30,
"cost_mid_percentile": 0.50,
"valid_ad_min_open_count": 100
},
"decision_matrix": {
"aggressive_scale_down": {
"high_high": ["keep", 0.0],
"mid_high": ["decrease", -0.10],
"low_low": ["close", 0.0]
}
// ... 5 种策略 × 6 个象限
},
"protection": {
"cold_start": { "enabled": true, "hours": 48, "min_conversions": 6 },
"compensation": { "enabled": true, "min_conversions": 6, "cpa_deviation": 0.20 }
}
}
4.2 决策框架（5 步）
| 步骤 |
操作 |
产出 |
| ① 全局策略 |
scale_ratio = 今日预算 ÷ 昨日消耗 |
aggressive_scale_down / moderate_scale_down / maintain / moderate_scale_up / aggressive_scale_up |
| ② 样本过滤 |
排除 open_count < 100 的广告 |
有效广告池 |
| ③ 分位数计算 |
ROI P70/P30 + 消耗 P50 |
动态阈值（非固定值） |
| ④ 2×2 分类 |
ROI 高/中/低 × 消耗 高/低 |
6 个象限 |
| ⑤ 矩阵查找 |
策略 × 象限 → [action, ratio] |
keep / increase / decrease / close / observe |
4.3 保护机制（按优先级）
| 优先级 |
机制 |
规则 |
| 🔴 最高 |
冷启动保护 |
创建 < 48h 或转化 < 6 → 强制 observe |
| 🟠 高 |
赔付保护 |
转化 3-5 次 → 改为 observe，等积累到 6 次申请赔付 |
| 🟡 中 |
出价边界 |
截断到 [10, 10000] 分 |
| 🟢 低 |
振幅上限 |
单次调整 ≤ 15%；超过需拆阶梯执行（间隔 ≥ 2h） |
4.4 Multi-Agent 协作
presets.json 定义了 8 个 sub-agent：
main ──分派──▶ budget ← 当前可用
├──▶ audience ← 部分可用
├──▶ creative ← 未就绪
├──▶ system_ops ← 未就绪
├──▶ monitor ← 未就绪
└──▶ data_analyst← 部分可用
execute ←── 独立入口，不通过 main 调度
五、工具清单
ad_api.py — 腾讯广告 API 封装（13 个工具）
| 工具 |
API 端点 |
说明 |
ad_create |
POST /adgroups/add |
创建广告 |
ad_update |
POST /adgroups/update |
更新广告（出价/状态） |
ad_batch_update_status |
POST /adgroups/update (batch) |
批量更新广告状态 |
ad_get_list |
GET /adgroups/get |
查询广告列表 |
ad_get_report |
GET /daily_reports/get |
广告报表 |
creative_create |
POST /dynamic_creatives/add |
创建动态创意 |
creative_get_list |
GET /dynamic_creatives/get |
查询创意列表 |
creative_update |
POST /dynamic_creatives/update |
更新创意 |
creative_get_report |
GET /daily_reports/get |
创意报表 |
asset_get_list |
GET /assets/get |
查询资产列表 |
audience_get_list |
GET /custom_audiences/get |
查询人群包 |
account_get_info |
GET /advertiser/get |
查询账户信息 |
data_query.py — ODPS 数据查询（3 个工具）
| 工具 |
说明 |
data_query |
通用 ODPS SQL 查询（含模板：creative_detail, account_summary, ad_detail 等） |
data_aggregate |
数据聚合查询 |
get_ad_current_status |
查询广告当前状态（出价/预算/定向） |
budget_calc.py — 出价计算引擎（6 个工具）
| 工具 |
说明 |
get_ad_performance |
拉取广告昨日效率数据 |
get_account_summary |
拉取账户汇总数据 |
compute_budget_thresholds |
计算分位数阈值（P70/P30/P50） |
classify_ads |
2×2 象限分类（ROI × 消耗） |
compute_bid_adjustment |
计算出价调整方案 |
bid_adjustment_execute |
批量执行出价调整 |
六、配置说明
config.py 定义了三套 RunConfig：
| 配置 |
用途 |
Temperature |
Max Iterations |
MAIN_CONFIG |
主分析 Agent |
0.3 |
50 |
BUDGET_CONFIG |
预算/出价 sub-agent |
0.3 |
30 |
EXECUTE_CONFIG |
执行 Agent |
0.1 |
50 |
工具白名单：
ANALYSIS_TOOLS: 只读查询 + 计算工具（不含 ad_create/ad_update 等写操作）EXECUTION_TOOLS: 全量工具（含所有写操作）
七、关键设计原则
- 策略外置: 决策参数在 JSON 配置文件中，LLM 可运行时调整并版本化管理
- 两段式执行: 分析（run.py）与执行（run_execute.py）分离，中间有人工审批环节
- 保护优先: 冷启动 → 赔付 → 边界 → 振幅，四层保护从高到低依次生效
- 用出价控制消耗: oCPM 模式下通过 bid 调整影响 eCPM → 竞价胜率 → 消耗量，而非直接设 day_amount
- 非线性认知: 降价效果放大（-10% 出价 ≈ -15~25% 消耗），需警惕"掉量悬崖"
