langsmith 0.10.5 → 0.10.7

package/dist/experimental/otel/constants.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AI_SDK_TOOL_OPERATIONS = exports.AI_SDK_LLM_OPERATIONS = exports.GEN_AI_CHOICE = exports.GEN_AI_ASSISTANT_MESSAGE = exports.GEN_AI_USER_MESSAGE = exports.GEN_AI_SYSTEM_MESSAGE = exports.LANGSMITH_TRACEABLE_PARENT_OTEL_SPAN_ID = exports.LANGSMITH_IS_ROOT = exports.LANGSMITH_TRACEABLE = exports.LANGSMITH_REFERENCE_EXAMPLE_ID = exports.LANGSMITH_USAGE_METADATA = exports.LANGSMITH_PARENT_RUN_ID = exports.LANGSMITH_DOTTED_ORDER = exports.LANGSMITH_TRACE_ID = exports.LANGSMITH_RUN_ID = exports.LANGSMITH_REQUEST_HEADERS = exports.LANGSMITH_REQUEST_STREAMING = exports.LANGSMITH_RUNTIME = exports.LANGSMITH_TAGS = exports.LANGSMITH_METADATA = exports.LANGSMITH_NAME = exports.LANGSMITH_RUN_TYPE = exports.LANGSMITH_SESSION_NAME = exports.LANGSMITH_SESSION_ID = exports.GEN_AI_USAGE_OUTPUT_TOKEN_DETAILS = exports.GEN_AI_USAGE_INPUT_TOKEN_DETAILS = exports.GEN_AI_RESPONSE_SYSTEM_FINGERPRINT = exports.GEN_AI_RESPONSE_SERVICE_TIER = exports.GEN_AI_RESPONSE_ID = exports.GEN_AI_SERIALIZED_DOC = exports.GEN_AI_SERIALIZED_SIGNATURE = exports.GEN_AI_SERIALIZED_NAME = exports.GEN_AI_REQUEST_EXTRA_BODY = exports.GEN_AI_REQUEST_EXTRA_QUERY = exports.GENAI_COMPLETION = exports.GENAI_PROMPT = exports.GEN_AI_RESPONSE_FINISH_REASONS = exports.GEN_AI_REQUEST_PRESENCE_PENALTY = exports.GEN_AI_REQUEST_FREQUENCY_PENALTY = exports.GEN_AI_REQUEST_TOP_P = exports.GEN_AI_REQUEST_TEMPERATURE = exports.GEN_AI_REQUEST_MAX_TOKENS = exports.GEN_AI_USAGE_TOTAL_TOKENS = exports.GEN_AI_USAGE_OUTPUT_TOKENS = exports.GEN_AI_USAGE_INPUT_TOKENS = exports.GEN_AI_RESPONSE_MODEL = exports.GEN_AI_REQUEST_MODEL = exports.GEN_AI_SYSTEM = exports.GEN_AI_OPERATION_NAME = void 0;
+exports.GEN_AI_CHOICE = exports.GEN_AI_ASSISTANT_MESSAGE = exports.GEN_AI_USER_MESSAGE = exports.GEN_AI_SYSTEM_MESSAGE = exports.LANGSMITH_TRACEABLE_PARENT_OTEL_SPAN_ID = exports.LANGSMITH_IS_ROOT = exports.LANGSMITH_TRACEABLE = exports.LANGSMITH_REFERENCE_EXAMPLE_ID = exports.LANGSMITH_USAGE_METADATA = exports.LANGSMITH_PARENT_RUN_ID = exports.LANGSMITH_DOTTED_ORDER = exports.LANGSMITH_TRACE_ID = exports.LANGSMITH_RUN_ID = exports.LANGSMITH_REQUEST_HEADERS = exports.LANGSMITH_REQUEST_STREAMING = exports.LANGSMITH_RUNTIME = exports.LANGSMITH_TAGS = exports.LANGSMITH_METADATA = exports.LANGSMITH_NAME = exports.LANGSMITH_RUN_TYPE = exports.LANGSMITH_SESSION_NAME = exports.LANGSMITH_SESSION_ID = exports.GEN_AI_USAGE_OUTPUT_TOKEN_DETAILS = exports.GEN_AI_USAGE_INPUT_TOKEN_DETAILS = exports.GEN_AI_RESPONSE_SYSTEM_FINGERPRINT = exports.GEN_AI_RESPONSE_SERVICE_TIER = exports.GEN_AI_TOOL_DEFINITIONS = exports.GEN_AI_TOOL_CALL_ID = exports.GEN_AI_TOOL_NAME = exports.GEN_AI_RESPONSE_ID = exports.GEN_AI_SERIALIZED_DOC = exports.GEN_AI_SERIALIZED_SIGNATURE = exports.GEN_AI_SERIALIZED_NAME = exports.GEN_AI_REQUEST_EXTRA_BODY = exports.GEN_AI_REQUEST_EXTRA_QUERY = exports.GENAI_COMPLETION = exports.GENAI_PROMPT = exports.GEN_AI_RESPONSE_FINISH_REASONS = exports.GEN_AI_REQUEST_PRESENCE_PENALTY = exports.GEN_AI_REQUEST_FREQUENCY_PENALTY = exports.GEN_AI_REQUEST_TOP_P = exports.GEN_AI_REQUEST_TEMPERATURE = exports.GEN_AI_REQUEST_MAX_TOKENS = exports.GEN_AI_USAGE_TOTAL_TOKENS = exports.GEN_AI_USAGE_OUTPUT_TOKENS = exports.GEN_AI_USAGE_INPUT_TOKENS = exports.GEN_AI_RESPONSE_MODEL = exports.GEN_AI_REQUEST_MODEL = exports.GEN_AI_SYSTEM = exports.GEN_AI_OPERATION_NAME = void 0;
+exports.AI_SDK_TOOL_OPERATIONS = exports.AI_SDK_LLM_OPERATIONS = void 0;
 // OpenTelemetry GenAI semantic convention attribute names
 exports.GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
 exports.GEN_AI_SYSTEM = "gen_ai.system";
