Google Antigravity SDK可观测性实战OpenTelemetry追踪与Token成本审计配置指南【免费下载链接】antigravity-sdk-pythonA Python library for building AI agents that leverage the full power of Google Antigravity.项目地址: https://gitcode.com/gh_mirrors/an/antigravity-sdk-pythonGoogle Antigravity SDK是用于构建 AI Agent 的 Python 库而它的可观测性能力OpenTelemetry 分布式追踪 Token 成本审计往往被新手忽略。本文带你用不到 30 行配置给 Agent 加上完整的执行链路追踪与 Token 用量账单轻松定位Agent 为什么这么慢、花了这么多钱。 阅读时长约 8 分钟 | 无需额外经验会基本 Python 即可上手为什么 AI Agent 需要可观测性传统程序出了 bug 看日志就行但 AI Agent 的一次回答背后藏着复杂的链路模型调用、工具执行、子代理Subagent派生……任何一环变慢或报错肉眼都难以察觉。SDK 提供三层观测手段手段解决什么问题核心入口OpenTelemetry 追踪每一步耗时、哪次工具调用出错、子代理调用树utils/otel.pyToken 用量审计会话总消耗、单个回合增量、每个子代理的花费conversation.py预算上限Budget超支前主动刹车控制模型/工具/Token 次数budget_limits.py一键开启 OpenTelemetry 追踪1. 安装 OTel 依赖SDK 的追踪模块通过可选依赖提供见 pyproject.tomlpip install google-antigravity[otel]2. 注册追踪钩子所有追踪逻辑都基于 SDK 的**生命周期钩子Hooks**实现一行注册即可from google import antigravity from google.antigravity.utils import otel as otel_hooks config antigravity.LocalAgentConfig( hooksotel_hooks.get_otel_hooks(), # 9 个钩子一次注册 )get_otel_hooks()会返回 9 个开箱即用的钩子定义于 otel.py覆盖从会话开始到工具结束的完整生命周期。3. 配置导出器以打印到控制台为例官方示例 observability_otel.pyfrom opentelemetry import trace from opentelemetry.sdk import trace as sdk_trace from opentelemetry.sdk.trace import export provider sdk_trace.TracerProvider() provider.add_span_processor( export.SimpleSpanProcessor(export.ConsoleSpanExporter()) ) trace.set_tracer_provider(provider)生产环境只需把ConsoleSpanExporter换成 OTLP 导出器即可接入任意 OpenTelemetry 后端。追踪结构解析4 层 Span 是怎么嵌套的运行一次 Agent 后控制台会输出树状的 Span。SDK 自动构建了四层结构实现逻辑见 otel.pyantigravity.session ← 整个会话 └── invoke_agent Antigravity ← 每一轮对话Turn ├── antigravity.step.0 ← 第 0 步 │ └── execute_tool get_weather ← 工具调用 └── invoke_agent Poet ← 子代理独立成子树 └── antigravity.step.0每个 Span 都带上了通用的gen_ai标准属性gen_ai.operation.name、gen_ai.agent.name、gen_ai.tool.name方便在 Jaeger、Grafana 等平台上按 Agent 维度聚合。⚠️两个值得知道的细节工具 Span 的开始时机在安全策略检查之前因此人工确认Human-in-the-loop的等待时间会被计入工具耗时工具执行抛异常时钩子会自动将异常记录到 Span 并打上ERROR状态OTelOnToolErrorHook无需自己写 try/except。Token 成本审计3 个属性看懂整张账单追踪解决怎么跑的用量审计解决花了多少。Agent 的会话对象暴露了 3 个现成属性定义见 conversation.pyasync with antigravity.Agent(config) as agent: await agent.chat(What is the weather in Seattle?) usage agent.conversation.total_usage # ① 会话累计 turn agent.conversation.last_turn_usage # ② 最近一轮增量 by_agent agent.conversation.trajectory_usages # ③ 按子代理拆分① 会话累计用量返回UsageMetadata对象types.py包含 5 个关键字段字段含义prompt_token_count输入 Token 数cached_content_token_count命中缓存的 Token 数输入的子集通常更便宜candidates_token_count模型生成的输出 Token 数不含思考thoughts_token_count思考/推理消耗的 Token 数total_token_count以上三者之和⚠️避坑提示如果你用的是支持扩展思考的模型thoughts_token_count可能远超输出 Token成为成本大头——审计时请优先关注它参考文档 observability.md。另外若 Agent 执行失败如 API Key 无效用量可能报告为 0。② 单轮增量用量last_turn_usage通过当前累计 − 本轮开始前快照自动算出差值适合做每轮成本告警。③ 子代理拆分trajectory_usages返回{轨迹ID: 用量}字典主代理的轨迹 ID 与会话 ID 相同每个子代理拥有独立轨迹——可以精确回答是主代理花了钱还是某个子代理在烧钱。预算刹车用 BudgetConfig 控制成本上限审计是事后看账单预算配置是事前装刹车。通过LocalAgentConfig传入 BudgetConfig可打开 5 个限流阀门config antigravity.LocalAgentConfig( budget_configantigravity.types.BudgetConfig( max_model_calls10, # 最多调用模型 10 次 max_tool_calls20, # 最多执行 20 次工具 max_input_tokens50_000, # 输入 Token 上限推理前拦截 max_output_tokens10_000, # 累计输出上限 max_total_tokens80_000, # 累计总 Token 上限 ) )任一阀门耗尽时回合会携带对应的停止原因如MAX_MODEL_CALLS_EXCEEDED、MAX_TOTAL_TOKENS_EXCEEDED你可以在代码里读取response.stop_reason并优雅降级。完整的五阀门触发演示见 budget_limits.py。 小技巧max_input_tokens是推理前主动拦截——在还没花钱之前就刹车是唯一能零消耗阻止回合的阀门。进阶标准日志与自定义审计钩子不想接 OpenTelemetry 平台SDK 内置标准 Python 日志两行即可开启运行详情示例 observability.pyimport logging logging.getLogger(google.antigravity).setLevel(logging.INFO)而基于装饰器的钩子可以零框架写出审计日志——每次工具执行后自动落一条审计记录from google.antigravity.hooks import hooks hooks.post_tool_call async def audit_log_tool_call(data): print(f[AUDIT] Tool execution completed. Result: {data})把它和total_usage结合就是一份极简的工具 × Token审计方案。关键文件速查文件说明google/antigravity/utils/otel.py9 个 OTel 追踪钩子的完整实现examples/deep_dives/observability_otel.py含子代理的追踪端到端示例examples/getting_started/observability.py日志 审计钩子 用量打印入门示例examples/getting_started/budget_limits.py5 个预算阀门逐一触发演示google/antigravity/conversation/conversation.pytotal_usage/last_turn_usage/trajectory_usages定义google/antigravity/types.pyUsageMetadata数据模型skills/google-antigravity-sdk/references/observability.md官方可观测性参考文档小结追踪pip install google-antigravity[otel]get_otel_hooks()一行注册自动获得会话 → 回合 → 步骤 → 工具四层 Span 树审计total_usage/last_turn_usage/trajectory_usages三个属性从全局到子代理逐层对账重点关注thoughts_token_count控费BudgetConfig五个阀门在超支前主动刹车配合stop_reason优雅降级。把这三件套配上你的 Agent 从此每一分钱、每一毫秒都有据可查 【免费下载链接】antigravity-sdk-pythonA Python library for building AI agents that leverage the full power of Google Antigravity.项目地址: https://gitcode.com/gh_mirrors/an/antigravity-sdk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考