feat: Support Custom Metadata Labels on Vertex AI

libs/langchain-google-common/src/chat_models.ts

@@ -221,6 +221,8 @@ export abstract class ChatGoogleBase<AuthOptions>
 
   streaming = false;
 
+  labels?: Record<string, string>;
+
   protected connection: ChatConnection<AuthOptions>;
 
   protected streamedConnection: ChatConnection<AuthOptions>;

libs/langchain-google-common/src/connection.ts

@@ -475,7 +475,14 @@ export abstract class AbstractGoogleLLMConnection<
     input: MessageType,
     parameters: GoogleAIModelRequestParams
   ): Promise<unknown> {
-    return this.api.formatData(input, parameters);
+    // Filter out labels for non-Vertex AI platforms (labels are only supported on Vertex AI)
+    let filteredParameters = parameters;
+    if (parameters.labels && this.platform !== "gcp") {
+      const { labels, ...paramsWithoutLabels } = parameters;
+      filteredParameters = paramsWithoutLabels;
+    }
+
+    return this.api.formatData(input, filteredParameters);
   }
 }
 

libs/langchain-google-common/src/tests/chat_models.test.ts

@@ -328,6 +328,181 @@ describe("Mock ChatGoogle - Gemini", () => {
     );
   });
 
+  test("labels - included on Vertex AI (gcp)", async () => {
+    const record: Record<string, any> = {};
+    const projectId = mockId();
+    const authOptions: MockClientAuthInfo = {
+      record,
+      projectId,
+      resultFile: "chat-1-mock.json",
+    };
+    const model = new ChatGoogle({
+      authOptions,
+      platformType: "gcp",
+      labels: {
+        team: "research",
+        component: "frontend",
+        environment: "production",
+      },
+    });
+    const messages: BaseMessageLike[] = [
+      new HumanMessage("Hello"),
+    ];
+    await model.invoke(messages);
+
+    expect(record.opts).toBeDefined();
+    expect(record.opts.data).toBeDefined();
+    const { data } = record.opts;
+    expect(data.labels).toBeDefined();
+    expect(data.labels).toEqual({
+      team: "research",
+      component: "frontend",
+      environment: "production",
+    });
+  });
+
+  test("labels - excluded on Google AI Studio (gai)", async () => {
+    const record: Record<string, any> = {};
+    const projectId = mockId();
+    const authOptions: MockClientAuthInfo = {
+      record,
+      projectId,
+      resultFile: "chat-1-mock.json",
+    };
+    const model = new ChatGoogle({
+      authOptions,
+      platformType: "gai",
+      labels: {
+        team: "research",
+        component: "frontend",
+      },
+    });
+    const messages: BaseMessageLike[] = [
+      new HumanMessage("Hello"),
+    ];
+    await model.invoke(messages);
+
+    expect(record.opts).toBeDefined();
+    expect(record.opts.data).toBeDefined();
+    const { data } = record.opts;
+    expect(data.labels).not.toBeDefined();
+  });
+
+  test("labels - passed via invoke options on Vertex AI", async () => {
+    const record: Record<string, any> = {};
+    const projectId = mockId();
+    const authOptions: MockClientAuthInfo = {
+      record,
+      projectId,
+      resultFile: "chat-1-mock.json",
+    };
+    const model = new ChatGoogle({
+      authOptions,
+      platformType: "gcp",
+    });
+    const messages: BaseMessageLike[] = [
+      new HumanMessage("Hello"),
+    ];
+    await model.invoke(messages, {
+      labels: {
+        session: "test-session",
+        user: "test-user",
+      },
+    });
+
+    expect(record.opts).toBeDefined();
+    expect(record.opts.data).toBeDefined();
+    const { data } = record.opts;
+    expect(data.labels).toBeDefined();
+    expect(data.labels).toEqual({
+      session: "test-session",
+      user: "test-user",
+    });
+  });
+
+  test("labels - invoke options override model labels on Vertex AI", async () => {
+    const record: Record<string, any> = {};
+    const projectId = mockId();
+    const authOptions: MockClientAuthInfo = {
+      record,
+      projectId,
+      resultFile: "chat-1-mock.json",
+    };
+    const model = new ChatGoogle({
+      authOptions,
+      platformType: "gcp",
+      labels: {
+        team: "research",
+        environment: "dev",
+      },
+    });
+    const messages: BaseMessageLike[] = [
+      new HumanMessage("Hello"),
+    ];
+    await model.invoke(messages, {
+      labels: {
+        environment: "production",
+        session: "override-session",
+      },
+    });
+
+    expect(record.opts).toBeDefined();
+    expect(record.opts.data).toBeDefined();
+    const { data } = record.opts;
+    expect(data.labels).toBeDefined();
+    expect(data.labels).toEqual({
+      environment: "production",
+      session: "override-session",
+    });
+  });
+
+  test("labels - no labels sent when not provided", async () => {
+    const record: Record<string, any> = {};
+    const projectId = mockId();
+    const authOptions: MockClientAuthInfo = {
+      record,
+      projectId,
+      resultFile: "chat-1-mock.json",
+    };
+    const model = new ChatGoogle({
+      authOptions,
+      platformType: "gcp",
+    });
+    const messages: BaseMessageLike[] = [
+      new HumanMessage("Hello"),
+    ];
+    await model.invoke(messages);
+
+    expect(record.opts).toBeDefined();
+    expect(record.opts.data).toBeDefined();
+    const { data } = record.opts;
+    expect(data.labels).not.toBeDefined();
+  });
+
+  test("labels - empty labels object not sent", async () => {
+    const record: Record<string, any> = {};
+    const projectId = mockId();
+    const authOptions: MockClientAuthInfo = {
+      record,
+      projectId,
+      resultFile: "chat-1-mock.json",
+    };
+    const model = new ChatGoogle({
+      authOptions,
+      platformType: "gcp",
+      labels: {},
+    });
+    const messages: BaseMessageLike[] = [
+      new HumanMessage("Hello"),
+    ];
+    await model.invoke(messages);
+
+    expect(record.opts).toBeDefined();
+    expect(record.opts.data).toBeDefined();
+    const { data } = record.opts;
+    expect(data.labels).not.toBeDefined();
+  });
+
   test("1. Basic request format", async () => {
     const record: Record<string, any> = {};
     const projectId = mockId();
@@ -1880,8 +2055,8 @@ describe("Mock ChatGoogle - Gemini", () => {
     expect(first.bytes).toEqual([72, 101, 114, 101]);
     expect(first).toHaveProperty("top_logprobs");
     expect(Array.isArray(first.top_logprobs)).toBeTruthy();
-    expect(first.top_logprobs).toHaveLength(5);
-  });
+          expect(first.top_logprobs).toHaveLength(5);
+    });
 });
 
 describe("Mock ChatGoogle - Anthropic", () => {

libs/langchain-google-common/src/types.ts

@@ -269,6 +269,24 @@ export interface GoogleAIModelParams {
    * The modalities of the response.
    */
   responseModalities?: GoogleAIModelModality[];
+
+  /**
+   * Custom metadata labels to associate with the request.
+   * Only supported on Vertex AI (Google Cloud Platform).
+   * Labels are key-value pairs where both keys and values must be strings.
+   *
+   * Example:
+   * ```typescript
+   * {
+   *   labels: {
+   *     "team": "research",
+   *     "component": "frontend",
+   *     "environment": "production"
+   *   }
+   * }
+   * ```
+   */
+  labels?: Record<string, string>;
 }
 
 export type GoogleAIToolType = BindToolsInput | GeminiTool;
@@ -585,6 +603,11 @@ export interface GeminiRequest {
   safetySettings?: GeminiSafetySetting[];
   generationConfig?: GeminiGenerationConfig;
   cachedContent?: string;
+
+  /**
+   * Custom metadata labels to associate with the API call.
+   */
+  labels?: Record<string, string>;
 }
 
 export interface GeminiResponseCandidate {

libs/langchain-google-common/src/utils/common.ts

@@ -214,6 +214,8 @@ export function copyAIModelParamsInto(
     ret.cachedContent = options.cachedContent;
   }
 
+  ret.labels = options?.labels ?? params?.labels ?? target?.labels;
+
   return ret;
 }
 

libs/langchain-google-common/src/utils/gemini.ts

@@ -1614,6 +1614,9 @@ export function getGeminiAPI(config?: GeminiAPIConfig): GoogleAIAPI {
     if (parameters.cachedContent) {
       ret.cachedContent = parameters.cachedContent;
     }
+    if (parameters.labels && Object.keys(parameters.labels).length > 0) {
+      ret.labels = parameters.labels;
+    }
     return ret;
   }
 

libs/langchain-google-vertexai/src/tests/chat_models.test.ts

@@ -8,3 +8,16 @@ test("Serialization", () => {
     `{"lc":1,"type":"constructor","id":["langchain","chat_models","vertexai","ChatVertexAI"],"kwargs":{"platform_type":"gcp"}}`
   );
 });
+
+test("Labels parameter support", () => {
+  // Verify that the model accepts labels parameter without throwing an error
+  expect(() => {
+    const model = new ChatVertexAI({
+      labels: {
+        team: "test",
+        environment: "development",
+      },
+    });
+    expect(model.platform).toEqual("gcp");
+  }).not.toThrow();
+});