langsmith 0.10.11 → 0.10.13

package/resources/traces.d.mts

@@ -32,6 +32,10 @@ export declare class Traces extends APIResource {
      * Supports filters (`trace_filter`, `tree_filter`), cursor pagination (`cursor`),
      * and field projection (`selects`).
      *
+     * When `ai_search` is set, `Accept: text/event-stream` is required; requests
+     * without it return 406. AI search is unavailable on deployments that route
+     * queries to the v1 backend and returns 501 there.
+     *
      * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
@@ -42,7 +46,7 @@ export declare class Traces extends APIResource {
      * }
      * ```
      */
-    query(body: TraceQueryParams, options?: RequestOptions): PagePromise<TracesItemsCursorPostPagination, Trace>;
+    query(params: TraceQueryParams, options?: RequestOptions): PagePromise<TracesItemsCursorPostPagination, Trace>;
 }
 export type TracesItemsCursorPostPagination = ItemsCursorPostPagination<Trace>;
 export interface Trace {
@@ -125,46 +129,60 @@ export interface TraceListRunsParams {
 }
 export interface TraceQueryParams extends ItemsCursorPostPaginationParams {
     /**
-     * `max_start_time` is the exclusive upper bound for the root-run start time scan
-     * (RFC3339). Defaults to the request time when omitted.
+     * Body param: `ai_search` is a plain-language criterion evaluated against the
+     * messages from the agent trajectory scoped to the trace. AND-ed with the ordinary
+     * filters. Requires semantic filtering enabled for the deployment. Must contain
+     * nonempty text of at most 2000 UTF-8 bytes.
+     */
+    ai_search?: string;
+    /**
+     * Body param: `max_start_time` is the exclusive upper bound for the root-run start
+     * time scan (RFC3339). Defaults to the request time when omitted.
      */
     max_start_time?: string;
     /**
-     * `min_start_time` is the inclusive lower bound for the root-run start time scan
-     * (RFC3339). Defaults to 24 hours before the request when omitted.
+     * Body param: `min_start_time` is the inclusive lower bound for the root-run start
+     * time scan (RFC3339). Defaults to 24 hours before the request when omitted.
      */
     min_start_time?: string;
     /**
-     * `project_id` is the UUID of the tracing project that owns the traces. Required.
+     * Body param: `project_id` is the UUID of the tracing project that owns the
+     * traces. Required.
      */
     project_id?: string;
     /**
-     * `selects` lists which properties to include on each returned trace. Properties
-     * listed here are routed to the appropriate sub-object on each item:
+     * Body param: `selects` lists which properties to include on each returned trace.
+     * Properties listed here are routed to the appropriate sub-object on each item:
      * `total_tokens`, `total_cost`, and `first_token_time` appear under
      * `trace_aggregates`; everything else appears under `root_run`. If omitted, only
      * `id` is returned on `root_run`.
      */
     selects?: Array<RunsAPI.RunSelectField>;
     /**
-     * `trace_filter` narrows results to traces whose root run matches this LangSmith
-     * filter expression. This filter targets root runs only — `is_root = true` is
-     * implied. See
+     * Body param: `trace_filter` narrows results to traces whose root run matches this
+     * LangSmith filter expression. This filter targets root runs only —
+     * `is_root = true` is implied. See
      * https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language
      * for syntax.
      */
     trace_filter?: string;
     /**
-     * `trace_ids` is an optional fast-path restriction to a known set of trace UUIDs.
-     * Equivalent in result to including each UUID in a `trace_filter`, but more
-     * efficient at scale.
+     * Body param: `trace_ids` is an optional fast-path restriction to a known set of
+     * trace UUIDs. Equivalent in result to including each UUID in a `trace_filter`,
+     * but more efficient at scale.
      */
     trace_ids?: Array<string>;
     /**
-     * `tree_filter` narrows results to traces containing at least one run anywhere in
-     * the run tree (root or descendant) that matches this LangSmith filter expression.
+     * Body param: `tree_filter` narrows results to traces containing at least one run
+     * anywhere in the run tree (root or descendant) that matches this LangSmith filter
+     * expression.
      */
     tree_filter?: string;
+    /**
+     * Header param: application/json, or text/event-stream (required when ai_search is
+     * set)
+     */
+    Accept?: string;
 }
 export declare namespace Traces {
     export { type Trace as Trace, type TraceAggregates as TraceAggregates, type TraceListRunsResponse as TraceListRunsResponse, type TracesItemsCursorPostPagination as TracesItemsCursorPostPagination, type TraceListRunsParams as TraceListRunsParams, type TraceQueryParams as TraceQueryParams, };

package/resources/traces.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"traces.d.mts","sourceRoot":"","sources":["../src/resources/traces.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"traces.d.mts","sourceRoot":"","sources":["../src/resources/traces.ts"],"names":[],"mappings":"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"}

package/resources/traces.d.ts

@@ -32,6 +32,10 @@ export declare class Traces extends APIResource {
      * Supports filters (`trace_filter`, `tree_filter`), cursor pagination (`cursor`),
      * and field projection (`selects`).
      *
+     * When `ai_search` is set, `Accept: text/event-stream` is required; requests
+     * without it return 406. AI search is unavailable on deployments that route
+     * queries to the v1 backend and returns 501 there.
+     *
      * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
@@ -42,7 +46,7 @@ export declare class Traces extends APIResource {
      * }
      * ```
      */
-    query(body: TraceQueryParams, options?: RequestOptions): PagePromise<TracesItemsCursorPostPagination, Trace>;
+    query(params: TraceQueryParams, options?: RequestOptions): PagePromise<TracesItemsCursorPostPagination, Trace>;
 }
 export type TracesItemsCursorPostPagination = ItemsCursorPostPagination<Trace>;
 export interface Trace {
@@ -125,46 +129,60 @@ export interface TraceListRunsParams {
 }
 export interface TraceQueryParams extends ItemsCursorPostPaginationParams {
     /**
-     * `max_start_time` is the exclusive upper bound for the root-run start time scan
-     * (RFC3339). Defaults to the request time when omitted.
+     * Body param: `ai_search` is a plain-language criterion evaluated against the
+     * messages from the agent trajectory scoped to the trace. AND-ed with the ordinary
+     * filters. Requires semantic filtering enabled for the deployment. Must contain
+     * nonempty text of at most 2000 UTF-8 bytes.
+     */
+    ai_search?: string;
+    /**
+     * Body param: `max_start_time` is the exclusive upper bound for the root-run start
+     * time scan (RFC3339). Defaults to the request time when omitted.
      */
     max_start_time?: string;
     /**
-     * `min_start_time` is the inclusive lower bound for the root-run start time scan
-     * (RFC3339). Defaults to 24 hours before the request when omitted.
+     * Body param: `min_start_time` is the inclusive lower bound for the root-run start
+     * time scan (RFC3339). Defaults to 24 hours before the request when omitted.
      */
     min_start_time?: string;
     /**
-     * `project_id` is the UUID of the tracing project that owns the traces. Required.
+     * Body param: `project_id` is the UUID of the tracing project that owns the
+     * traces. Required.
      */
     project_id?: string;
     /**
-     * `selects` lists which properties to include on each returned trace. Properties
-     * listed here are routed to the appropriate sub-object on each item:
+     * Body param: `selects` lists which properties to include on each returned trace.
+     * Properties listed here are routed to the appropriate sub-object on each item:
      * `total_tokens`, `total_cost`, and `first_token_time` appear under
      * `trace_aggregates`; everything else appears under `root_run`. If omitted, only
      * `id` is returned on `root_run`.
      */
     selects?: Array<RunsAPI.RunSelectField>;
     /**
-     * `trace_filter` narrows results to traces whose root run matches this LangSmith
-     * filter expression. This filter targets root runs only — `is_root = true` is
-     * implied. See
+     * Body param: `trace_filter` narrows results to traces whose root run matches this
+     * LangSmith filter expression. This filter targets root runs only —
+     * `is_root = true` is implied. See
      * https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language
      * for syntax.
      */
     trace_filter?: string;
     /**
-     * `trace_ids` is an optional fast-path restriction to a known set of trace UUIDs.
-     * Equivalent in result to including each UUID in a `trace_filter`, but more
-     * efficient at scale.
+     * Body param: `trace_ids` is an optional fast-path restriction to a known set of
+     * trace UUIDs. Equivalent in result to including each UUID in a `trace_filter`,
+     * but more efficient at scale.
      */
     trace_ids?: Array<string>;
     /**
-     * `tree_filter` narrows results to traces containing at least one run anywhere in
-     * the run tree (root or descendant) that matches this LangSmith filter expression.
+     * Body param: `tree_filter` narrows results to traces containing at least one run
+     * anywhere in the run tree (root or descendant) that matches this LangSmith filter
+     * expression.
      */
     tree_filter?: string;
+    /**
+     * Header param: application/json, or text/event-stream (required when ai_search is
+     * set)
+     */
+    Accept?: string;
 }
 export declare namespace Traces {
     export { type Trace as Trace, type TraceAggregates as TraceAggregates, type TraceListRunsResponse as TraceListRunsResponse, type TracesItemsCursorPostPagination as TracesItemsCursorPostPagination, type TraceListRunsParams as TraceListRunsParams, type TraceQueryParams as TraceQueryParams, };

package/resources/traces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traces.d.ts","sourceRoot":"","sources":["../src/resources/traces.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"traces.d.ts","sourceRoot":"","sources":["../src/resources/traces.ts"],"names":[],"mappings":"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"}

package/resources/traces.js

@@ -42,6 +42,10 @@ class Traces extends resource_1.APIResource {
      * Supports filters (`trace_filter`, `tree_filter`), cursor pagination (`cursor`),
      * and field projection (`selects`).
      *
+     * When `ai_search` is set, `Accept: text/event-stream` is required; requests
+     * without it return 406. AI search is unavailable on deployments that route
+     * queries to the v1 backend and returns 501 there.
+     *
      * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
@@ -52,11 +56,13 @@ class Traces extends resource_1.APIResource {
      * }
      * ```
      */
-    query(body, options) {
+    query(params, options) {
+        const { Accept, ...body } = params;
         return this._client.getAPIList('/api/v2/traces/query', (pagination_1.ItemsCursorPostPagination), {
             body,
             method: 'post',
             ...options,
+            headers: (0, headers_1.buildHeaders)([{ ...(Accept != null ? { Accept: Accept } : undefined) }, options?.headers]),
         });
     }
 }

package/resources/traces.js.map

@@ -1 +1 @@
-{"version":3,"file":"traces.js","sourceRoot":"","sources":["../src/resources/traces.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAG/C,sDAI4B;AAC5B,oDAAmD;AAEnD,oDAA8C;AAE9C,MAAa,MAAO,SAAQ,sBAAW;IACrC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CACN,OAAe,EACf,MAA2B,EAC3B,OAAwB;QAExB,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,kBAAkB,OAAO,OAAO,EAAE;YAC5D,KAAK;YACL,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SACpG,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CACH,IAAsB,EACtB,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAA,sCAAgC,CAAA,EAAE;YACvF,IAAI;YACJ,MAAM,EAAE,MAAM;YACd,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF;AA7DD,wBA6DC"}
+{"version":3,"file":"traces.js","sourceRoot":"","sources":["../src/resources/traces.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAG/C,sDAI4B;AAC5B,oDAAmD;AAEnD,oDAA8C;AAE9C,MAAa,MAAO,SAAQ,sBAAW;IACrC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CACN,OAAe,EACf,MAA2B,EAC3B,OAAwB;QAExB,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,kBAAkB,OAAO,OAAO,EAAE;YAC5D,KAAK;YACL,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SACpG,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,KAAK,CACH,MAAwB,EACxB,OAAwB;QAExB,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAA,sCAAgC,CAAA,EAAE;YACvF,IAAI;YACJ,MAAM,EAAE,MAAM;YACd,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SACpG,CAAC,CAAC;IACL,CAAC;CACF;AAnED,wBAmEC"}

package/resources/traces.mjs

@@ -39,6 +39,10 @@ export class Traces extends APIResource {
      * Supports filters (`trace_filter`, `tree_filter`), cursor pagination (`cursor`),
      * and field projection (`selects`).
      *
+     * When `ai_search` is set, `Accept: text/event-stream` is required; requests
+     * without it return 406. AI search is unavailable on deployments that route
+     * queries to the v1 backend and returns 501 there.
+     *
      * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
@@ -49,11 +53,13 @@ export class Traces extends APIResource {
      * }
      * ```
      */
-    query(body, options) {
+    query(params, options) {
+        const { Accept, ...body } = params;
         return this._client.getAPIList('/api/v2/traces/query', (ItemsCursorPostPagination), {
             body,
             method: 'post',
             ...options,
+            headers: buildHeaders([{ ...(Accept != null ? { Accept: Accept } : undefined) }, options?.headers]),
         });
     }
 }

package/resources/traces.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"traces.mjs","sourceRoot":"","sources":["../src/resources/traces.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAG/C,OAAO,EACL,yBAAyB,GAG1B,+BAA2B;AAC5B,OAAO,EAAE,YAAY,EAAE,gCAA4B;AAEnD,OAAO,EAAE,IAAI,EAAE,mCAA+B;AAE9C,MAAM,OAAO,MAAO,SAAQ,WAAW;IACrC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CACN,OAAe,EACf,MAA2B,EAC3B,OAAwB;QAExB,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,kBAAkB,OAAO,OAAO,EAAE;YAC5D,KAAK;YACL,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SACpG,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CACH,IAAsB,EACtB,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAA,yBAAgC,CAAA,EAAE;YACvF,IAAI;YACJ,MAAM,EAAE,MAAM;YACd,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"traces.mjs","sourceRoot":"","sources":["../src/resources/traces.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAG/C,OAAO,EACL,yBAAyB,GAG1B,+BAA2B;AAC5B,OAAO,EAAE,YAAY,EAAE,gCAA4B;AAEnD,OAAO,EAAE,IAAI,EAAE,mCAA+B;AAE9C,MAAM,OAAO,MAAO,SAAQ,WAAW;IACrC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CACN,OAAe,EACf,MAA2B,EAC3B,OAAwB;QAExB,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,kBAAkB,OAAO,OAAO,EAAE;YAC5D,KAAK;YACL,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SACpG,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,KAAK,CACH,MAAwB,EACxB,OAAwB;QAExB,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAA,yBAAgC,CAAA,EAAE;YACvF,IAAI;YACJ,MAAM,EAAE,MAAM;YACd,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SACpG,CAAC,CAAC;IACL,CAAC;CACF"}

package/src/lib/address.ts

@@ -26,32 +26,67 @@ export type Environment = "local" | "development" | "staging" | "production";
  */
 export type Lrn = `lrn:agents/${string}/environments/${Environment}`;
 
-/** (beta) The backend's form of an address, as the resolve endpoint takes it. */
-export type ApiAddress = {
-  kind: "AGENT" | "EXPERIMENT" | "EVALUATOR";
-  id?: string;
-  environment?: Uppercase<Environment>;
-};
+/** (beta) The address of an agent's environment. */
+export interface AgentAddress {
+  kind: "AGENT";
+  id: string;
+  environment: Uppercase<Environment>;
+}
 
-/** (beta) A feature that holds traces in a tracing project. */
-export interface Address {
-  /** The address in the backend's form. */
-  toApiAddress(): ApiAddress;
+/** (beta) Construct and validate an agent address; plain objects are also accepted. */
+export class AgentAddress {
+  constructor(id: string, environment: Environment | (string & {})) {
+    const address = ensureAgent({ kind: "AGENT", id, environment });
+    this.kind = address.kind;
+    this.id = address.id;
+    this.environment = address.environment;
+    Object.freeze(this);
+  }
+}
+
+/** (beta) The address of an experiment's tracing project. */
+export interface ExperimentAddress {
+  kind: "EXPERIMENT";
+  id: string;
+}
+
+/** (beta) Construct and validate an experiment address. */
+export class ExperimentAddress {
+  constructor(id: string) {
+    const address = ensureAddress({ kind: "EXPERIMENT", id });
+    this.kind = address.kind;
+    this.id = address.id;
+    Object.freeze(this);
+  }
+}
+
+/** (beta) The address of the workspace's shared evaluators project. */
+export interface EvaluatorAddress {
+  kind: "EVALUATOR";
 }
 
+/** (beta) Construct the workspace's evaluators address. */
+export class EvaluatorAddress {
+  constructor() {
+    this.kind = "EVALUATOR";
+    Object.freeze(this);
+  }
+}
+
+/** (beta) A feature that holds traces in a tracing project. */
+export type Address = AgentAddress | ExperimentAddress | EvaluatorAddress;
+
+/** (beta) An address as the resolve endpoint takes it. */
+export type ApiAddress = Address;
+
 const UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // The server's agent id rule: a DNS label, so a hostname can carry the id.
 const AGENT_ID_PATTERN = /^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/;
-const ENVIRONMENTS: string[] = [
-  "local",
-  "development",
-  "staging",
-  "production",
-];
-
-// The wire form of an agent address. The parts are validated by `AgentAddress`.
+const ENVIRONMENTS = ["local", "development", "staging", "production"];
+
+// The wire form of an agent address. The parts are validated at entrypoints.
 const LRN_PATTERN = /^lrn:agents\/([^/]+)\/environments\/([^/]+)$/;
 
 const ENV_NAMES = ["LANGSMITH_AGENT_ID", "LANGSMITH_AGENT_ENVIRONMENT"];
@@ -64,189 +99,112 @@ export class EnvAddressError extends Error {
   }
 }
 
-/**
- * (beta) The address of an agent's environment.
- *
- * @example
- * ```ts
- * new AgentAddress("customer-support", "production");
- * ```
- */
-export class AgentAddress implements Address {
-  readonly id: string;
-
-  /** Always lowercase. */
-  readonly environment: Environment;
-
-  /**
-   * @param id 1 to 63 lowercase ASCII letters, digits or hyphens, starting
-   *   with a letter and ending with a letter or digit. The server creates the
-   *   agent on first use.
-   * @param environment One of `local`, `development`, `staging` or `production`, in
-   *   any case.
-   * @throws If a value is invalid.
-   */
-  constructor(id: string, environment: Environment | (string & {})) {
-    if (typeof id !== "string" || !AGENT_ID_PATTERN.test(id)) {
-      throw new Error(
-        "Address agent id must be 1 to 63 lowercase ASCII letters, digits, or " +
-          "hyphens, start with a letter, and end with a letter or digit, got " +
-          `${JSON.stringify(id)}. Use an id such as "support-agent".`,
-      );
-    }
-    const normalized =
-      typeof environment === "string" ? environment.toLowerCase() : undefined;
-    if (normalized === undefined || !ENVIRONMENTS.includes(normalized)) {
-      throw new Error(
-        `Address environment must be one of ${ENVIRONMENTS.join(", ")}, got ` +
-          `${JSON.stringify(environment)}.`,
-      );
-    }
-    this.id = id;
-    this.environment = normalized as Environment;
-    Object.freeze(this);
-  }
-
-  toApiAddress(): ApiAddress {
-    return {
-      kind: "AGENT",
-      id: this.id,
-      environment: this.environment.toUpperCase() as Uppercase<Environment>,
-    };
-  }
-
-  /** @internal */
-  _toLrn(): Lrn {
-    return `lrn:agents/${this.id}/environments/${this.environment}`;
-  }
-
-  /**
-   * @internal Parse an LRN read from the wire, such as a `baggage` header. The
-   * value is untrusted, so it is not echoed in the error.
-   * @throws If `value` is not an agent LRN, or names an invalid id or environment.
-   */
-  static _fromLrn(value: unknown): AgentAddress {
-    const match = typeof value === "string" ? LRN_PATTERN.exec(value) : null;
-    if (match === null) {
-      throw new Error("Not an agent address.");
-    }
-    return new AgentAddress(match[1], match[2]);
-  }
-
-  /**
-   * Read the agent named by `LANGSMITH_AGENT_ID` and
-   * `LANGSMITH_AGENT_ENVIRONMENT`; `undefined` if neither is set.
-   * @throws {EnvAddressError} If only one is set, or a value is invalid.
-   */
-  static fromEnv(): AgentAddress | undefined {
-    const values = ENV_NAMES.map((name) => getEnvironmentVariable(name));
-    if (!values.some(Boolean)) {
-      return undefined;
-    }
-    try {
-      const missing = ENV_NAMES.filter((_, i) => !values[i]);
-      if (missing.length > 0) {
-        throw new Error(`An address needs ${missing.join(" and ")} as well.`);
-      }
-      return new AgentAddress(values[0] as string, values[1] as string);
-    } catch (e) {
-      const present = ENV_NAMES.flatMap((name, i) =>
-        values[i] ? [`${name}=${JSON.stringify(values[i])}`] : [],
-      ).join(", ");
-      throw new EnvAddressError(
-        `The LANGSMITH_AGENT_* env vars can't address a run (${present}): ${
-          (e as Error).message
-        }`,
-      );
-    }
+/** Validate an address at an SDK entrypoint and return a normalized copy. */
+export function ensureAddress<K extends Address["kind"]>(value: {
+  kind: K;
+  id?: unknown;
+  environment?: unknown;
+}): Extract<Address, { kind: K }>;
+export function ensureAddress(value: unknown): Address | undefined;
+export function ensureAddress(value: unknown): Address | undefined {
+  if (value == null) return undefined;
+  if (typeof value !== "object") {
+    throw new Error(
+      "address must be an AgentAddress, ExperimentAddress or EvaluatorAddress object.",
+    );
   }
-}
-
-/** (beta) The address of an experiment's tracing project. */
-export class ExperimentAddress implements Address {
-  /** Always lowercase. */
-  readonly id: string;
-
-  /**
-   * @param id The experiment's UUID.
-   * @throws If `id` is not a UUID.
-   */
-  constructor(id: string) {
+  const { kind, id, environment } = value as Record<string, unknown>;
+  if (kind === "EVALUATOR") return { kind };
+  if (kind === "EXPERIMENT") {
     if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
       throw new Error(
         `Experiment id must be a UUID, got ${JSON.stringify(id)}.`,
       );
     }
-    this.id = id.toLowerCase();
-    Object.freeze(this);
+    return { kind, id: id.toLowerCase() };
   }
-
-  toApiAddress(): ApiAddress {
-    return { kind: "EXPERIMENT", id: this.id };
+  if (kind !== "AGENT") {
+    throw new Error(
+      "address must be an AgentAddress, ExperimentAddress or EvaluatorAddress object.",
+    );
   }
-}
-
-/** (beta) The address of the workspace's shared evaluators project. */
-export class EvaluatorAddress implements Address {
-  constructor() {
-    Object.freeze(this);
+  if (typeof id !== "string" || !AGENT_ID_PATTERN.test(id)) {
+    throw new Error(
+      "Address agent id must be 1 to 63 lowercase ASCII letters, digits, or " +
+        "hyphens, start with a letter, and end with a letter or digit, got " +
+        `${JSON.stringify(id)}. Use an id such as "support-agent".`,
+    );
   }
-
-  toApiAddress(): ApiAddress {
-    return { kind: "EVALUATOR" };
+  const normalized =
+    typeof environment === "string" ? environment.toLowerCase() : undefined;
+  if (normalized === undefined || !ENVIRONMENTS.includes(normalized)) {
+    throw new Error(
+      `Address environment must be one of ${ENVIRONMENTS.join(
+        ", ",
+      )}, got ${JSON.stringify(environment)}.`,
+    );
   }
+  return {
+    kind,
+    id,
+    environment: normalized.toUpperCase() as Uppercase<Environment>,
+  };
 }
 
-/**
- * @internal The ingestion entry-point guard: `value` must be an `AgentAddress` (or
- * absent), and is returned as is. Other addresses and strings are rejected.
- * @throws If `value` is not an `AgentAddress`.
- */
+/** @internal Only agent addresses can receive traces. */
+export function ensureAgent(value: {
+  kind: "AGENT";
+  id?: unknown;
+  environment?: unknown;
+}): AgentAddress;
+export function ensureAgent(value: unknown): AgentAddress | undefined;
 export function ensureAgent(value: unknown): AgentAddress | undefined {
-  if (value == null) {
-    return undefined;
-  }
-  if (value instanceof AgentAddress) {
-    return value;
-  }
-  if (
-    typeof value === "object" &&
-    typeof (value as Address).toApiAddress === "function"
-  ) {
+  const address = ensureAddress(value);
+  if (address && address.kind !== "AGENT") {
     throw new Error(
-      `Only an AgentAddress can receive traces, got ${
-        (value as object).constructor?.name ?? "an unknown address"
-      }.`,
+      `Only an AgentAddress can receive traces, got ${address.kind}.`,
     );
   }
-  throw new Error(
-    "address must be an AgentAddress such as `new AgentAddress(id, environment)`, got " +
-      `${typeof value === "string" ? JSON.stringify(value) : typeof value}.`,
-  );
+  return address;
 }
 
-/**
- * Return `value` if it is an `Address` of any kind, as a lookup takes it.
- * For the calls that only resolve an address to its project, such as
- * `getRunUrl`. Whatever receives traces takes `ensureAgent`.
- */
-export function ensureAddress(value: unknown): Address | undefined {
-  if (value == null) {
-    return undefined;
-  }
-  if (
-    typeof value === "object" &&
-    typeof (value as Address).toApiAddress === "function"
-  ) {
-    return value as Address;
+/** @internal Convert a validated address to the ingestion wire format. */
+export function addressToLrn(address: AgentAddress): Lrn {
+  return `lrn:agents/${address.id}/environments/${
+    address.environment.toLowerCase() as Environment
+  }`;
+}
+
+/** @internal Parse and validate an address from untrusted wire data. */
+export function addressFromLrn(value: unknown): AgentAddress {
+  const match = typeof value === "string" ? LRN_PATTERN.exec(value) : null;
+  if (!match) throw new Error("Not an agent address.");
+  return ensureAgent({ kind: "AGENT", id: match[1], environment: match[2] });
+}
+
+/** @internal Read and validate the address named by environment variables. */
+export function addressFromEnv(): AgentAddress | undefined {
+  const values = ENV_NAMES.map((name) => getEnvironmentVariable(name));
+  if (!values.some(Boolean)) return undefined;
+  try {
+    const missing = ENV_NAMES.filter((_, i) => !values[i]);
+    if (missing.length)
+      throw new Error(`An address needs ${missing.join(" and ")} as well.`);
+    return ensureAgent({
+      kind: "AGENT",
+      id: values[0],
+      environment: values[1],
+    });
+  } catch (e) {
+    throw new EnvAddressError(
+      `The LANGSMITH_AGENT_* env vars can't address a run: ${
+        (e as Error).message
+      }`,
+    );
   }
-  throw new Error(
-    "address must be an AgentAddress, ExperimentAddress or EvaluatorAddress, got " +
-      `${typeof value === "string" ? JSON.stringify(value) : typeof value}.`,
-  );
 }
 
-/** @internal The `LANGSMITH_AGENT_*` env var names an address reads. */
+/** @internal The environment variable names an address reads. */
 export function envNames(): string[] {
   return ENV_NAMES;
 }