@@ -23,6 +24,9 @@ exports.GEN_AI_SERIALIZED_NAME = "gen_ai.serialized.name";
 exports.GEN_AI_SERIALIZED_SIGNATURE = "gen_ai.serialized.signature";
 exports.GEN_AI_SERIALIZED_DOC = "gen_ai.serialized.doc";
 exports.GEN_AI_RESPONSE_ID = "gen_ai.response.id";
+exports.GEN_AI_TOOL_NAME = "gen_ai.tool.name";
+exports.GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id";
+exports.GEN_AI_TOOL_DEFINITIONS = "gen_ai.tool.definitions";
 exports.GEN_AI_RESPONSE_SERVICE_TIER = "gen_ai.response.service_tier";
 exports.GEN_AI_RESPONSE_SYSTEM_FINGERPRINT = "gen_ai.response.system_fingerprint";
 exports.GEN_AI_USAGE_INPUT_TOKEN_DETAILS = "gen_ai.usage.input_token_details";

package/dist/experimental/otel/constants.d.ts

@@ -19,6 +19,9 @@ export declare const GEN_AI_SERIALIZED_NAME = "gen_ai.serialized.name";
 export declare const GEN_AI_SERIALIZED_SIGNATURE = "gen_ai.serialized.signature";
 export declare const GEN_AI_SERIALIZED_DOC = "gen_ai.serialized.doc";
 export declare const GEN_AI_RESPONSE_ID = "gen_ai.response.id";
+export declare const GEN_AI_TOOL_NAME = "gen_ai.tool.name";
+export declare const GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id";
+export declare const GEN_AI_TOOL_DEFINITIONS = "gen_ai.tool.definitions";
 export declare const GEN_AI_RESPONSE_SERVICE_TIER = "gen_ai.response.service_tier";
 export declare const GEN_AI_RESPONSE_SYSTEM_FINGERPRINT = "gen_ai.response.system_fingerprint";
 export declare const GEN_AI_USAGE_INPUT_TOKEN_DETAILS = "gen_ai.usage.input_token_details";

package/dist/experimental/otel/constants.js

