instrument-agent 是一个面向已有 AI 智能体或 LLM 应用的可观测性埋点技能，用于把 Progress Observability 接入现有代码库。它只编辑已经存在的代码，不适用于尚未创建的项目。该技能只写埋点相关代码，不重构应用，也不回读平台数据；确认 trace 是否到达由单独的 /health-check 步骤负责。
用途
为现有 AI 智能体或 LLM 应用添加 Progress Observability 埋点，以尽可能小的改动让 span 开始上报。支持 Python、TypeScript/JavaScript 和 .NET，覆盖 LangChain、LangGraph、LlamaIndex、OpenAI、Anthropic、Microsoft.Extensions.AI 等框架与 SDK。
主要能力
-
检测：在改动前扫描仓库并报告发现，包括语言与入口点（pyproject.toml/requirements.txt、package.json、*.csproj）、正在使用的 LLM SDK 与框架、已有遥测（OpenTelemetry、Traceloop 或此前的 Progress Observability 初始化）、作用范围（monorepo、多服务或多智能体时需要先确认目标）、配置方式、包管理器，以及 Python 项目是否缺少 langchain / llama-index 元包。
-
接线：按语言参考逐字使用其代码片段。Python 使用 progress-observability（PyPI），TypeScript 使用 @progress/observability（npm），.NET 使用 Progress.Observability.Instrumentation（NuGet）。通用规则包括：在进程启动时、任何 LLM 客户端存在之前初始化；保持最小改动；无 LLM 调用的应用需对每个步骤埋点而非仅入口；Python + LangChain/LlamaIndex 必须添加元包；TypeScript + LangChain 必须声明 @langchain/core；绝不要求用户在聊天中粘贴密钥；缺失密钥必须显式报错；密钥通过配置提供而非硬编码；依赖声明是必须的文件编辑；app_name 是平台身份标识，需与用户确认；内容捕获默认开启，敏感数据可关闭。
-
运行一次：让用户运行应用以产生至少一条 trace。若没有 LLM 凭据，可用装饰器/手动 span 路径产生真实 span。
-
确认与交接：埋点完成以编辑就位且应用已产生至少一条 trace 为准。该技能不通过 MCP 回读，不调用 list_observations、get_observation_details 等平台工具。用户可自行打开 observability.progress.com 确认 trace 是否流入。
使用方式
该技能通过检测、接线、运行一次、确认与交接四个步骤工作。接线时严格遵循对应语言的参考文档，使用经过验证的代码片段。初始化顺序因语言而异：Python 需在应用自身 OpenTelemetry 设置之后初始化，否则会破坏应用已有遥测；.NET 无顺序约束，但需注意重复计数；TypeScript 需先 provider.register() 再 instrument()，并检查 @opentelemetry/* 主版本。
适用场景
适用于已有 AI 智能体或 LLM 应用需要接入 Progress Observability 的场景，包括使用 LangChain、LangGraph、LlamaIndex、OpenAI、Anthropic、Microsoft.Extensions.AI 等框架的项目。不适用于尚未创建的项目，也不适用于 DSPy、AutoGen、Pydantic AI、Semantic Kernel、Google ADK 等未在支持列表中的框架（可改用装饰器/手动 span 回退方案）。LangGraph 在 Python 中受支持，在 JS SDK 中不受支持；Genkit 在 JS SDK 3.1.0 起受支持。
限制
该技能只做本地埋点编辑，不读取也不写入平台。它不重构应用，不移动应用代码。确认 trace 是否到达是用户自行执行的只读步骤。未经验证的接线是正常且健康的结果，尤其对免费层新用户而言。