agnost-ai

Agnost AI 集成

在目标应用根目录下操作。这是技能集成路径：不要让用户安装 npm 包、使用全局二进制文件或运行包执行器。Agent 可以调用此已安装技能目录中的 scripts/ 辅助脚本，但技能约定的核心是集成工作流。

先询问

编辑前，只询问缺失的信息：

• 仪表板中的 Agnost 组织 ID。
• 如果仓库是 monorepo，则询问目标应用/软件包路径。
• 询问应在本地应用还是已部署的生产应用中进行验证。
• 询问是否允许安装 Agnost 软件包。
• 询问实际的 AI 入口：聊天路由、Agent 调用、MCP 服务启动或工具调用。
• 询问环境变量/代码变更后如何重启或部署应用。

如果没有组织 ID，就停止并询问。不要编造。

选择集成路径

选择集成方案前，先检查现有遥测：

• 查找 OpenTelemetry provider、exporter、框架埋点、环境变量配置，以及来自实际 AI 入口的代表性 spans。
• 检查发出的 span 类别是否受 Agnost 支持。支持的信号包括 OTel gen_ai.*、Vercel AI ai.*、OpenInference llm.*、LiveKit lk.*、Mastra、LangSmith、MCP 和自定义 tool.* spans。
• 如果现有 OpenTelemetry 路径会发出受支持的 spans，则保留该路径，并将这些 spans 路由至 Agnost。不要仅仅因为应用是通用的 TypeScript 或 Python 应用，就安装 Conversation SDK。
• Retell 不提供有文档说明的 OTLP 导出功能。对于 Retell Agent，请按 references/frameworks.md 配置 call_analyzed webhook 路由；不要用 Live Monitoring、Analytics 或 transcript_updated 替代 trace。
• 将自动 OTel 检测视为候选方案，而非证明。检查或触发一次真实交互，并根据以下清单验证生成的 trace，然后再宣称该路径可用。
• 如果存在 OTel，但实际 AI 路径没有发出受支持的 spans，则在实际入口添加框架官方埋点，或补充最少量的缺失属性。如果无法据此生成忠实的对话模型，则改用匹配的 Agnost SDK/MCP 路径。
• 遵循明确指定的 --strategy sdk 或 --strategy otel 选项。

如果没有可用的现有 OTel 路径，则使用 SDK/MCP 集成：

• TypeScript 对话应用：安装 agnostai，初始化一次，并用 begin() 和 end() 包装实际的模型/Agent 调用。
• Python 对话应用：安装 agnost，初始化一次，并用 begin()/end() 或 track_ai() 包装实际的模型/Agent 调用。
• TypeScript MCP 服务：安装 agnost，在服务构造完成后、传输连接前调用 configureFromEnv() 和 trackMCP(server, orgId, config)。对于 HTTP/OAuth MCP 服务，保留官方传输请求路径（transport.handleRequest(req, res, req.body)），以便 extra.requestInfo.headers 能传递给 Agnost。如果目标使用自定义传输或手动调用 handleMessage(...)，请传入 { requestInfo: { headers: req.headers }, authInfo: req.auth }。如果 OAuth 中间件会验证 bearer 令牌，请在 req.auth.extra 上附加稳定的非机密身份信息，例如 { userId, tokenId }；Agnost 会使用 tokenId 作为持久的 OAuth 对话/会话键。如果请求头不可用，Agnost 也可以从 authInfo.sub、authInfo.claims、authInfo.tokenPayload、authInfo.extra、authInfo.token、authInfo.accessToken 或 authInfo.access_token 读取身份信息；切勿将 OAuth clientId 用作用户 ID。切勿记录原始 bearer 令牌。
• Python MCP/FastMCP 服务：安装 agnost-mcp，在工具注册完成后、调用 run() 前调用 track(server, org_id, config(...))。SDK 支持 stdio、SSE 以及有状态/无状态的 Streamable HTTP。同一进程中的多个已跟踪服务实例必须使用相同的 org ID 和 config。如果没有自定义同步/异步 identify，内置身份识别会使用 bearer 令牌或经过验证的 MCP 身份验证上下文，且不会转发原始凭据；身份会按会话键缓存。

