该 @langchain/langsmith-opencode 插件发送 OpenCode 会话追踪到 LangSmith。使用它检查代理轮次、模型元数据、令牌使用量、工具调用、工具错误、附件以及 OpenCode 工作流中的子代理活动。

前置要求

在设置追踪之前，请确保您具备：

• - OpenCode 已安装并配置。
• - A LangSmith API 密钥.
• - 配置 OpenCode 的权限 plugin 密钥在 opencode.json or ~/.config/opencode/opencode.json.

安装并启用插件

将插件添加到 OpenCode 配置文件中。您可以在本地配置 opencode.json 或全局配置 ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@langchain/langsmith-opencode"]
}

启动 OpenCode 之前启用追踪并提供您的 LangSmith API 密钥：

照常运行 OpenCode。插件将已完成的用户轮次发送到配置的 LangSmith 项目。

配置追踪

追踪默认禁用。设置 TRACE_TO_LANGSMITH=true 后，插件会将追踪发送到 LangSmith。您也可以使用 LangSmith 配置文件启用追踪。

环境变量

插件首先读取 OpenCode 特定变量，然后在可用时回退到通用 LangSmith SDK 变量。

例如：

配置文件

使用 .opencode/langsmith.json 进行项目级设置， ~/.config/opencode/langsmith.json 进行全局默认值设置。

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "api_url": "https://api.smith.langchain.com",
  "project": "opencode",
  "metadata": {
    "team": "agents",
    "environment": "dev"
  }
}

将包含 API 密钥的配置文件排除在版本控制之外。

跟踪到多个目的地

设置 replicas in langsmith.json or LANGSMITH_OPENCODE_RUNS_ENDPOINTS 用于将相同的跟踪数据发送到其他 LangSmith 工作区或项目。

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "project": "opencode",
  "replicas": [
    {
      "api_url": "https://api.smith.langchain.com",
      "api_key": "<your-replica-langsmith-api-key>",
      "project": "opencode-replica",
      "updates": {
        "metadata": {
          "replica": true
        }
      }
    }
  ]
}

副本对象同时支持 snake_命名法和 LangSmith SDK 风格的 camelCase 字段名。snake_命名法在配置文件中推荐使用。

跟踪内容

该插件监听 OpenCode 聊天和事件钩子，聚合每个已完成的用户轮次，并将其作为运行树提交给 LangSmith。

• - opencode.session 已完成用户轮次的根运行。
• - opencode.assistant.turn 助手和模型响应的子运行。
• - 工具调用的嵌套工具运行，包括输入、输出、错误、计时和附件（如果有）。
• - 嵌套在父工具调用下的子代理会话。
• - 模型名称、提供商、调用参数、令牌使用量以及线程或会话 ID 元数据。
• - 与助手轮次相关的用户消息、助手消息、推理块、文件部分和系统提示。

跟踪完成基于 OpenCode step-finish 事件。当 OpenCode 服务器关闭时，插件还会刷新待处理的跟踪批次。

在 LangSmith 中查看跟踪

打开已配置的 LangSmith 项目，查找名为 opencode.session的根运行。每个跟踪以用户轮次作为根输入，助手响应、工具调用和子代理跟踪作为子运行。该插件将 OpenCode 会话 ID 存储为 thread_id 元数据，因此您可以在 LangSmith 中过滤或分组相关的 OpenCode 轮次。

故障排除

如果跟踪未出现在 LangSmith 中：

• - 确认跟踪已在配置中启用 TRACE_TO_LANGSMITH=true or "enabled": true 中启用。
• - 确认 LangSmith API 密钥已设置在 OpenCode 使用的同一 shell、项目配置或全局配置中。
• - 确认插件包已安装在 OpenCode 可以解析的位置。
• - 检查已选择的 LangSmith 项目。如果未配置项目，跟踪将发送到 opencode.
• - 更改后重启 OpenCode opencode.json, langsmith.json或环境变量后。
• - 确保用户轮次已完成。插件不会发送未完成的轮次。