@grafana/sigil-sdk-js

中文文档
0.8.2发布于 2026/07/16Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 9085

Sigil 记录 正常 LLM 生成和工具执行 遥测 使用您的 OpenTelemetrime tracker/ meter 设置 .

此软件包已被标记为弃用

Renamed to @grafana/agento11y. See https://grafana.com/docs/grafana-cloud/machine-learning/agent-observability/guides/migrate-sigil-sdk-to-agento11y/

中文使用文档
文档目录20 节
  1. 安装
  2. 验证
  3. 快速启动
  4. 内容抓取
  5. 提醒前编辑
  6. 通过环境变量配置编辑
  7. 虎克和卫兵
  8. 核心 API
  9. 手动 try/finally 样式
  10. 嵌入可观察性
  11. 工具执行示例
  12. 提供者助手
  13. 框架处理器
  14. 行为
  15. 只使用仪器模式( 没有生成发送)
  16. SDK 度量衡
  17. 生成导出认证模式
  18. Grafana Cloud auth( 基础) :
  19. 连接自定义环境 vars
  20. 对话评分

Grafana Sigil 类型脚本/ JavaScript SDK

Sigil 记录 正常 LLM 生成和工具执行 遥测 使用您的 OpenTelemetrime tracker/ meter 设置 .

安装

pnpm add @grafana/sigil-sdk-js

对于只需要核心的低依赖性运行时间 SigilClient 生成导出 API,使用瘦芯包 :

pnpm add @grafana/sigil-sdk-js-core

对于Grafana Cloud 设置的走过(在哪里找到端点 URL, 例如 ID, 和 API 令牌), 指的是 Grafana 云设置指南。 。 。 .

验证

从 repo 根运行 JavaScript SDK 共享核心兼容套件 :

mise run test:ts:sdk-conformance

从 repo 根运行跨语言集合核心相容套件 :

mise run sdk:conformance

快速启动

下面的片段明确配置了SDK. 作为替代方案,设置 SIGIL_* 环境变量和呼叫 new SigilClient() 没有任何论据——参见: Grafana 云设置指南 用于变量名称.

import { SigilClient } from "@grafana/sigil-sdk-js";

const client = new SigilClient({
  generationExport: {
    protocol: "http",
    endpoint: "https://sigil-prod-<region>.grafana.net",
    auth: {
      mode: "basic",
      tenantId: process.env.SIGIL_AUTH_TENANT_ID,
      basicPassword: process.env.SIGIL_AUTH_TOKEN,
    },
  },
  api: {
    endpoint: "https://sigil-prod-<region>.grafana.net",
  },
});

await client.startGeneration(
  {
    conversationId: "conv-1",
    model: { provider: "openai", name: "gpt-5" },
  },
  async (recorder) => {
    const outputText = "Hello from model";
    recorder.setResult({
      output: [{ role: "assistant", content: outputText }],
    });
  }
);

await client.shutdown();

内容抓取

contentCapture 控制SDK在输出的生成有效载荷和OTel的属性中包含的内容。 见 内容抓取模式 用于 Cononical 模式矩阵和默认; 下面的片段显示如何在 TypeScript 中将其接线.

客户端级别默认 :

import { SigilClient } from "@grafana/sigil-sdk-js";

const client = new SigilClient({
  contentCapture: "metadata_only",
});

SDK 核心客户端处理 "default" 作为 "no_tool_content":生成内容被捕获,但工具执行参数和结果不超出范围.

每代覆盖 :

await client.startGeneration(
  {
    model: { provider: "openai", name: "gpt-5" },
    contentCapture: "full",
  },
  async (recorder) => {
    recorder.setResult({ output: [{ role: "assistant", content: "hi" }] });
  }
);

每个工具执行覆盖( 这里) "full" 选择获取工具参数和跨度结果 :

await client.startToolExecution(
  { toolName: "search", contentCapture: "full" },
  async (recorder) => {
    recorder.setResult({ arguments: { q: "weather" }, result: { tempC: 18 } });
  }
);