如果没有可用的受支持 OTel 路径，且 Node/TypeScript 项目包含 MCP 代码，但并非专用 MCP 服务（例如还包含应用、Agent、模型、OpenAI、Vercel AI SDK、LangChain、Mastra、Next/React 或 API 服务代码），请使用其现有的受支持 OTel 路径，或使用 TypeScript 对话 SDK 路径（agnostai），并为实际的 AI 轮次添加埋点。仅当该包的主要用途是专用 MCP 服务时，才使用 MCP 封装路径。

默认启用输入和输出捕获。对于名为 disableInput/disableOutput（或 Python 中的 disable_input/disable_output）的选项，false 表示启用捕获。只有当用户明确要求对输入/输出进行脱敏，或目标应用的隐私要求需要这样做时，才将其设为 true。

受支持的 OTel 配方目标包括 LiveKit Agents、Vercel AI SDK、Mastra、Spectrum TS、LangChain、OpenAI，以及其他已添加埋点的 OTel 应用。

如果存在官方 SDK、MCP 封装或框架 OTel 选项，请勿创建合成 fetcher 或自定义 OTLP 载荷路径。

验证 OTel 路由

对于一次具有代表性的真实交互，检查发出的追踪记录以及由此产生的 Agnost 用户、会话、轮次、事件和工具详情。发现缺失项时，在框架插桩或实际 AI 入口处设置属性。只有通过以下所有检查，路由才有效：

1. 用户映射： 对同一客户的所有会话，使用一个稳定的 agnost.user_id、enduser.id 或 user.id。验证该客户的两个不同会话映射到同一个 Agnost 用户，并确认其他客户无法继承该身份。
2. 会话映射： 对一个会话中的所有事件和轮次（包括分批导出的 span），使用一个稳定的 agnost.session_id、gen_ai.conversation.id 或 session.id。新会话必须获得不同的 ID，且其中的用户/助手轮次必须保持有序且完整。
3. 轮次和工具层级： 每个用户与助手的轮次都必须保留其输入和输出。内部 tool.*、框架原生工具或 MCP 工具 span 必须是调用它们的轮次的子 span，并使用真实的 OTel 父 span ID，而不是自定义父级属性。
4. AI 和 SDK 属性： 保留框架的原生属性，并确认模型、提供方、操作、成功/错误状态以及可用的令牌数量位于正确的 span 上。优先使用当前的 GenAI 字段，例如 gen_ai.usage.input_tokens 和 gen_ai.usage.output_tokens；保留有用的特定 SDK 属性，如 ai.*、llm.*、lk.*、Mastra、LangSmith 或 MCP 属性。
5. 自定义元数据： 使用 user.* 或 enduser.* 表示自定义用户元数据，使用 conversation.* 或 session.* 表示自定义会话元数据，并使用非保留的 span 属性表示自定义事件元数据。将稳定值放在资源上，或传播到每个相关 span；仅将轮次/工具专属值放在其所描述的事件 span 上。

修复有证据支持的最小范围问题，重启或重新部署，然后重复相同的交互并重新检查追踪记录。不要仅仅为了重命名属性，就用合成 span 替换正常工作的框架追踪树。

查阅正确的参考文档

仅打开 references/frameworks.md 中匹配的部分：

• #conversation-ts-agnostai
• #conversation-py-agnost
• #mcp-ts-agnost
• #mcp-py-agnost-mcp
• #vercel-ai-otlp
• #openai-openinference-otlp
• #mastra-otlp
• #spectrum-ts-app-level-otel-spans
• #langchain-langsmith-otel-mode
• #custom-otel-spans

语音 Agent 路由：

• #livekit-agents-native-otlp
• #retell-call-analyzed-webhook

对于 vercel-ai，请先阅读 references/frameworks.md#vercel-ai-otlp 再进行编辑。仅使用 Agnost 官方配方：设置 OTel 导出器，并在现代 generateText/streamText/generateObject 调用中启用 experimental_telemetry。如果应用使用不符合现代调用形式的旧版 OpenAIStream(...)，则仅在用户选择 OTel 时配置环境变量/依赖，然后说明应用遥测需要迁移到受支持的 Vercel AI SDK 调用形式，或使用 SDK 插桩。不要生成自定义 OTLP 请求、合成 span 或包装函数。