@@ -20,6 +20,9 @@ export const GEN_AI_SERIALIZED_NAME = "gen_ai.serialized.name";
 export const GEN_AI_SERIALIZED_SIGNATURE = "gen_ai.serialized.signature";
 export const GEN_AI_SERIALIZED_DOC = "gen_ai.serialized.doc";
 export const GEN_AI_RESPONSE_ID = "gen_ai.response.id";
+export const GEN_AI_TOOL_NAME = "gen_ai.tool.name";
+export const GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id";
+export const GEN_AI_TOOL_DEFINITIONS = "gen_ai.tool.definitions";
 export const GEN_AI_RESPONSE_SERVICE_TIER = "gen_ai.response.service_tier";
 export const GEN_AI_RESPONSE_SYSTEM_FINGERPRINT = "gen_ai.response.system_fingerprint";
 export const GEN_AI_USAGE_INPUT_TOKEN_DETAILS = "gen_ai.usage.input_token_details";

package/dist/experimental/otel/translator.cjs

@@ -203,6 +203,16 @@ class LangSmithToOTELTranslator {
         }
         // Set other parameters from invocation_params
         this.setInvocationParameters(span, runInfo);
+        if ("run_type" in runInfo && runInfo.run_type === "tool") {
+            if ("name" in runInfo && runInfo.name) {
+                span.setAttribute(constants.GEN_AI_TOOL_NAME, runInfo.name);
+            }
+            // Match Python: prefer extra.tool_call_id over metadata.tool_call_id.
+            const toolCallId = runInfo.extra?.tool_call_id || runInfo.extra?.metadata?.tool_call_id;
+            if (toolCallId != null) {
+                span.setAttribute(constants.GEN_AI_TOOL_CALL_ID, String(toolCallId));
+            }
+        }
         // Set metadata and tags if available
         const metadata = runInfo.extra?.metadata || {};
         for (const [key, value] of Object.entries(metadata)) {
@@ -289,6 +299,10 @@ class LangSmithToOTELTranslator {
         span.setAttribute(constants.GEN_AI_SYSTEM, system);
     }
     setInvocationParameters(span, runInfo) {
+        const tools = runInfo.extra?.invocation_params?.tools;
+        if (Array.isArray(tools) && tools.length > 0) {
+            span.setAttribute(constants.GEN_AI_TOOL_DEFINITIONS, JSON.stringify(tools));
+        }
         if (!runInfo.extra?.metadata?.invocation_params) {
             return;
         }

package/dist/experimental/otel/translator.js

@@ -167,6 +167,16 @@ export class LangSmithToOTELTranslator {
         }
         // Set other parameters from invocation_params
         this.setInvocationParameters(span, runInfo);
+        if ("run_type" in runInfo && runInfo.run_type === "tool") {
+            if ("name" in runInfo && runInfo.name) {
+                span.setAttribute(constants.GEN_AI_TOOL_NAME, runInfo.name);
+            }
+            // Match Python: prefer extra.tool_call_id over metadata.tool_call_id.
+            const toolCallId = runInfo.extra?.tool_call_id || runInfo.extra?.metadata?.tool_call_id;
+            if (toolCallId != null) {
+                span.setAttribute(constants.GEN_AI_TOOL_CALL_ID, String(toolCallId));
+            }
+        }
         // Set metadata and tags if available
         const metadata = runInfo.extra?.metadata || {};
         for (const [key, value] of Object.entries(metadata)) {
@@ -253,6 +263,10 @@ export class LangSmithToOTELTranslator {
         span.setAttribute(constants.GEN_AI_SYSTEM, system);
     }
     setInvocationParameters(span, runInfo) {
+        const tools = runInfo.extra?.invocation_params?.tools;
+        if (Array.isArray(tools) && tools.length > 0) {
+            span.setAttribute(constants.GEN_AI_TOOL_DEFINITIONS, JSON.stringify(tools));
+        }
         if (!runInfo.extra?.metadata?.invocation_params) {
             return;
         }

package/dist/index.cjs

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LS_MESSAGE_VIEW_EXCLUDE = exports.__version__ = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionTimeoutError = exports.APIConnectionError = exports.APIUserAbortError = exports.APIError = exports.LangsmithError = exports.promptCacheSingleton = exports.configureGlobalPromptCache = exports.PromptCache = exports.Cache = exports.isTracingEnabled = exports.uuid7FromTime = exports.uuid7 = exports.computeRunIdForSecondaryReplica = exports.getDefaultProjectName = exports.overrideFetchImplementation = exports.RunTree = exports.Client = void 0;
+exports.LS_MESSAGE_VIEW_EXCLUDE = exports.__version__ = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionTimeoutError = exports.APIConnectionError = exports.APIUserAbortError = exports.APIError = exports.LangsmithError = exports.promptCacheSingleton = exports.configureGlobalPromptCache = exports.PromptCache = exports.Cache = exports.isTracingEnabled = exports.uuid7FromTime = exports.uuid7 = exports.computeRunIdForSecondaryReplica = exports.getDefaultProjectName = exports.overrideFetchImplementation = exports.EnvAddressError = exports.RunTree = exports.Client = void 0;
 var client_js_1 = require("./client.cjs");
 Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
 var run_trees_js_1 = require("./run_trees.cjs");
 Object.defineProperty(exports, "RunTree", { enumerable: true, get: function () { return run_trees_js_1.RunTree; } });
+var address_js_1 = require("./address.cjs");
+Object.defineProperty(exports, "EnvAddressError", { enumerable: true, get: function () { return address_js_1.EnvAddressError; } });
 var fetch_js_1 = require("./singletons/fetch.cjs");
 Object.defineProperty(exports, "overrideFetchImplementation", { enumerable: true, get: function () { return fetch_js_1.overrideFetchImplementation; } });
 var project_js_1 = require("./utils/project.cjs");
@@ -35,6 +37,6 @@ Object.defineProperty(exports, "UnprocessableEntityError", { enumerable: true, g
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return error_js_1.RateLimitError; } });
 Object.defineProperty(exports, "InternalServerError", { enumerable: true, get: function () { return error_js_1.InternalServerError; } });
 // Update using pnpm bump-version
-exports.__version__ = "0.10.5";
+exports.__version__ = "0.10.7";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 exports.LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 export { Client, type ClientConfig, type LangSmithTracingClientInterface, } from "./client.js";
 export type { Dataset, Example, TracerSession, Run, Feedback, FeedbackConfigSchema, RetrieverOutput, } from "./schemas.js";
 export { RunTree, type RunTreeConfig, type WriteReplica } from "./run_trees.js";
+export { type Address, EnvAddressError } from "./address.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
 export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.js";
 export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, type CacheConfig, type CacheMetrics, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
-export declare const __version__ = "0.10.5";
+export declare const __version__ = "0.10.7";
 export declare const LS_MESSAGE_VIEW_EXCLUDE: "ls_message_view_exclude";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { Client, } from "./client.js";
 export { RunTree } from "./run_trees.js";
+export { EnvAddressError } from "./address.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
 export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.js";
@@ -7,6 +8,6 @@ export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
 // Update using pnpm bump-version
-export const __version__ = "0.10.5";
+export const __version__ = "0.10.7";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 export const LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/run_trees.cjs

@@ -10,11 +10,12 @@ const error_js_1 = require("./utils/error.cjs");
 const constants_js_1 = require("./singletons/constants.cjs");
 const context_vars_js_1 = require("./utils/context_vars.cjs");
 const env_js_2 = require("./utils/env.cjs");
-const project_js_1 = require("./utils/project.cjs");
 const env_js_3 = require("./utils/env.cjs");
 const warn_js_1 = require("./utils/warn.cjs");
 const _uuid_js_1 = require("./utils/_uuid.cjs");
 const index_js_1 = require("./utils/uuid/src/index.cjs");
+const agent_addressing_js_1 = require("./utils/agent_addressing.cjs");
+const address_js_1 = require("./address.cjs");
 const TIMESTAMP_LENGTH = 36;
 // DNS namespace for UUID v5 (same as Python's uuid.NAMESPACE_DNS)
 const UUID_NAMESPACE_DNS = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
@@ -49,7 +50,31 @@ const HEADER_SAFE_REPLICA_FIELDS = new Set([
     "primary",
     "updates",
     "reroot",
+    ...(0, address_js_1.wireKeys)(),
 ]);
+// URL-encoded JSON of the address's wire fields.
+const LANGSMITH_ADDRESS = "langsmith-address";
+/** Pops the address wire keys off untrusted `values`; never throws. */
+function takeHeaderAddress(values) {
+    const wire = {};
+    for (const key of (0, address_js_1.wireKeys)()) {
+        if (key in values) {
+            wire[key] = values[key];
+            delete values[key];
+        }
+    }
+    try {
+        return {
+            named: Object.keys(wire).length > 0,
+            address: (0, address_js_1.fromWire)(wire),
+        };
+    }
+    catch {
+        // Values are untrusted, so not logged.
+        console.warn("Ignoring an invalid address in a `baggage` header.");
+        return { named: true };
+    }
+}
 function filterReplicaForHeaders(replica) {
     const filtered = {};
     for (const key of Object.keys(replica)) {
@@ -66,7 +91,7 @@ function filterReplicaForHeaders(replica) {
  * Baggage header information
  */
 class Baggage {
-    constructor(metadata, tags, project_name, replicas) {
+    constructor(metadata, tags, project_name, replicas, address) {
         Object.defineProperty(this, "metadata", {
             enumerable: true,
             configurable: true,
@@ -91,10 +116,17 @@ class Baggage {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "address", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.metadata = metadata;
         this.tags = tags;
         this.project_name = project_name;
         this.replicas = replicas;
+        this.address = address;
     }
     static fromHeader(value) {
         const items = value.split(",");
@@ -102,6 +134,7 @@ class Baggage {
         let tags = [];
         let project_name;
         let replicas;
+        let address;
         for (const item of items) {
             const [key, uriValue] = item.split("=");
             const value = decodeURIComponent(uriValue);
@@ -114,17 +147,36 @@ class Baggage {
             else if (key === "langsmith-project") {
                 project_name = value;
             }
+            else if (key === LANGSMITH_ADDRESS) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(value);
+                }
+                catch {
+                    parsed = undefined;
+                }
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    address = takeHeaderAddress({ ...parsed }).address;
+                }
+            }
             else if (key === "langsmith-replicas") {
                 const parsed = JSON.parse(value);
-                replicas = parsed.map((replica) => {
+                replicas = parsed.flatMap((replica) => {
                     if (Array.isArray(replica)) {
-                        return replica;
+                        return [replica];
                     }
-                    return filterReplicaForHeaders(replica);
+                    const filtered = filterReplicaForHeaders(replica);
+                    const { named, address } = takeHeaderAddress(filtered);
+                    // A project wins over an address; a replica with an invalid
+                    // address and no project is dropped.
+                    if (filtered.projectName || !named) {
+                        return [filtered];
+                    }
+                    return address ? [{ ...filtered, address }] : [];
                 });
             }
         }
-        return new Baggage(metadata, tags, project_name, replicas);
+        return new Baggage(metadata, tags, project_name, replicas, address);
     }
     toHeader() {
         const items = [];
@@ -137,6 +189,9 @@ class Baggage {
         if (this.project_name) {
             items.push(`langsmith-project=${encodeURIComponent(this.project_name)}`);
         }
+        if (this.address) {
+            items.push(`${LANGSMITH_ADDRESS}=${encodeURIComponent(JSON.stringify((0, address_js_1.toWire)(this.address)))}`);
+        }
         return items.join(",");
     }
 }
@@ -164,12 +219,20 @@ class RunTree {
             writable: true,
             value: void 0
         });
+        /** Unset for a run sent to an `address`. */
         Object.defineProperty(this, "project_name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** (beta) Set instead of `project_name` for an addressed run. */
+        Object.defineProperty(this, "address", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "parent_run", {
             enumerable: true,
             configurable: true,
@@ -344,6 +407,7 @@ class RunTree {
             delete config.id;
         }
         Object.assign(this, { ...defaultConfig, ...config, client });
+        this._resolveAddressing(config);
         this.execution_order ??= 1;
         this.child_execution_order ??= 1;
         // Generate serialized start time for ID generation
@@ -374,6 +438,31 @@ class RunTree {
             }
         }
     }
+    /** Falls back to the env; a bad env leaves the run untraced. */
+    _resolveAddressing(config) {
+        const address = (0, agent_addressing_js_1.checkAddress)(config.address);
+        const project = config.project_name || undefined;
+        (0, agent_addressing_js_1.rejectConflicting)(project, address);
+        if (project || address) {
+            this.project_name = project;
+            this.address = address;
+            return;
+        }
+        try {
+            [this.project_name, this.address] = (0, agent_addressing_js_1.resolveFromEnv)();
+        }
+        catch (e) {
+            if (!(e instanceof address_js_1.EnvAddressError)) {
+                throw e;
+            }
+            if ((0, env_js_1.isEnvTracingEnabled)(this.tracingEnabled)) {
+                (0, agent_addressing_js_1.logUntraced)(e);
+            }
+            this.project_name = undefined;
+            this.address = undefined;
+            this.tracingEnabled = false;
+        }
+    }
     set metadata(metadata) {
         this.extra = {
             ...this.extra,
@@ -390,7 +479,6 @@ class RunTree {
         const start_time = Date.now();
         return {
             run_type: "chain",
-            project_name: (0, project_js_1.getDefaultProjectName)(),
             child_runs: [],
             api_url: (0, env_js_2.getEnvironmentVariable)("LANGCHAIN_ENDPOINT") ?? "http://localhost:1984",
             api_key: (0, env_js_2.getEnvironmentVariable)("LANGCHAIN_API_KEY"),
@@ -420,6 +508,7 @@ class RunTree {
             ...config,
             parent_run: this,
             project_name: this.project_name,
+            address: this.address,
             replicas: childReplicas,
             client: this.client,
             tracingEnabled: this.tracingEnabled,
@@ -518,6 +607,7 @@ class RunTree {
             inputs: run.inputs,
             outputs: run.outputs,
             session_name: run.project_name,
+            address: run.address,
             child_runs: child_runs,
             parent_run_id: parent_run_id,
             trace_id: run.trace_id,
@@ -574,16 +664,33 @@ class RunTree {
             child._setReplicaTraceRoot(replicaKey, traceRootId);
         }
     }
+    /** A replica naming neither inherits the run tree's destination. */
+    _replicaAddressing(replica) {
+        const address = (0, agent_addressing_js_1.checkAddress)(replica.address);
+        if (replica.projectName != null) {
+            (0, agent_addressing_js_1.rejectConflicting)(replica.projectName, address);
+            return [replica.projectName, undefined];
+        }
+        if (address) {
+            return [undefined, address];
+        }
+        return [this.project_name, this.address];
+    }
     _remapForProject(params) {
-        const { projectName, primary, runtimeEnv, excludeChildRuns = true, reroot = false, distributedParentId, apiUrl, apiKey, workspaceId, } = params;
+        const { projectName, address, primary, runtimeEnv, excludeChildRuns = true, reroot = false, distributedParentId, apiUrl, apiKey, workspaceId, } = params;
         const baseRun = this._convertToCreate(this, runtimeEnv, excludeChildRuns);
-        // Preserve legacy behavior when `primary` is omitted.
-        if (primary === undefined && projectName === this.project_name) {
+        // Preserve legacy behavior when `primary` is omitted, unless another replica is primary.
+        if (primary === undefined &&
+            !this.replicas?.some((r) => r.primary === true) &&
+            projectName === this.project_name &&
+            (0, address_js_1.sameAddress)(address, this.address)) {
             return {
                 ...baseRun,
                 session_name: projectName,
+                address,
             };
         }
+        const seed = projectName ?? (address ? (0, address_js_1.seed)(address) : undefined) ?? "agent//";
         // Apply reroot logic before ID remapping
         if (reroot) {
             if (distributedParentId) {
@@ -607,7 +714,7 @@ class RunTree {
             // Store this run's original ID in context vars so descendants know the new trace root
             // We store the original ID (before remapping) so it can be found in dotted_order
             const replicaKey = getReplicaKey({
-                projectName,
+                projectName: seed,
                 apiUrl,
                 apiKey,
                 workspaceId,
@@ -620,7 +727,7 @@ class RunTree {
         if (!reroot) {
             const replicaTraceRoots = (0, context_vars_js_1.getContextVar)(this, constants_js_1._REPLICA_TRACE_ROOTS_KEY) ?? {};
             const replicaKey = getReplicaKey({
-                projectName,
+                projectName: seed,
                 apiUrl,
                 apiKey,
                 workspaceId,
@@ -655,17 +762,18 @@ class RunTree {
             return {
                 ...baseRun,
                 session_name: projectName,
+                address,
             };
         }
         // Remap IDs for the replica using nonCryptographicUuid7Deterministic
         // This ensures consistency across runs in the same replica while
         // preserving UUID7 properties (time-ordering, monotonicity)
         const oldId = baseRun.id;
-        const newId = (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(oldId, projectName);
+        const newId = (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(oldId, seed);
         // Remap trace_id
         let newTraceId;
         if (baseRun.trace_id) {
-            newTraceId = (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(baseRun.trace_id, projectName);
+            newTraceId = (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(baseRun.trace_id, seed);
         }
         else {
             newTraceId = newId;
@@ -673,7 +781,7 @@ class RunTree {
         // Remap parent_run_id
         let newParentId;
         if (baseRun.parent_run_id) {
-            newParentId = (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(baseRun.parent_run_id, projectName);
+            newParentId = (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(baseRun.parent_run_id, seed);
         }
         // Remap dotted_order segments
         let newDottedOrder;
@@ -682,7 +790,7 @@ class RunTree {
             const remappedSegs = segs.map((seg) => {
                 // Extract the UUID from the segment (last TIMESTAMP_LENGTH characters)
                 const segId = seg.slice(-TIMESTAMP_LENGTH);
-                const remappedId = (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(segId, projectName);
+                const remappedId = (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(segId, seed);
                 // Replace the UUID part while keeping the timestamp prefix
                 return seg.slice(0, -TIMESTAMP_LENGTH) + remappedId;
             });
@@ -695,6 +803,7 @@ class RunTree {
             parent_run_id: newParentId,
             dotted_order: newDottedOrder,
             session_name: projectName,
+            address,
         };
     }
     async postRun(excludeChildRuns = true) {
@@ -705,9 +814,12 @@ class RunTree {
         try {
             const runtimeEnv = (0, env_js_2.getRuntimeEnvironment)();
             if (this.replicas && this.replicas.length > 0) {
-                for (const { projectName, primary, apiKey, apiUrl, workspaceId, reroot, client: replicaClient, } of this.replicas) {
+                for (const replica of this.replicas) {
+                    const { primary, apiKey, apiUrl, workspaceId, reroot, client: replicaClient, } = replica;
+                    const [projectName, address] = this._replicaAddressing(replica);
                     const runCreate = this._remapForProject({
-                        projectName: projectName ?? this.project_name,
+                        projectName,
+                        address,
                         primary,
                         runtimeEnv,
                         excludeChildRuns: true,
@@ -756,9 +868,12 @@ class RunTree {
     async patchRun(options) {
         const excludeInputs = options?.excludeInputs ?? getExcludeInputsOnPatch();
         if (this.replicas && this.replicas.length > 0) {
-            for (const { projectName, primary, apiKey, apiUrl, workspaceId, updates, reroot, client: replicaClient, } of this.replicas) {
+            for (const replica of this.replicas) {
+                const { primary, apiKey, apiUrl, workspaceId, updates, reroot, client: replicaClient, } = replica;
+                const [projectName, address] = this._replicaAddressing(replica);
                 const runData = this._remapForProject({
-                    projectName: projectName ?? this.project_name,
+                    projectName,
+                    address,
                     primary,
                     runtimeEnv: undefined,
                     excludeChildRuns: true,
@@ -777,6 +892,7 @@ class RunTree {
                     error: runData.error,
                     parent_run_id: runData.parent_run_id,
                     session_name: runData.session_name,
+                    address: runData.address,
                     reference_example_id: runData.reference_example_id,
                     end_time: runData.end_time,
                     dotted_order: runData.dotted_order,
@@ -819,6 +935,7 @@ class RunTree {
                     tags: this.tags,
                     attachments: this.attachments,
                     session_name: this.project_name,
+                    address: this.address,
                 };
                 // Important that inputs is not a key in the run update
                 // if excluded because it will overwrite the run create if the
@@ -879,7 +996,7 @@ class RunTree {
                 ...props,
                 client,
                 tracingEnabled,
-                project_name: projectName,
+                project_name: props.address ? undefined : projectName,
             });
         }
         const parentRunTree = new RunTree({
@@ -934,7 +1051,19 @@ class RunTree {
             const baggage = Baggage.fromHeader(rawHeaders["baggage"]);
             config.metadata = baggage.metadata;
             config.tags = baggage.tags;
-            config.project_name = baggage.project_name;
+            if (baggage.project_name && baggage.address) {
+                console.warn("Ignoring a `baggage` header that names both a project and an address.");
+                return undefined;
+            }
+            // The header's destination outranks the caller's.
+            if (baggage.project_name) {
+                config.project_name = baggage.project_name;
+                delete config.address;
+            }
+            else if (baggage.address) {
+                config.address = baggage.address;
+                delete config.project_name;
+            }
             config.replicas = baggage.replicas;
         }
         const runTree = new RunTree(config);
@@ -945,7 +1074,7 @@ class RunTree {
     toHeaders(headers) {
         const result = {
             "langsmith-trace": this.dotted_order,
-            baggage: new Baggage(this.extra?.metadata, this.tags, this.project_name, this.replicas).toHeader(),
+            baggage: new Baggage(this.extra?.metadata, this.tags, this.project_name, this.replicas, this.address).toHeader(),
         };
         if (headers) {
             for (const [key, value] of Object.entries(result)) {
@@ -1082,7 +1211,8 @@ function _ensureWriteReplicas(replicas) {
                     updates: replica[1],
                 };
             }
-            return replica;
+            const address = (0, agent_addressing_js_1.checkAddress)(replica.address);
+            return address ? { ...replica, address } : replica;
         })
         : _getWriteReplicasFromEnv();
     if (ensured.filter((replica) => replica.primary === true).length > 1) {

package/dist/run_trees.d.ts

@@ -1,5 +1,6 @@
 import { Client } from "./client.js";
 import { Attachments, BaseRun, KVMap, RunCreate } from "./schemas.js";
+import { type Address } from "./address.js";
 export declare function convertToDottedOrderFormat(epoch: number, runId: string, executionOrder?: number): {
     dottedOrder: string;
     microsecondPrecisionDatestring: string;
@@ -9,6 +10,8 @@ export interface RunTreeConfig {
     run_type?: string;
     id?: string;
     project_name?: string;
+    /** (beta) Send the run to this address instead of a project. */
+    address?: Address;
     parent_run?: RunTree;
     parent_run_id?: string;
     child_runs?: RunTree[];
@@ -60,6 +63,8 @@ export type WriteReplica = {
     apiKey?: string;
     workspaceId?: string;
     projectName?: string;
+    /** (beta) Send the replica to this address instead of a project. */
+    address?: Address;
     /** Whether this replica keeps the original run IDs. */
     primary?: boolean;
     updates?: KVMap | undefined;
@@ -79,7 +84,10 @@ export declare class RunTree implements BaseRun {
     id: string;
     name: RunTreeConfig["name"];
     run_type: string;
-    project_name: string;
+    /** Unset for a run sent to an `address`. */
+    project_name?: string;
+    /** (beta) Set instead of `project_name` for an addressed run. */
+    address?: Address;
     parent_run?: RunTree;
     parent_run_id?: string;
     child_runs: RunTree[];
@@ -114,6 +122,8 @@ export declare class RunTree implements BaseRun {
      */
     private _serialized_start_time;
     constructor(originalConfig: RunTreeConfig | RunTree);
+    /** Falls back to the env; a bad env leaves the run untraced. */
+    private _resolveAddressing;
     set metadata(metadata: KVMap);
     get metadata(): KVMap;
     private static getDefaultConfig;
@@ -123,6 +133,8 @@ export declare class RunTree implements BaseRun {
     private _convertToCreate;
     private _sliceParentId;
     private _setReplicaTraceRoot;
+    /** A replica naming neither inherits the run tree's destination. */
+    private _replicaAddressing;
     private _remapForProject;
     postRun(excludeChildRuns?: boolean): Promise<void>;
     /**