动态分辨率通过 contentCaptureResolver数字 :

const client = new SigilClient({
  contentCaptureResolver: (metadata) => {
    if (metadata?.["sigil.tenant"] === "healthcare") {
      return "metadata_only";
    }
    return "default"; // defer to `contentCapture`
  },
});

解析器接收录制的元数据(或 undefined 用于记录没有元数据的类型,如工具执行)。 丢出的错误被抓住并当作 "metadata_only" (失闭.

分辨率优先( 最高至最低) :

  1. 每集记录 contentCapture 打开 GenerationStart 编号 : ToolExecutionStart
  2. contentCaptureResolver 返回值
  3. 客户一级 contentCapture (违约) "no_tool_content"(中文(简体) )

与"去","Python","Java"和"NET SDK"不同,JS SDK没有通过Async上下文来传播解析的捕捉模式,因此在一代块内开始的工具执行不会自动地继承一代模式. 设定 contentCapture 每个 ToolExecutionStart 当您需要工具来遵循非违约政策时.

用户提供 metadata 财务报告和审定财务报表 tags 不被任何捕获模式剥离。 SDK-内部元数据密钥,包含内容(例如. call_error, (中文(简体) ), sigil.conversation.title)与匹配内容一起剥去。 见 标记和元数据 用于客户端标签、每代标签、元数据以及 userId 每个显示( export vs 跨度 vs 度量衡) .

提醒前编辑

使用 generationSanitizer 当您想要编辑以前正常世代的子字符串时 验证、 跨度同步、 调试快照和导出 .

import {
  SigilClient,
  createSecretRedactionSanitizer,
} from "@grafana/sigil-sdk-js";

const client = new SigilClient({
  generationSanitizer: createSecretRedactionSanitizer({
    redactInputMessages: false, // omit to fall back to SIGIL_REDACT_INPUT_MESSAGES, then false
    redactEmailAddresses: true,
  }),
});

内置消毒器:

  • 编辑助理文本和思维中的高度自信秘密格式
  • 编辑工具调用输入和工具结果中的秘密格式外加 env 风格的秘密值
  • 默认编辑电子邮件地址
  • 除非启用输入编辑,否则用户输入保持不变

要保存电子邮件地址, 请明确选择退出 :

const client = new SigilClient({
  generationSanitizer: createSecretRedactionSanitizer({
    redactEmailAddresses: false,
  }),
});

通过环境变量配置编辑

createSecretRedactionSanitizer() 读取 SIGIL_REDACT_INPUT_MESSAGES 联合国 1/0, (中文(简体) ), true/false, (中文(简体) ), yes/no, (中文(简体) ), on/off当 redactInputMessages 省略. 优先是明确的选项 > env var > false未识别的嵌入值是 警告并倒回下一层, 所以打字不能静地翻转 编辑.

import {
  createSecretRedactionSanitizer,
  SigilClient,
} from "@grafana/sigil-sdk-js";

// Omit redactInputMessages so SIGIL_REDACT_INPUT_MESSAGES decides.
const client = new SigilClient({
  generationSanitizer: createSecretRedactionSanitizer(),
});

虎克和卫兵

在LLM呼叫前要用钩子来操作西吉尔守卫规则. SDK评估您请求路径上的钩子; Grafana Cloud 配置的守护规则决定是允许,拒绝,还是转换输入.

虎克默认被禁用. 启用客户端并拨打 evaluateHook(...) 在提供者提出请求之前:

import { HookDeniedError, SigilClient } from "@grafana/sigil-sdk-js";

const client = new SigilClient({
  hooks: { enabled: true, phases: ["preflight"], timeoutMs: 15_000, failOpen: true },
});

let messages = [{ role: "user" as const, content: "Summarize this customer note..." }];
const response = await client.evaluateHook({
  phase: "preflight",
  context: {
    agentName: "support-agent",
    agentVersion: "1.0.0",
    model: { provider: "openai", name: "gpt-5" },
  },
  input: {
    messages,
    systemPrompt: "You are a helpful support agent.",
    conversationPreview: "Summarize this customer note...",
  },
});

if (response.action === "deny") {
  throw new HookDeniedError(response.reason ?? "", response.ruleId, response.evaluations);
}

messages = response.transformedInput?.messages ?? messages;

与 failOpen: true,钩子运输错误的解决 允许一个没有评估者不会阻断生产流量。 设定 failOpen: false 用于关闭的严格路径.

如果您使用已转换的输入, 请将已转换的信件/系统提示传递给提供者, 并将相同的值记录在 startGeneration(...)。如果您使用 Vercel AI SDK 适配器,请参见 docs/frameworks/vercel-ai-sdk.md 用于自动飞行前接线.

在您的应用程序 OTEL SDK 设置中配置 OTEL 导出器( 追踪/ 测量) 。 你可以选择通过 tracer 财务报告和审定财务报表 meter 直接转到 SigilClient。 。 。 .

在创建 Sigil 客户端前快速 OTEL 设置模式 :

import { NodeSDK } from "@opentelemetry/sdk-node";

const otel = new NodeSDK();
await otel.start();

核心 API

  • startGeneration(...) 财务报告和审定财务报表 startStreamingGeneration(...)
  • startToolExecution(...)
  • 记录方法 : setResult(...), (中文(简体) ), setCallError(...), (中文(简体) ), end(), (中文(简体) ), getError()
  • 生命周期 : flush(), (中文(简体) ), shutdown()

手动 try/finally 样式

const recorder = client.startGeneration({
  model: { provider: "anthropic", name: "claude-sonnet-4-5" },
});

try {
  recorder.setResult({
    output: [{ role: "assistant", content: "Done" }],
  });
} catch (error) {
  recorder.setCallError(error);
  throw error;
} finally {
  recorder.end();
}

嵌入可观察性

使用 startEmbedding(...) 用于嵌入 API 调用。 嵌入式记录只创建OTel跨度和SDK度量衡,不为生成输出定序.

await client.startEmbedding(
  {
    agentName: "retrieval-worker",
    agentVersion: "1.0.0",
    model: { provider: "openai", name: "text-embedding-3-small" },
  },
  async (recorder) => {
    const response = await openai.embeddings.create(request);
    recorder.setResult({
      inputCount: request.input.length,
      inputTokens: response.usage?.prompt_tokens ?? 0,
      inputTexts: request.input,
      responseModel: response.model,
    });
  }
);

输入文本抓取为选入 :

const client = new SigilClient({
  embeddingCapture: {
    captureInput: true,
    maxInputItems: 20,
    maxTextLength: 1024,
  },
});

embeddingCapture.captureInput 可能以跨度显示PII/文件内容。 默认情况下保留其禁用并仅允许用于范围调试.

TrackQL 示例 :

  • traces{gen_ai.operation.name="embeddings"}
  • traces{gen_ai.operation.name="embeddings" && gen_ai.request.model="text-embedding-3-small"}
  • traces{gen_ai.operation.name="embeddings" && error.type!=""}

工具执行示例

await client.startToolExecution(
  {
    toolName: "weather",
    includeContent: true,
  },
  async (recorder) => {
    recorder.setResult({
      arguments: { city: "Paris" },
      result: { temp_c: 18 },
    });
  }
);

提供者助手

  • 打开AI : docs/providers/openai.md
  • 安东尼: docs/providers/anthropic.md
  • 双子座: docs/providers/gemini.md

框架处理器

使用模块子路径导出用于框架召回集成 :

  • 兰彩: @grafana/sigil-sdk-js/langchain
  • 兰格: @grafana/sigil-sdk-js/langgraph
  • OpenAI 代理 : @grafana/sigil-sdk-js/openai-agents
  • 拉玛因德克斯: @grafana/sigil-sdk-js/llamaindex
  • Google ADK: (英语) @grafana/sigil-sdk-js/google-adk
  • Vercel AI SDK: (中文(简体) ) @grafana/sigil-sdk-js/vercel-ai-sdk
  • 特工队: @grafana/sigil-sdk-js/strands
  • 兰彩指南: docs/frameworks/langchain.md
  • LangGraph 向导 : docs/frameworks/langgraph.md
  • OpenAI 代理指南 : docs/frameworks/openai-agents.md
  • LlamaIndex 指南 : docs/frameworks/llamaindex.md
  • 谷歌 ADK 指南 : docs/frameworks/google-adk.md
  • Vercel AI SDK指南: docs/frameworks/vercel-ai-sdk.md
  • Strands 代理指南 : docs/frameworks/strands.md
import { SigilClient } from "@grafana/sigil-sdk-js";
import { withSigilLangChainCallbacks } from "@grafana/sigil-sdk-js/langchain";
import { withSigilLangGraphCallbacks } from "@grafana/sigil-sdk-js/langgraph";
import { withSigilOpenAIAgentsHooks } from "@grafana/sigil-sdk-js/openai-agents";
import { withSigilLlamaIndexCallbacks } from "@grafana/sigil-sdk-js/llamaindex";
import { withSigilGoogleAdkPlugins } from "@grafana/sigil-sdk-js/google-adk";
import { createSigilVercelAiSdk } from "@grafana/sigil-sdk-js/vercel-ai-sdk";
import { withSigilStrandsHooks } from "@grafana/sigil-sdk-js/strands";
import { Runner } from "@openai/agents";
import { CallbackManager } from "llamaindex";

const client = new SigilClient();
const langChainConfig = withSigilLangChainCallbacks(undefined, client, { providerResolver: "auto" });
const langGraphConfig = withSigilLangGraphCallbacks(undefined, client, { providerResolver: "auto" });
const runner = new Runner();
const openAIAgentsHooks = withSigilOpenAIAgentsHooks(runner, client, { providerResolver: "auto" });
const callbackManager = new CallbackManager();
const llamaIndexConfig = withSigilLlamaIndexCallbacks({ callbackManager }, client, { providerResolver: "auto" });
const googleAdkRunnerConfig = withSigilGoogleAdkPlugins(undefined, client, { providerResolver: "auto" });
const vercelAiSdk = createSigilVercelAiSdk(client, { agentName: "vercel-agent" });
const strandsConfig = withSigilStrandsHooks(undefined, client, { conversationId: "chat-123" });

框架处理器使用 SigilClient 假设你通过。 如果客户端配置为 generationSanitizer,同样的编辑政策自动适用于记录的世代 通过LangChain,LangGraph,OpenAI Agents,LlamaIndex,Google ADK,和Vercel AI SDK集成. 同样的编辑政策也适用于斯特兰德斯代理世代.

每个框架处理器注入:

  • sigil.framework.name (单位:千美元)langchain, (中文(简体) ), langgraph, (中文(简体) ), openai-agents, (中文(简体) ), llamaindex, (中文(简体) ), google-adk, (中文(简体) ), vercel-ai-sdk,或 strands(中文(简体) )
  • sigil.framework.source (单位:千美元)handler 对于现有的召回处理器, framework 对于Vercel AI SDK钩, hooks 用于 Strands )
  • sigil.framework.language (单位:千美元)javascript 对于现有的召回处理器, typescript 为 Vercel AI SDK 和 Strands 钩)
  • metadata["sigil.framework.run_id"]
  • metadata["sigil.framework.thread_id"] (当有)
  • metadata["sigil.framework.parent_run_id"] (如有)
  • metadata["sigil.framework.component_name"]
  • metadata["sigil.framework.run_type"]
  • metadata["sigil.framework.tags"]
  • metadata["sigil.framework.retry_attempt"] (如有)
  • metadata["sigil.framework.event_id"] (如有)
  • metadata["sigil.framework.langgraph.node"] (可用时 LangGraph)

