追踪 OpenCode 会话

在 LangSmith 中捕获 OpenCode 会话、助手轮次、工具调用和子 agent 活动。

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

前置条件

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

• 已安装并配置 OpenCode。
• 一个 LangSmith API key。
• 有权在 opencode.json 或 ~/.config/opencode/opencode.json 中配置 OpenCode 的 plugin 键。

安装并启用插件

将插件添加到 OpenCode 配置文件。你可以在 opencode.json 中本地配置，也可以在 ~/.config/opencode/opencode.json 中全局配置：

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

在启动 OpenCode 之前启用追踪并提供 LangSmith API key：

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_PROJECT="opencode"

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

配置追踪

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

环境变量

该插件会先读取 OpenCode 专用变量，然后再回退到通用的 LangSmith SDK 变量（如果可用）。

变量	必需	默认值	说明
TRACE_TO_LANGSMITH	是	false	设为 "true" 以启用追踪。
LANGSMITH_OPENCODE_API_KEY	视情况	-	LangSmith API key。回退到 LANGSMITH_API_KEY。除非每个副本都提供自己的 API key，否则为必需。
LANGSMITH_OPENCODE_ENDPOINT	否	LangSmith SDK 默认值	LangSmith API URL。回退到 LANGSMITH_ENDPOINT。
LANGSMITH_OPENCODE_PROJECT	否	opencode	LangSmith 项目名称。回退到 LANGSMITH_PROJECT。
LANGSMITH_OPENCODE_METADATA	否	-	合并到根追踪元数据中的 JSON 对象。
LANGSMITH_OPENCODE_RUNS_ENDPOINTS	否	-	副本目标的 JSON 数组。

例如：

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_PROJECT="opencode"
export LANGSMITH_OPENCODE_METADATA='{"team":"agents","environment":"dev"}'

配置文件

使用 .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"
  }
}

字段	必需	默认值	说明
enabled	是	false	设为 true 以从配置文件启用追踪。
api_key	视情况	-	LangSmith API key。除非由环境变量或副本提供，否则为必需。
api_url	否	LangSmith SDK 默认值	LangSmith API URL，通常为 https://api.smith.langchain.com。
project	否	opencode	LangSmith 项目名称。
metadata	否	-	合并到根追踪元数据中的对象。
replicas	否	-	将追踪复制到的其他 LangSmith 目标。

请勿将包含 API key 的配置文件纳入版本控制。

追踪到多个目标

在 langsmith.json 中设置 replicas，或设置 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_case 和 LangSmith SDK 风格的 camelCase 字段名。建议在配置文件中使用 snake_case。

字段	说明
api_url / apiUrl	副本目标的 LangSmith API URL。
api_key / apiKey	目标工作区的 API key。
project / projectName	目标工作区中的项目名称。
updates	可选，用于覆盖副本运行字段，例如额外元数据。

追踪内容

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

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

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

在 LangSmith 中查看追踪

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

故障排查

如果追踪未出现在 LangSmith 中：

• 确认已通过 TRACE_TO_LANGSMITH=true 或配置中的 "enabled": true 启用追踪。
• 确认 LangSmith API key 已设置在与 OpenCode 相同的 shell、项目配置或全局配置中。
• 确认插件包已安装在 OpenCode 能够解析的位置。
• 检查所选的 LangSmith 项目。如果未配置项目，追踪会发送到 opencode。
• 更改 opencode.json、langsmith.json 或环境变量后，请重启 OpenCode。
• 确保用户轮次已完成。插件不会发送未完成的轮次。

---