LangChain.js

When using tools with Gemini models through Vertex AI, certain Zod schema features are unsupported and will cause errors. Follow these patterns to ensure compatibility:

Unsupported: Discriminated Unions

.discriminatedUnion() is not supported. Solution: Use a flat object with an enum and optional fields.

// ❌ Unsupported
z.discriminatedUnion("type", [
  z.object({ type: z.literal("a"), value: z.string() }),
  z.object({ type: z.literal("b"), value: z.number() }),
]);

// ✅ Supported
z.object({
  type: z.enum(["a", "b"]),
  stringValue: z.string().optional(),
  numberValue: z.number().optional(),
});

Unsupported: Union Types

z.union() is not supported. Solution: Use separate optional fields within a single object.

// ❌ Unsupported
z.union([z.string(), z.number()]);

// ✅ Supported
z.object({
  stringValue: z.string().optional(),
  numberValue: z.number().optional(),
});

Unsupported: Positive Refinement

.positive() is automatically converted to .min(0.01). Solution: Use .min() directly to avoid ambiguity.

// ⚠️ Automatically converted
z.number().positive();

// ✅ Preferred
z.number().min(0.01);

MCP tools return arrays of content blocks (text, image, audio, or embedded resources). @langchain/mcp-adapters maps these into LangChain ToolMessage objects using two primary configuration settings:

1. useStandardContentBlocks: Determines the internal structure of the content blocks.

   • When true (recommended), outputs are converted to standardized types like StandardTextBlock, StandardImageBlock, StandardAudioBlock, and StandardFileBlock (compatible with @langchain/core 0.3.48+).
   • When false, outputs use older formats like MessageContentText or MessageContentImageUrl.

2. outputHandling: Determines visibility to the LLM.

   • ToolMessage.content: Data sent here is included in the LLM's input context.
   • ToolMessage.artifact: Data sent here is not included in the LLM context. This is useful for large outputs (like dataframes) or multimodal data that the specific LLM provider cannot handle directly.

Default Behavior: MCP resource blocks are routed to artifact, while all other types are routed to content.

You can control Live Search behavior globally by passing searchParameters to the ChatXAI constructor, or per-request by passing them to the .invoke() method.

Note on Naming: When using tools.xaiLiveSearch(), use camelCase field names (e.g., maxSearchResults, fromDate, allowedWebsites). These are automatically mapped to the underlying API's snake_case requirements.

// Global configuration via constructor
const model = new ChatXAI({
  model: "grok-3-fast",
  searchParameters: {
    mode: "auto", // "auto" | "on" | "off"
    max_search_results: 5,
    from_date: "2024-01-01", // ISO date string
    return_citations: true,
  },
});

// Per-request override
const result = await model.invoke("Find recent news about SpaceX", {
  searchParameters: {
    mode: "on",
    max_search_results: 10,
    sources: [
      {
        type: "web",
        allowed_websites: ["spacex.com", "nasa.gov"],
      },
    ],
  },
});

Use beforeToolCall and afterToolCall hooks in MultiServerMCPClient to intercept and modify tool arguments, headers, or results.

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
  mcpServers: {
    math: {
      transport: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-math"],
    },
  },

  // Modify args or headers before the tool is called
  beforeToolCall: ({ serverName, name, args }) => {
    const nextArgs = { ...(args as Record<string, unknown>), injected: true };
    return {
      args: nextArgs,
      headers: { "X-Request-ID": crypto.randomUUID() },
    };
  },

  // Modify the result after the tool has executed
  afterToolCall: (res) => {
    // Return a 2-tuple [content, artifact]
    if (res.name === "someTool") return { result: ["modified-output", []] };
    
    // Or return the original result
    return { result: res.result };
  },
});

const tools = await client.getTools();
const t = tools.find((tool) => tool.name.includes("add"));
const out = await t?.invoke({ a: 1, b: 2 });