对话绘图是对话的第一:

  • conversation_id 编号 : session_id 编号 : group_id 从框架上下文
  • 接下来 thread_id
  • 决定性倒计时 sigil:framework:<framework_name>:<run_id>

当生成元数据中存在时,低心力框架密钥被复制到生成跨属性上.

对LangGraph的坚持,通过 configurable.thread_id 并反复使用它

const threadConfig = {
  ...withSigilLangGraphCallbacks(undefined, client, { providerResolver: "auto" }),
  configurable: { thread_id: 'customer-42' },
};
await graph.invoke({ prompt: 'Remember my timezone is UTC+1.', answer: '' }, threadConfig);
await graph.invoke({ prompt: 'What timezone did I give you?', answer: '' }, threadConfig);

行为

  • 生成模式是明确的: SYNC 财务报告和审定财务报表 STREAM。 。 。 .
  • 生成导出支持 HTTP, gRPC, 以及 none (仅以文书为主.
  • 追踪/测量使用 config.tracer编号 :config.meter 提供,否则 OTEL 全球.
  • 导出与被限制的队列和重试/后退同步 .
  • flush() 排出排队的世代; shutdown() 冲洗并关闭世代出口商.
  • 空工具名会生成一个禁用工具记录器.
  • 生成/工具跨度总是包括 SDK 身份属性:
    • sigil.sdk.name=sdk-js
  • 常态化生成元数据总是包括相同的SDK身份密钥;相冲突的调用器值被覆盖.
  • 原始提供者的文物选入(rawArtifacts: true) (中文(简体) ).

只使用仪器模式( 没有生成发送)

设定 generationExport.protocol 改为 "none" 保持生成/工具的仪器和跨度,同时使生成运输失效.

const client = new SigilClient({
  generationExport: {
    protocol: "none",
  },
});

SDK 度量衡

SDK通过您配置的 OTL 测量器提供商 来发布这些 OTel 直方图 :

  • gen_ai.client.operation.duration
  • gen_ai.client.token.usage
  • gen_ai.client.time_to_first_token
  • gen_ai.client.tool_calls_per_operation

生成导出认证模式

Auth 配置为 generationExport。 。 。 .

  • mode: "none"
  • mode: "tenant" (所需经费) tenantId输入 X-Scope-OrgID(中文(简体) )
  • mode: "bearer" (所需经费) bearerToken输入 Authorization: Bearer <token>(中文(简体) )
  • mode: "basic" (所需经费) basicPassword + 键 basicUser 或者说 tenantId输入 Authorization: Basic <base64(user:password)>; 还注入 X-Scope-OrgID 何时 tenantId 设定——仅用于多租户部署,格拉法纳云不需要)