语音 Agent

对于 livekit-ts 或 livekit-py，请先阅读 references/frameworks.md#livekit-agents-native-otlp 再进行编辑。保留 LiveKit 的原生 span：配置标准 OTel 批量导出器，并在 AgentSession.start() 之前调用框架的 tracer-provider 钩子。使用 session.id、user.id、user.* 和 conversation.* 元数据。不要添加自定义 span 包装器、合成 OTLP 负载，也不要使用 LiveKit 房间 Webhook 替代 Agent 追踪记录。

对于 Retell，请阅读 references/frameworks.md#retell-call-analyzed-webhook。配置直接指向 Agnost Webhook 的 URL，填入真实的组织 UUID，并启用 call_analyzed。不要添加 OTel 导出器，也不要摄取增量 transcript_updated 事件。

回填现有数据

如果用户有历史对话或 Agent 活动，可在实时埋点之前或同时提供回填功能。保留原始时间戳和稳定的对话／事件关联关系，并将源标识符映射为所需的 UUID。使用 Capture Session API 创建每个对话，然后使用 Capture Event API 发送其轮次对和工具调用。请遵循 API 参考，确保事件层级、输入／输出格式和历史时间戳符合要求。

脚本辅助工具

脚本是供 Agent 和命令行工具使用的辅助工具，不是产品界面。

仅在选定上面的接入方式后使用：

node "$SKILL_DIR/scripts/detect.mjs" --dir . --strategy <auto|sdk|otel> --json
node "$SKILL_DIR/scripts/instrument.mjs" --dir . --framework <framework> --org-id <org-id> --mode <local|prod> --env-mode <file|shell|manual> --json
node "$SKILL_DIR/scripts/send-demo.mjs" --org-id <org-id> --transport <ingest|otel> --mode <local|prod> --json

detect.mjs 可以建议接入方式。在 auto 模式下，它会保留受支持框架现有的 OTel 设置，但该建议仍需通过真实追踪进行验证。instrument.mjs 可以应用已知范围最小的修改。send-demo.mjs 可以检查 Agnost 是否接受流量，但无法证明客户应用已完成集成。

完成标准

只有当用户自己的应用在本地运行，并使用生产环境的 Agnost 端点从其真实代码路径发出遥测数据时，集成才算完成。

• 将本地应用环境变量设置为真实的组织 ID 和生产端点： AGNOST_ORG_ID=<org-id>、AGNOST_ENDPOINT=https://api.agnost.ai，如果使用 OTel，还要设置 AGNOST_OTEL_URL=https://otel.agnost.ai。
• 应在应用好环境变量并完成代码修改后，告知 Agent 框架／用户使用常规启动命令运行本地应用。
• 通过正在运行的本地应用触发一次真实聊天、Agent 操作或 MCP 工具调用。
• 在宣布集成完成前，先在 Agnost 仪表板中确认用户、对话、轮次／事件、工具层级、属性和元数据。

如果事件来自 send-demo.mjs、独立 SDK 代码片段，或绕过用户正在运行的应用，则不要宣称集成已完成。

验证

完成依赖、环境变量和代码修改后：

1. 请用户重启本地应用，或部署／重启生产应用。
2. 请用户执行一次真实聊天、Agent 操作或 MCP 工具调用。
3. 请用户在 Agnost 仪表板中检查该真实交互的原始日志、用户、对话、工具和追踪。对于 OTel，应执行上面的完整验证清单，而不只是检查是否收到一个 span。

报告所采用的接入方式、修改的文件、所需的环境变量、重启／部署步骤，以及验证所需的确切真实交互。如果没有事件出现，应先检查应用日志和环境变量传递情况，再添加更多代码。

验证循环

重复以下步骤，直到真实交互出现在 Agnost 中，或发现明确的阻碍：

1. 请求最少量的缺失证据：重启／部署确认、环境变量来源、应用日志、真实交互时间戳、仪表板截图／日志，或确切的 AI 入口点。
2. 只修复已确认的问题。
3. 请用户再次重启／部署，并重复相同的真实交互。
4. 在宣称成功前，重新检查 Agnost 仪表板中的结果。