agents-cli 本地启用 Prompt 日志：playground 环境变量配置全攻略

agents-cli 本地启用 Prompt 日志playground 环境变量配置全攻略【免费下载链接】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 智能体时agents-cli的playground命令默认不开启Prompt 日志prompt-response logging。只需配置 6 个环境变量就能让 agents-cli 把每轮对话的完整提示词与响应记录到 GCS 和 BigQuery实现本地与线上行为完全一致。本文手把手带你完成全套配置。为什么本地需要 Prompt 日志agents-cli是一个把任意编码助手变成AI 智能体专家的命令行工具覆盖创建、评估、部署三大场景并内置了完善的可观测性能力Cloud Trace默认开启无需任何配置追踪 LLM 调用与工具执行的耗时Prompt 日志记录完整模型交互提示词、响应、Token 用量上传到GCSJSONL 格式和BigQuery的completions表。但这里有一个新手容易踩的坑运行环境Cloud TracePrompt 日志本地agents-cli playground✅ 开启不含内容❌ 默认关闭已部署Terraform 供给✅ 开启不含内容✅ 开启完整记录Prompt 日志的开关取决于是否配置了LOGS_BUCKET_NAME等环境变量——Terraform 部署时会自动设置而本地 playground 不会。好在它的设计是声明式的你手动设置同一组变量本地即可启用完全相同的日志能力。一键配置6 个环境变量完整清单在启动 playground 之前执行以下命令将占位符替换为你的项目信息export LOGS_BUCKET_NAMEyour-dev-project-id-your-project-name-logs # 纯桶名不加 gs:// export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT # 或 EVENT_ONLY 在日志事件中保留完整内容 export OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOKupload export OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATHgs://your-dev-project-id-your-project-name-logs/completions export OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMATjsonl export OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental然后照常启动agents-cli playground桶名命名规则Terraform 供给的日志桶遵循${PROJECT_ID}-${PROJECT_NAME}-logs格式本地配置时保持一致就能复用部署环境已有的存储资源无需额外创建。逐个理解每个配置项下面这张表帮你快速搞懂每个变量管什么、怎么填环境变量取值示例作用LOGS_BUCKET_NAMEGCS 桶名不带gs://总开关。未设置则 Prompt 日志完全禁用OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT/EVENT_ONLY/SPAN_ONLY/SPAN_AND_EVENT控制仅Trace/日志事件层是否带内容⚠️true/false是非法值会被拒绝并回退为NO_CONTENTOTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOKupload开启完整对话记录上传OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATHgs://桶名/completions对话记录的上传目的地OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMATjsonl上传格式OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimentalGenAI 上传语义约定必需项关键区分GCS/BigQuery 的 completions 记录永远捕获完整内容只要配了桶而 Trace 和 Cloud Logging 事件是否出现内容由第二个变量单独控制。默认NO_CONTENT即完整内容进 GCS/BigQueryTrace 里看不到正文——兼顾了排障深度与数据安全。另外还有一个 ADK 专属变量ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS设为false可确保内容不出现在 Trace span 中Terraform 已默认帮你设置本地调试一般无需再动。3 步验证日志是否生效启动 playground 并和智能体聊几轮后按以下步骤确认第 1 步查看 GCS 桶gsutil ls gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/应能看到新写入的 JSONL 文件每行即一条完整的提示词-响应记录。第 2 步查询 BigQuerybq query --use_legacy_sqlfalse \ SELECT * FROM \${PROJECT_ID}.${PROJECT_NAME}_telemetry.completions\ LIMIT 10第 3 步观察应用日志如果前两步都没有数据检查应用启动日志中是否有 telemetry 配置警告通常指向变量拼写或权限问题。常见问题排查症状可能原因解决办法完全没有日志文件LOGS_BUCKET_NAME未设置或拼写错误确认值中不含gs://前缀GCS 有文件但 BigQuery 查不到日志 sink 有分钟级延迟或数据集名含连字符等待几分钟后重试注意 BigQuery 数据集名会自动将-转为_如my-agent→my_agent_telemetry权限报错服务账号缺角色确认服务账号在桶上拥有storage.objectCreator权限设置了true/false却无效实验性语义约定下这两个值非法改用NO_CONTENT/EVENT_ONLY等枚举值相关资源 官方可观测性指南docs/src/guide/observability/index.md Cloud Trace 与本地日志详解docs/src/guide/observability/cloud-trace.md️ 智能体可观测性 Skillskills/google-agents-cli-observability/SKILL.md playground 命令实现src/google/agents/cli/dev/cmd_playground.py⚙️ Terraform 遥测配置模板src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/single-project/telemetry.tf配置完成后你本地的每一次对话都会与生产环境一样被完整记录——调试 Prompt、复现线上问题时这套日志就是最可靠的行车记录仪。【免费下载链接】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辅助生成（AIGC），仅供参考