spanora-setup

Spanora 设置 Agent Skill

你正在将 Spanora AI 可观测性集成到用户的项目中。请按照本指南逐步操作。

1. 何时调用

在用户提出以下任一需求时，启用此 Skill：

• “添加 Spanora”、“设置 Spanora”、“集成 Spanora”
• “添加 AI 可观测性”、“添加大模型监控”
• “使用 Spanora 监控大模型调用”、“跟踪 AI 成本”
• “为我的 Agent 添加埋点”、“为我的 Agent 添加追踪”
• 在添加可观测性的语境中提到“Spanora”

2. 公开文档——唯一可信来源

Spanora 官方文档 https://spanora.ai/docs 始终保持最新，是唯一可信的权威来源。此 Skill 中附带的 references/ 文件是主要的分步指南；但如果遇到含糊之处、不熟悉的 API、边缘情况，或发现内容与用户代码不符，请使用 WebFetch 获取相关文档页面。如果公开文档与附带的参考资料相矛盾，以公开文档为准。

按集成模式查找的关键页面：

模式	文档页面
Vercel AI SDK	https://spanora.ai/docs/integrations/vercel-ai
OpenAI SDK	https://spanora.ai/docs/integrations/openai
Anthropic SDK	https://spanora.ai/docs/integrations/anthropic
LangChain Python	https://spanora.ai/docs/integrations/langchain
原始 OTEL / 其他	https://spanora.ai/docs/integrations/raw-otel
TypeScript SDK 参考	https://spanora.ai/docs/sdk
OTEL 属性约定	https://spanora.ai/docs/sdk/attributes

无需每次运行时都获取文档——仅在存在不明确之处或怀疑附带的参考资料可能已过时时才获取。

3. 前提条件

用户必须拥有 Spanora API 密钥（以 ak_ 开头）。绝不要要求用户在对话中粘贴 API 密钥。

1. 检查 .env（或 .env.local）中，或 Shell 环境变量中是否已设置 SPANORA_API_KEY。只检查是否存在——不要输出或记录其值。
2. 如果已设置，继续下一步。
3. 如果未设置，请告知用户自行添加：
   • 告诉他们：“请将 Spanora API 密钥添加到 .env 文件中，格式为 SPANORA_API_KEY=ak_...。你可以在 https://spanora.ai/settings 获取密钥。”
   • 不要在对话中接收密钥，也不要将密钥值写入任何文件。
   • 等待用户确认已设置后再继续。
4. 如果 .env 不在 .gitignore 中，请提醒用户将其添加进去。

4. 语言检测

通过检查项目根目录中的配置文件，确定项目语言：

找到的文件	语言
package.json	JavaScript / TypeScript
pyproject.toml	Python
setup.py	Python
requirements.txt	Python

如果同时存在 JS 和 Python 文件，请询问用户要为项目的哪一部分添加埋点。

5. 检测——确定集成模式

JavaScript / TypeScript

读取 package.json，检查 dependencies 和 devDependencies：

找到的依赖项	要使用的模式
ai	模式 A — Vercel AI SDK
@anthropic-ai/sdk	模式 B — Anthropic SDK
openai	模式 C — OpenAI SDK
以上皆无	模式 D — 原始 Core SDK

如果存在多个依赖项，优先顺序为：A > B > C。使用与用户代码实际调用的 SDK 对应的模式。如不确定，请询问用户。

Python

读取 pyproject.toml（或 requirements.txt / setup.py）并检查依赖项：

检测到的依赖项	使用的模式
langchain	模式 E — LangChain / LangGraph

未来可能会添加更多 Python 模式。如果用户的 Python 项目未使用 LangChain，请告知他们 Spanora 支持通过原始 OpenTelemetry 接入任何 Python 框架，并让他们参考 LangChain 指南，将其作为 OTEL 设置模板。

6. 包管理器检测

JavaScript / TypeScript

检测到的文件	包管理器
pnpm-lock.yaml	pnpm
yarn.lock	yarn
bun.lockb	bun
package-lock.json	npm

Python

检测到的文件	包管理器
uv.lock	uv
poetry.lock	poetry
Pipfile.lock	pipenv
其他情况	pip

7. 安装

JavaScript / TypeScript

pnpm add @spanora-ai/sdk
# or: npm install @spanora-ai/sdk / yarn add @spanora-ai/sdk / bun add @spanora-ai/sdk

Python（LangChain）

pip install opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-langchain langgraph
# or: uv add ... / poetry add ... / pipenv install ...

Python 无需安装 Spanora SDK——追踪使用标准 OpenTelemetry。

8. 集成 — 阅读对应的参考文档

根据检测到的模式，阅读相应的参考文件，了解代码示例和 API 用法：

JavaScript / TypeScript：

• 模式 A（Vercel AI SDK）：阅读 references/vercel-ai.md
• 模式 B（Anthropic SDK）：阅读 references/anthropic.md
• 模式 C（OpenAI SDK）：阅读 references/openai.md
• 模式 D（原始 Core SDK）：阅读 references/core-sdk.md

Python：

• 模式 E（LangChain / LangGraph）：阅读 references/langchain-python.md

对于 JS/TS 模式，还必须阅读 references/common.md，了解通用模式：init()、shutdown()、工具追踪（trackToolHandler、runTool）、多 Agent 共享上下文、Agent 命名指南、API 密钥设置以及迁移清单。Python 模式的说明均包含在各自的参考文件中。

将参考文件中的模式应用到用户的代码中。参考文件包含适用于生产环境的示例，并已通过 SDK 源码和集成测试验证。

9. 确保完整的埋点覆盖

每次 AI 执行都必须至少生成一条追踪记录。 对于用户代码中的每个 LLM 调用点，使用可用的最高保真度方案：

1. 自动遥测 — Vercel AI SDK 使用 experimental_telemetry，LangChain 使用自动埋点。优先使用此方案——无需手动操作。
2. 提供商包装器 — 使用 trackOpenAI、trackAnthropic、trackVercelAI / trackVercelAIStream。当某个调用点无法使用自动遥测时使用此方案（例如工具循环 Agent、自定义 Agent 模式）。
3. Core SDK 函数 — 使用 trackLlm、trackLlmStream、recordLlm。作为上述方案未覆盖的 LLM 调用的后备方案。

应用基础集成后，扫描用户的代码，查找不会生成 span 的 LLM 调用。如果发现此类调用，使用上述列表中的适当追踪函数对其进行包装。不要留下任何盲点。

10. 提供可选增强功能

应用基础集成后，向用户说明以下可选功能。默认情况下不要添加这些功能——只有当用户的代码中有相关上下文，或用户提出要求时，才添加：

• 用户和组织上下文——在 track() 调用中使用 userId、orgId、agentSessionId。在仪表板中将跟踪记录与最终用户、租户和会话关联起来。只有当代码可以访问这些值时（例如来自请求上下文、身份验证会话或 API 输入），才添加。
• 操作类型——在 LLM 元数据中使用 operation（trackLlm、trackOpenAI、trackAnthropic、recordLlm）。默认值为 "chat"。嵌入调用设为 "embeddings"，补全调用设为 "text_completion"。仅当用户的代码会进行非聊天类 LLM 调用时才适用。

字段名称参考：

• track() 使用 agent（而非 agentName）作为 Agent 名称
• LLM 跟踪函数使用 prompt（而非 promptInput）作为输入提示词
• LLM 结果/提取器使用 output（而非 promptOutput）作为输出文本

每个参考文件都包含一个「可选增强功能」章节，其中提供了这些功能的代码示例。