@langchain/langsmith-opencode

Trace OpenCode sessions to LangSmith so you can inspect agent turns, tool calls, model metadata, token usage, and subagent activity within LangSmith.

What It Does

@langchain/langsmith-opencode is an OpenCode plugin that listens to OpenCode chat and event hooks, aggregates each user turn, and posts it to LangSmith as a run tree:

opencode.session root runs for each completed user turn.
opencode.assistant.turn child runs for assistant/model responses.
Tool calls as nested tool runs with inputs, outputs, errors, timing, and attachments when available.
Subagent sessions as nested traces under the parent tool call.
LangSmith metadata for model name, provider, invocation parameters, token usage, and thread/session ID.

Quick Start

Add the plugin to your OpenCode configuration file. You can configure it locally in opencode.json or globally in ~/.config/opencode/opencode.json:

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

Set your LangSmith credentials before starting OpenCode:

export LANGSMITH_API_KEY="lsv2_pt_..."
export TRACE_TO_LANGSMITH="true"

Then run OpenCode as usual. Completed turns will appear in the configured LangSmith project.

LangSmith API keys

To create an API key:

Go to smith.langchain.com.
Sign in or create an account.
Open Settings -> API Keys.
Click Create API Key.
Copy the key and set it as LANGSMITH_API_KEY, LANGSMITH_OPENCODE_API_KEY, or api_key in a local config file.

Configuration

Tracing is disabled by default. Enable it with TRACE_TO_LANGSMITH=true or with a config file.

Environment Variables

The plugin accepts OpenCode-specific LangSmith variables first, then falls back to the generic LangSmith SDK variables when available:

Variable	Required	Default	Description
`TRACE_TO_LANGSMITH`	Yes	`false`	Set to `"true"` to enable tracing.
`LANGSMITH_OPENCODE_API_KEY`	No*	-	LangSmith API key. Falls back to `LANGSMITH_API_KEY`. Required unless every replica provides its own API key.
`LANGSMITH_OPENCODE_ENDPOINT`	No	LangSmith SDK default	LangSmith API URL. Falls back to `LANGSMITH_ENDPOINT`.
`LANGSMITH_OPENCODE_PROJECT`	No	`opencode`	LangSmith project name. Falls back to `LANGSMITH_PROJECT`.
`LANGSMITH_OPENCODE_METADATA`	No	-	JSON object merged into root trace metadata.
`LANGSMITH_OPENCODE_RUNS_ENDPOINTS`	No	-	JSON array of replica destinations.

Example:

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_API_KEY="lsv2_pt_..."
export LANGSMITH_PROJECT="opencode"
export LANGSMITH_OPENCODE_METADATA='{"team":"agents","environment":"dev"}'

Config Files

Use .opencode/langsmith.json in your project for per-project settings, or ~/.config/opencode/langsmith.json for global defaults.

Field	Required	Default	Description
`enabled`	Yes	`false`	Set to `true` to enable tracing from the config file.
`api_key`	No*	-	LangSmith API key. Required unless provided by environment variable or replicas.
`api_url`	No	LangSmith SDK default	LangSmith API URL, usually `https://api.smith.langchain.com`.
`project`	No	`opencode`	LangSmith project name.
`metadata`	No	-	Object merged into root trace metadata.
`replicas`	No	-	Array of additional LangSmith destinations to replicate traces to.

{
  "enabled": true,
  "api_key": "lsv2_pt_...",
  "api_url": "https://api.smith.langchain.com",
  "project": "opencode",
  "metadata": {
    "team": "agents",
    "environment": "dev"
  },
  "replicas": [
    {
      "api_url": "https://api.smith.langchain.com",
      "api_key": "lsv2_pt_...",
      "project": "opencode-replica",
      "updates": {
        "metadata": {
          "replica": true
        }
      }
    }
  ]
}

api_key is required unless the API key is provided by environment variable. Keep config files with API keys out of version control.

Replica objects support both snake_case and LangSmith SDK-style camelCase field names. Snake_case is recommended in config files.

Field	Required	Description
`api_url` / `apiUrl`	No	LangSmith API URL for the replica destination.
`api_key` / `apiKey`	No	API key for the destination workspace.
`project` / `projectName`	No	Project name in the destination workspace.
`updates`	No	Optional run fields to override on replicated runs, such as extra metadata.

What Gets Traced

The plugin captures OpenCode session events and converts them into LangSmith-compatible chat messages and run metadata.

Captured content includes:

User messages, assistant messages, reasoning blocks, and file parts.
Tool calls, tool results, tool errors, and tool attachments.
System prompts associated with assistant turns.
Model and provider metadata from OpenCode.
Token usage from completed model steps when OpenCode provides it.
Session history so each assistant turn has the relevant chat context.

Trace completion is based on OpenCode step-finish events. When OpenCode disposes the server instance, the plugin flushes pending LangSmith trace batches.

Troubleshooting

If traces do not appear in LangSmith:

Confirm tracing is enabled with TRACE_TO_LANGSMITH=true or "enabled": true in config.
Confirm an API key is set in the same shell, project config, or global config used by OpenCode.
Confirm the plugin package is installed where OpenCode can resolve it.
Check the project selected in LangSmith. If no project is configured, traces go to opencode.
Restart OpenCode after changing opencode.json, langsmith.json, or environment variables.
Make sure a user turn completes; incomplete turns are not submitted as complete traces.