企业官网建设流程全解析

agents-cli 成本监控：per-tool Span 统计发现「话痨工具」消耗异常

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli

AI Agent 的 Token 成本监控，一直是让开发者头疼的问题。用agents-cli脚手架创建的项目自带 OpenTelemetry 埋点：每一次 LLM 调用、每一次工具执行都会生成独立的Span，在 Cloud Trace 中可查可分析，配合 BigQuery Agent Analytics 插件，几条 SQL 就能定位「话痨工具」的消耗异常，帮你把成本账单看得明明白白。

🧐 为什么需要 per-tool 的 Span 级成本监控？

一个 Agent 通常由 LLM 推理 + 多个工具（数据库查询、API 调用、RAG 检索等）协作完成。成本往往不是均匀分布的：

• 某个工具反复被调用，每次调用都塞入超长上下文，Token 消耗爆炸；
• 某个工具返回结果过大，把整页 HTML 或大 JSON 直接回传给模型，Prompt Token 持续膨胀；
• Agent 陷入重试循环，某个工具频繁报错后反复重试，账单悄悄翻倍。

如果只看「总 Token 数」这类粗粒度指标，这些异常全部被平均掉了。per-tool 粒度的 Span 统计，正是把这些隐藏消耗揪出来的关键。

📊 agents-cli 如何采集工具级遥测数据

每个agents-cli项目都开箱即用地内置了 OpenTelemetry 插桩，无需手写埋点代码：

一次用户请求进来后，Span 树会清晰呈现「LLM 调用 → 工具执行 → 再次 LLM 调用」的完整链路，每个 Span 都带有时长、错误状态和 GenAI 语义约定属性（模型名、Token 用量等）。相关机制详见 docs/src/guide/observability/index.md 与 docs/src/guide/observability/cloud-trace.md。

🚀 三步快速上手：在 Cloud Trace 里验证 Span 流

1. 部署并制造流量：执行agents-cli deploy后，向 Agent 发几个真实请求；
2. 打开 Trace Explorer：在 Google Cloud Console 进入Trace → Trace explorer，你会看到每个请求一条 Trace，Span 中分别标记 LLM 调用与工具执行；
3. 观察异常形态：找出耗时最长、调用次数最多的 Span，即可初步锁定嫌疑工具。

无需任何配置，本地agents-cli playground与所有部署环境都自动生效。

🔍 用 BigQuery SQL 揪出「话痨工具」

Cloud Trace 适合交互式排查，规模化成本监控则推荐 BigQuery Agent Analytics 插件——在创建项目时加上--bq-analytics参数即可开启（仅 ADK 模板支持）：

agents-cli create my-agent -a adk -d cloud_run --bq-analytics

插件会把每次工具完成（TOOL_COMPLETED）、工具报错（TOOL_ERROR）以及每次 LLM 响应（LLM_RESPONSE，含 Token 用量）写入 BigQuery 的agent_events表。想知道哪个工具最「费话」，聚合一下就行：

SELECT JSON_VALUE(content, '$.tool') AS tool_name, COUNT(*) AS call_count, COUNTIF(event_type = 'TOOL_ERROR') AS error_count FROM `YOUR_PROJECT.YOUR_AGENT_telemetry.agent_events` WHERE event_type IN ('TOOL_COMPLETED', 'TOOL_ERROR') GROUP BY 1 ORDER BY call_count DESC;

再按模型维度统计 Token 消耗（完整示例见 docs/src/guide/observability/bq-agent-analytics.md）：

• TOOL_COMPLETED次数远超预期→ 工具被 Agent 高频调用，检查提示词是否诱导了多余调用；
• TOOL_ERROR占比高→ 报错重试循环，先修工具稳定性，省下的就是钱；
• 该工具活跃时间段的 Prompt Token 明显偏高→ 工具返回内容过大，加上摘要或截断逻辑。

⚠️ 「话痨工具」异常排查清单

📚 延伸阅读与关键路径

• 可观测性总览：docs/src/guide/observability/index.md
• Cloud Trace 验证与配置参考：docs/src/guide/observability/cloud-trace.md
• BigQuery 分析插件与示例查询：docs/src/guide/observability/bq-agent-analytics.md
• 内置可观测性技能（供编码助手使用）：skills/google-agents-cli-observability/SKILL.md
• Prompt-Response 日志的 Terraform 定义：src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/single-project/telemetry.tf

小结：agents-cli 把 OpenTelemetry 遥测做成了项目的默认能力——Span 自动记录每次工具执行，BigQuery 插件让成本分析变成一条 SQL 的事。用 per-tool 的视角盯住「话痨工具」，你的 Agent 成本账单再也不会出现无法解释的毛刺。📉

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli