feat: Add traceable function wrapper for LangSmith tracing

[Jacob Lee (jacoblee93)]

Adds a traceable() API that wraps functions with LangSmith tracing — the Java/Kotlin equivalent of the @traceable decorator in the Python/JS SDKs.

Usage

Kotlin

import com.langchain.smith.client.okhttp.LangsmithOkHttpClient
import com.langchain.smith.tracing.traceable
import com.langchain.smith.tracing.TraceConfig
import com.langchain.smith.tracing.RunType

val client = LangsmithOkHttpClient.fromEnv()

// Wrap a function — name is inferred from the reference
fun answerQuestion(question: String): String = "42"
val traced = traceable(::answerQuestion, TraceConfig(client = client))
val result = traced("What is the meaning of life?")

// Or with explicit config
val tracedTool = traceable(
    { input: String -> "result for $input" },
    TraceConfig("my-tool", client = client, runType = RunType.TOOL, metadata = mapOf("version" to 1)),
)

Java

import com.langchain.smith.client.LangsmithClient;
import com.langchain.smith.client.okhttp.LangsmithOkHttpClient;
import com.langchain.smith.tracing.Tracing;
import com.langchain.smith.tracing.TraceConfig;

import java.util.function.Function;

LangsmithClient client = LangsmithOkHttpClient.fromEnv();

Function<String, String> traced = Tracing.traceable(
    (Function<String, String>) q -> "42",
    TraceConfig.builder()
        .name("answer-question")
        .client(client)
        .build());
String result = traced.apply("What is the meaning of life?");

Nested traces

Traced functions automatically nest — calling a traced function inside another creates a parent-child relationship in LangSmith. Child runs inherit client, projectName, executor, and tracingEnabled from their parent automatically.

Kotlin

val client = LangsmithOkHttpClient.fromEnv()

// Root — must provide client
val callLLM = traceable(
    { question: String ->
        openai.chat().completions().create(/* ... */)
    },
    TraceConfig("call-llm", client = client, runType = RunType.LLM),
)

// Children — no client needed, inherited from parent
val formatAnswer = traceable(
    { answer: String -> "The answer is: $answer" },
    TraceConfig("format-answer"),
)

val agent = traceable(
    { input: Map<String, Any?> ->
        val answer = callLLM(input["question"] as String)
        formatAnswer(answer)
    },
    TraceConfig("my-agent", client = client),
)

agent(mapOf("question" to "What is 2+2?"))

Java

LangsmithClient client = LangsmithOkHttpClient.fromEnv();

// Root — must provide client
Function<String, String> callLLM = Tracing.traceable(
    (Function<String, String>) question -> { /* call OpenAI */ return "4"; },
    TraceConfig.builder().name("call-llm").client(client).runType(RunType.LLM).build());

// Children — no client needed, inherited from parent
Function<String, String> formatAnswer = Tracing.traceable(
    (Function<String, String>) answer -> "The answer is: " + answer,
    TraceConfig.builder().name("format-answer").build());

Function<Map<String, Object>, String> agent = Tracing.traceable(
    (Function<Map<String, Object>, String>) input -> {
        String answer = callLLM.apply((String) input.get("question"));
        return formatAnswer.apply(answer);
    },
    TraceConfig.builder().name("my-agent").client(client).build());

agent.apply(Map.of("question", "What is 2+2?"));

Accessing and mutating the current run

Use getCurrentRunTree() inside a traced function to access the RunTree and attach metadata or extra data at runtime:

Kotlin

val traced = traceable({ input: String ->
    val run = getCurrentRunTree()!!
    run.metadata["custom_key"] = "custom_value"
    run.extra["usage"] = mapOf("tokens" to 42)
    "result"
}, TraceConfig("my-run", client = client))

Java

Function<String, String> traced = Tracing.traceable(
    (Function<String, String>) input -> {
        RunTree run = Tracing.getCurrentRunTree();
        run.getMetadata().put("custom_key", "custom_value");
        run.getExtra().put("usage", Map.of("tokens", 42));
        return "result";
    },
    TraceConfig.builder().name("my-run").client(client).build());

Creating RunTrees manually

RunTree can be constructed directly for custom integrations:

Kotlin

val run = RunTree(name = "my-run", runType = RunType.LLM, client = myClient)
val child = run.createChild(TraceConfig("child-step"))
child.inputs = mapOf("question" to "hello")

Java

RunTree run = RunTree.builder()
    .name("my-run")
    .runType(RunType.LLM)
    .client(client)
    .build();