在客户端配置解析时丢出无效的模式/字段组合 .

如果已包含明确的信头 Authorization 或者说 X-Scope-OrgID,明确标题优先.

const client = new SigilClient({
  generationExport: {
    protocol: "http",
    endpoint: "https://sigil-prod-<region>.grafana.net",
    auth: {
      mode: "basic",
      tenantId: process.env.SIGIL_AUTH_TENANT_ID,
      basicPassword: process.env.SIGIL_AUTH_TOKEN,
    },
  },
  api: {
    endpoint: "https://sigil-prod-<region>.grafana.net",
  },
});

Grafana Cloud auth( 基础) :

对于格拉法纳云,使用 basic 认证模式 。 用户名是您的 Grafana Cloud 实例/租户 ID 密码是您的 Grafana Cloud API 密钥 。 见 Grafana Cloud AI 开始观察文件 用于完整的设置步骤; 对于 SDK 端点, 复制 API 網址 从 Observation → AI observation → 配置看起来像 https://sigil-prod-<region>.grafana.net。 。 。 .

const client = new SigilClient({
  generationExport: {
    protocol: "http",
    endpoint: "https://sigil-prod-<region>.grafana.net",
    auth: {
      mode: "basic",
      tenantId: process.env.SIGIL_AUTH_TENANT_ID,
      basicPassword: process.env.SIGIL_AUTH_TOKEN,
    },
  },
});

