Gumloop 功能规格 - Per-Chat Credit Warnings

初始上下文

功能: 管理员可为单条 Agent 对话设信用阈值，超限时 Agent 暂停并创建 Action Request（HITL）请求批准才能继续
版本起源: v10.5.0 "Telegraph Cove" (2026-06-29)
解决的问题: 长对话（含 subagent、code sandbox、background action）不知不觉烧光信用，用户没有成本控制抓手——直到月底账单才发现。组织级限额太粗，需"单对话可控、超限可决策"的中间粒度
战略动机: 成本可控性是企业 Agent 进生产的硬需求。Credit Warnings 把成本控制变成 HITL 决策点——既控成本，又不打断高价值长任务
评分: 6/13（战略1 护城河1 用户2 复杂度1 创新1）[初始7→质疑-1→最终6] · 🔶 用户提级生成

1. 概览

背景：成本控制粒度演进

┌──────────────────────────────────────────────────────────────────────┐
│   组织级告警 (v9.x)          单对话级阈值 (v10.5.0)                       │
│   ┌──────────────┐           ┌──────────────┐                          │
│   │ 用量达 75%/90%│           │ 单对话达 5000 │                          │
│   │ → 发邮件通知   │           │ → Agent 暂停  │                          │
│   │ (被动告知)     │           │ → HITL 审批   │                          │
│   │               │           │ → 批准才继续  │                          │
│   └──────────────┘           └──────────────┘                          │
│   "事后惊讶账单"             "事中决策点"                                  │
└──────────────────────────────────────────────────────────────────────┘

目标

精细到单对话的成本可控——不再因一条失控对话烧光预算
成本控制变人机协同决策——超限不是硬停，而是"问用户要不要继续"
可按角色/Agent 差异化配置——实验 Agent 低阈值，生产 Agent 高阈值

2. 核心机制 [文档已验证]

配置位：Custom Roles

官方文档：Admins and Security role holders can set per-chat credit warnings through Custom Roles。阈值不是全局开关，而是绑定到企业角色。不同角色可设不同阈值——"实习生角色" 1000 credits、"工程师角色" 10000 credits。

触发与暂停机制

┌─────────────────────────────────────────────────────────────────┐
│   Agent 对话执行中 → 每次工具调用/AI 推理后累计本对话 credit 消耗    │
│         │                                                       │
│         ▼ < 阈值 ──────────> 继续执行                              │
│         ▼ ≥ 阈值（如 5000）                                       │
│   ┌─────────────────┐                                            │
│   │ Agent 暂停       │ ──> 走 v10.0.0 HITL 审批流                  │
│   │ 创建 Action      │      渠道：App 内通知 / Slack DM / 聊天线程   │
│   │ Request          │                                            │
│   └─────────────────┘                                            │
│         │                                                       │
│         ▼ 用户响应                                                │
│   批准 → 继续    |    拒绝 → 终止                                  │
└─────────────────────────────────────────────────────────────────┘

与 HITL（v10.0.0）的深度联动

Credit Warnings 复用 v10.0.0 Human-in-the-Loop 全套基础设施：Action Request 创建、多渠道送达（App/Slack/聊天线程）、暂停/恢复机制、拒绝行为（Agent 调整方法或终止）。

计费完整性 [文档已验证]

单对话消耗完整计入：AI 推理 + 工具调用 + 后台动作（Reflections enrichment、Evaluations）。配合 v10.6.0 workflow 也按 token 计费，阈值精确反映真实成本。

3. 功能需求

模块 A — 阈值配置（Custom Roles）

ID	触发场景	系统行为	优先级
A1	Admin/Security 编辑 Custom Role	新增"per-chat credit warning"配置项	P0
A2	配置阈值	校验正整数，建议档位（1000/5000/10000/自定义）	P0
A3	不同角色配不同阈值	按角色差异化（实习生 1000、工程师 10000）	P0

模块 B — 触发与暂停

ID	触发场景	系统行为	优先级
B1	对话累计消耗跨过阈值	Agent 立即暂停，保留当前状态	P0
B2	达阈值	创建 Action Request（含已消耗量、阈值、任务摘要）	P0
B3	Action Request 创建	走 v10.0.0 HITL 多渠道送达	P0

模块 C — 审批响应

ID	触发场景	系统行为	优先级
C1	用户批准	Agent 从暂停处恢复执行	P0
C2	用户拒绝	Agent 终止当前任务，返回未完成说明	P0
C3	用户无响应	保持暂停（不自动继续）	P1
C4	同对话多次达阈值	每次触发新 Action Request（防批准后失控）	P1

4. 用户场景

企业 admin 控制实验性 Agent 成本

作为 IT admin，我希望给实习生角色设单对话 1000 credits 阈值——这样即使实习生误启了跑偏的代码生成任务，最多烧 1000 credits 就暂停问我，而不是无限制烧下去。

画像：王磊，企业 IT admin。团队在试验代码生成 Agent，担心长链推理 + sandbox 调用意外烧信用。

验收标准：

创建"实习生"Custom Role，配 per-chat warning 1000 credits
实习生启代码生成 Agent，消耗达 1000 → Agent 暂停
王磊收 App 通知 + Slack DM（含已消耗 1000、阈值 1000、任务摘要）
批准（任务有价值）或拒绝（跑偏）；批准后继续，拒绝后停止

5. 竞争分析

竞品	优势	劣势
传统硬性限额	简单、确定	误杀有价值的长任务
OpenAI/Anthropic spend limits	组织级可控	粒度粗，无单会话控制
LangChain tracing	事后分析	事后，非事中阻断

关键洞察

"成本控制变人机协同决策"是精巧设计——传统限额硬性阻断，Credit Warnings 变成 HITL 决策点。既控成本，又保留高价值长任务可能性
Custom Role 绑定是差异化——阈值按角色差异化，契合"不同岗位不同成本权限"的真实治理需求
补全"事中"环节——组织级 Insights（事后）+ per-chat Warnings（事中）+ 组织告警（事前）形成完整闭环

6. 遥测

漏斗阶段	事件名称	指标/KPI	优先级
采用	`credit_warning_role_configured`	配置率（多少企业启用）	P0
触发	`credit_warning_action_request_created`	单对话超限触发率	P0
决策	`credit_warning_approved`	批准率（高说明阈值合理）	P0
决策	`credit_warning_denied`	拒绝率（高说明 Agent 在烧钱做无用功）	P0
影响	`credit_warning_cost_saved`	拒绝终止省下的预计信用	P1

7. 未来演进方向

阶段	时间线	里程碑	状态
Phase 1 — 单对话阈值	v10.5.0	per-chat warning + HITL 暂停审批	已发布
Phase 2 — 智能动态阈值	v10.x	Agent 历史消耗学习，动态建议阈值	规划中
Phase 3 — 预测式告警	v11.x	任务开始时预测总成本，提前告警	探索中
Phase 4 — Agent 级预算池	远期	每个 Agent 独立预算池，跨对话共享	探索中

📚 源文档参考

docs.gumloop.com/core-concepts/credits.md（Per-Chat Credit Warnings 章节，已验证）