RunTree child = run.createChild(TraceConfig.builder().name("child-step").build());
child.setInputs(Map.of("question", "hello"));

Default client

If LangsmithOkHttpClient is on the classpath and LANGSMITH_API_KEY is set, a default client is created automatically — no explicit client needed:

// Just works if LANGSMITH_API_KEY is set
val traced = traceable({ input: String -> "result" }, TraceConfig("my-func"))

Or set a default client explicitly:

setDefaultClient(LangsmithOkHttpClient.fromEnv())

Client resolution order: config → parent run → setDefaultClient() → auto-created from env → error.

Reusing configs

TraceConfig is immutable and safe to reuse. Create a base config and derive per-run configs with toBuilder():

Kotlin

val base = TraceConfig.builder().client(client).projectName("my-project").build()
val step1 = traceable({ ... }, base.toBuilder().name("step-1").build())
val step2 = traceable({ ... }, base.toBuilder().name("step-2").runType(RunType.LLM).build())

Java

TraceConfig base = TraceConfig.builder()
    .client(client)
    .projectName("my-project")
    .build();

var step1 = Tracing.traceable(..., base.toBuilder().name("step-1").build());
var step2 = Tracing.traceable(..., base.toBuilder().name("step-2").runType(RunType.LLM).build());

Async context propagation

Run context propagates automatically for synchronous nested calls. On Java 21+, ScopedValue is used, which also propagates into StructuredTaskScope child tasks. On older JVMs, ThreadLocal is used as a fallback.

Neither mechanism automatically propagates context across unstructured async boundaries such as CompletableFuture.supplyAsync, ExecutorService.submit, or Kotlin coroutines. For those cases, use getCurrentRunTree() + withParent():

Kotlin

val parent = getCurrentRunTree()
CompletableFuture.supplyAsync {
    withParent(parent) {
        tracedChild("input")
    }
}

Java

RunTree parent = Tracing.getCurrentRunTree();
CompletableFuture.supplyAsync(() ->
    Tracing.withParent(parent, () -> tracedChild.apply("input")));

Enabling tracing

Tracing is controlled by environment variables (matching the Python/JS SDKs):

export LANGSMITH_TRACING=true
# or: LANGSMITH_TRACING_V2, LANGCHAIN_TRACING, LANGCHAIN_TRACING_V2

Or per-config:

val traced = traceable({ "result" }, TraceConfig("my-func", tracingEnabled = true))

When disabled, traceable wrappers still execute the underlying function but skip all LangSmith communication (zero overhead).

What's included

• traceable() — top-level function overloads for 0/1/2/3-arg functions, with dual Kotlin lambda and Java functional interface (Supplier/Function/BiFunction/TriFunction) variants. From Java: Tracing.traceable(...).
• RunTree — public, mutable representation of a run. Constructable manually (Kotlin named args or Java builder). Methods: createChild(), postRun(), patchRun(), buildRunData().
• TraceConfig — configuration for a traced run (name, client, type, metadata, tags, project, executor, enabled). Kotlin named args constructor + Java Builder. Reusable via toBuilder().
• RunType — extensible run type with predefined constants (CHAIN, LLM, TOOL, RETRIEVER) and RunType.of("custom") for arbitrary values.
• getCurrentRunTree() — returns the current RunTree during execution. From Java: Tracing.getCurrentRunTree().
• setDefaultClient() — sets the global default client. From Java: Tracing.setDefaultClient(...).
• withParent() — manual context propagation for async boundaries. From Java: Tracing.withParent(...).
• RunContext — internal abstraction over ScopedValue (Java 21+) with ThreadLocal fallback.
• isTracingEnabled() — checks LANGSMITH_TRACING / LANGCHAIN_TRACING env vars and system properties.

Known limitations (v0)

• No streaming support — only synchronous function wrapping.
• No batching — each run posts/patches individually via ingestBatch. TODO to delegate to client-level background processing.
• 4+ arg functions — only up to 3 args supported.
• Non-map inputs/outputs — typed SDK objects (e.g. ChatCompletionCreateParams) fall back to toString(). Pass Map inputs/outputs for clean traces. processInputs/processOutputs callbacks are planned.
• Flush/shutdown — will be handled at the client level in a future release.
• OpenAI tool calling integration test — deferred until OpenAI SDK dependency is bumped (requires updating OTel wrappers for new abstract members).

[Rafid S (rx5ad)]

lgtm