如果您的部署需要不同的用户名, 设置 basicUser 明确:

auth: {
  mode: "basic",
  tenantId: process.env.SIGIL_AUTH_TENANT_ID,
  basicUser: process.env.SIGIL_AUTH_TENANT_ID,
  basicPassword: process.env.SIGIL_AUTH_TOKEN,
},

连接自定义环境 vars

SDK 只自动装入 SIGIL_* (原始内容存档于2013-10-12) (中文(简体) ). env vars (nSIGIL_ENDPOINT, (中文(简体) ), SIGIL_PROTOCOL, (中文(简体) ), SIGIL_AUTH_MODE, (中文(简体) ), SIGIL_AUTH_TOKEN当您打电话时 new SigilClient()。对于任何其他的 env var(例如您的秘密管理者以不同名称曝光的),请在您的应用程序中读取,并将值传递到配置中:

const generationBearerToken = (process.env.MY_APP_SIGIL_TOKEN ?? "").trim();

const client = new SigilClient({
  generationExport: {
    protocol: "http",
    endpoint: "https://sigil-prod-<region>.grafana.net",
    auth:
      generationBearerToken.length > 0
        ? { mode: "bearer", bearerToken: generationBearerToken }
        : {
            mode: "basic",
            tenantId: process.env.SIGIL_AUTH_TENANT_ID,
            basicPassword: process.env.SIGIL_AUTH_TOKEN,
          },
  },
  api: {
    endpoint: "https://sigil-prod-<region>.grafana.net",
  },
});

共同地貌学:

  • 格拉法纳云:一代人 basic 模式,带有实例 ID 和 API 密钥.
  • 自办直通西吉尔:一代 tenant 模式.
  • 通过 OTEL 收集器/合金进行追踪/测量:在您的应用程序 OTEL SDK 设置中配置出口商.
  • 企业代理: 生成 bearer 模式到代理;代理认证和向上转发租户头.

对话评分

使用 SDK 帮助提交用户化的收视率 :

const result = await client.submitConversationRating("conv-123", {
  ratingId: "rat-123",
  rating: "CONVERSATION_RATING_VALUE_BAD",
  comment: "Answer ignored user context",
  metadata: { channel: "assistant-ui" },
  source: "sdk-js",
});

console.log(result.rating.rating, result.summary.hasBadRating);

submitConversationRating 向 api.endpoint,它应该是来自AI可观察性配置的Grafana Cloud Sigil API URL,并使用SDK客户端已经配置的同一代导出认证头.

版本与发布记录

@grafana/sigil-sdk-js 共发布 13 个版本,首次发布于 2026/04/23;过去 12 个月发布了 13 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.8.2latest2026/07/164 个月前
0.8.12026/07/134 个月前
0.8.02026/06/135 个月前
0.7.02026/06/025 个月前
0.6.02026/05/285 个月前
0.5.02026/05/176 个月前

关于 @grafana/sigil-sdk-js 的常见问题

@grafana/sigil-sdk-js 是什么?

Sigil 记录 正常 LLM 生成和工具执行 遥测 使用您的 OpenTelemetrime tracker/ meter 设置 .注意:该包已被作者标记为弃用——Renamed to @grafana/agento11y. See https://grafana.com/docs/grafana-cloud/machine-learning/agent-observability/guides/migrate-sigil-sdk-to-agento11y/

如何安装 @grafana/sigil-sdk-js?

在项目目录运行 npm install @grafana/sigil-sdk-js,或使用 pnpm add / yarn add / bun add。

@grafana/sigil-sdk-js 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@grafana/sigil-sdk-js 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@grafana/sigil-sdk-js 可以商用吗?

@grafana/sigil-sdk-js 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@grafana/sigil-sdk-js 的下载量有多少?

根据 npm 官方下载统计,@grafana/sigil-sdk-js 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,085 次,日均约 303 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grafana/sigil-sdk-js 还在维护吗?

最新版本 0.8.2 发布于 2026/07/16(4 个月前);至今共发布 13 个版本,其中过去 12 个月发布了 13 个;首次发布于 2026/04/23。作者已将其标记为弃用,新项目建议寻找替代方案。