From 2d0d7a85bc67e7fb5a5f9c5641c77b3ed29bb82a Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Thu, 20 Nov 2025 16:59:33 -0800 Subject: [PATCH 1/3] v1.1 JS release notes --- .../javascript/releases/langchain-v1-1.mdx | 189 +++++++++++++++++- 1 file changed, 181 insertions(+), 8 deletions(-) diff --git a/src/oss/javascript/releases/langchain-v1-1.mdx b/src/oss/javascript/releases/langchain-v1-1.mdx index 59e4c3c666..2fa12753d4 100644 --- a/src/oss/javascript/releases/langchain-v1-1.mdx +++ b/src/oss/javascript/releases/langchain-v1-1.mdx @@ -3,7 +3,7 @@ title: What's new in v1.1 sidebarTitle: v1.1 Release notes --- -**LangChain v1.1 focuses on improving agent reliability and flexibility.** This release introduces model profiles, new middleware capabilities, and enhanced type safety for custom middleware implementations. +**LangChain v1.1 focuses on improving agent reliability and flexibility.** This release introduces new middleware capabilities for retrying model calls and content moderation, improved system message handling, and enhanced compatibility with Zod v4. To upgrade, @@ -22,21 +22,194 @@ bun add @langchain/core @langchain/langgraph ``` -## Model profiles +## System message improvements -Model profiles allow you to configure how agents interact with specific models by defining capabilities, context handling, and structured output behavior. +### Concatenate system messages -### Summarization middleware +You can now easily extend system messages with additional content using the new `concat` method. This simplifies extending system prompts without manually handling string or array content types. -### Structured output for agents +```typescript +import { SystemMessage } from "langchain"; + +const systemPrompt = new SystemMessage("You are a helpful assistant."); + +// Easily append additional content +const extendedPrompt = systemPrompt.concat(" Always be concise and accurate."); +``` + +Previously, extending system messages required complex conditional logic to handle both string and array content types. The `concat` method handles this automatically, making it much easier to build dynamic system prompts. + +### SystemMessage as systemPrompt + +You can now pass a `SystemMessage` instance directly to the `systemPrompt` parameter when creating agents, providing more flexibility in prompt design. This enables advanced features like cache control (e.g., Anthropic's ephemeral cache) and structured content blocks. + +```typescript +import { createAgent, SystemMessage } from "langchain"; + +// Simple string (still supported) +const agent1 = createAgent({ + model: "gpt-4o", + tools: [myTool], + systemPrompt: "You are a helpful assistant.", +}); + +// SystemMessage instance with cache control +const agent2 = createAgent({ + model: "anthropic:claude-3-5-sonnet", + tools: [myTool], + systemPrompt: new SystemMessage({ + content: [ + { + type: "text", + text: "You are a helpful assistant.", + }, + { + type: "text", + text: "Today's date is 2024-06-01.", + cache_control: { type: "ephemeral", ttl: "5m" }, + }, + ], + }), +}); +``` + +#### Middleware Support + +When using middleware with `wrapModelCall`, the request object provides both `systemPrompt` (as a string) and `systemMessage` (as a `SystemMessage` object) for maximum flexibility. This dual interface allows middleware to choose the most appropriate approach for their use case. + +**Key Behavior:** +- Middleware receives both `systemPrompt` (string) and `systemMessage` (SystemMessage) in the request +- You can modify either `systemPrompt` or `systemMessage`, but **cannot set both in the same middleware call** - this prevents conflicts +- Using `systemPrompt` creates a new simple system message (overwrites cache control metadata) +- Using `systemMessage.concat()` preserves existing cache control and structured content blocks +- Multiple middleware can chain modifications sequentially across different middleware calls + +**Example: Using `systemPrompt` (string)** - Simple string concatenation, loses cache control: +```typescript +import { createMiddleware } from "langchain"; + +const middleware = createMiddleware({ + name: "MyMiddleware", + wrapModelCall: async (request, handler) => { + return handler({ + ...request, + systemPrompt: `${request.systemPrompt}. \nAdditional context.`, + }); + }, +}); +``` + +**Example: Using `systemMessage` (SystemMessage)** - Preserves cache control and structured content: +```typescript +import { createMiddleware, SystemMessage } from "langchain"; + +const middleware = createMiddleware({ + name: "MyMiddleware", + wrapModelCall: async (request, handler) => { + return handler({ + ...request, + systemMessage: request.systemMessage.concat( + new SystemMessage({ + content: [ + { + type: "text", + text: " Additional context.", + cache_control: { type: "ephemeral", ttl: "10m" }, + }, + ], + }) + ), + }); + }, +}); +``` + +**Example: Chaining middleware** - Different middleware can use different approaches: +```typescript +// Middleware 1: Uses systemPrompt (string) +const myMiddleware = createMiddleware({ + name: "MyMiddleware", + wrapModelCall: async (request, handler) => { + return handler({ + ...request, + systemPrompt: `${request.systemPrompt} Additional context.`, + }); + }, +}); + +// Middleware 2: Uses systemMessage (preserves structure) +const myOtherMiddleware = createMiddleware({ + name: "MyOtherMiddleware", + wrapModelCall: async (request, handler) => { + return handler({ + ...request, + systemMessage: request.systemMessage.concat( + new SystemMessage({ + content: [ + { + type: "text", + text: " More additional context. This will be cached.", + cache_control: { type: "ephemeral", ttl: "5m" }, + }, + ], + }) + ), + }); + }, +}); + +const agent = createAgent({ + model: "anthropic:claude-4-5-sonnet", + systemPrompt: "You are a helpful assistant.", + middleware: [myMiddleware, myOtherMiddleware], +}); +``` + +**When to use each approach:** +- Use `systemPrompt` when you need simple string manipulation and don't need cache control +- Use `systemMessage.concat()` when you need to preserve cache control metadata or work with structured content blocks ## Model retry middleware -## Misc +A new `modelRetryMiddleware` automatically retries failed model calls with configurable exponential backoff. This middleware improves agent reliability by handling transient model failures gracefully. + +```typescript +import { createAgent, modelRetryMiddleware } from "langchain"; + +const agent = createAgent({ + model: "gpt-4o", + tools: [searchTool, databaseTool], + middleware: [ + modelRetryMiddleware({ + maxRetries: 3, + backoffFactor: 2.0, + initialDelayMs: 1000, + }), + ], +}); +``` + +The middleware supports: +- Configurable retry attempts with exponential backoff +- Custom exception filtering to determine which errors should trigger retries +- Flexible failure handling strategies + +## OpenAI content moderation middleware + +A new middleware integrates OpenAI's moderation endpoint to detect and handle unsafe content in agent interactions. This middleware is useful for applications requiring content safety and compliance. + +The middleware can check content at multiple stages: +- **Input checking**: User messages before model calls +- **Output checking**: AI messages after model calls +- **Tool results**: Tool outputs before model calls + +You can configure how violations are handled with options like ending execution, raising errors, or replacing flagged content. See the [middleware documentation](/oss/langchain/middleware/built-in#content-moderation) for detailed usage examples. + +## Compatibility improvements -### New middleware docs +### Zod v4 support -### Type safety improvements for custom middlewares +LangChain.js now supports Zod v4, ensuring seamless integration with the latest version of the schema validation library. This update maintains backward compatibility while enabling you to use the latest Zod features for structured output and tool schemas. ## Reporting issues From 6165d23b8ee391e6d40562c37258f5d22279a5af Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Thu, 20 Nov 2025 17:04:39 -0800 Subject: [PATCH 2/3] add model profiles --- .../javascript/releases/langchain-v1-1.mdx | 45 ++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/src/oss/javascript/releases/langchain-v1-1.mdx b/src/oss/javascript/releases/langchain-v1-1.mdx index 2fa12753d4..c6d0c14963 100644 --- a/src/oss/javascript/releases/langchain-v1-1.mdx +++ b/src/oss/javascript/releases/langchain-v1-1.mdx @@ -3,7 +3,7 @@ title: What's new in v1.1 sidebarTitle: v1.1 Release notes --- -**LangChain v1.1 focuses on improving agent reliability and flexibility.** This release introduces new middleware capabilities for retrying model calls and content moderation, improved system message handling, and enhanced compatibility with Zod v4. +**LangChain v1.1 focuses on improving agent reliability and flexibility.** This release introduces model profiles for better model capability awareness, new middleware capabilities for retrying model calls and content moderation, improved system message handling, and enhanced compatibility with Zod v4. To upgrade, @@ -22,6 +22,49 @@ bun add @langchain/core @langchain/langgraph ``` +## Model profiles + +Model profiles provide a standardized way to understand model capabilities and constraints, enabling LangChain components to make better decisions based on model-specific characteristics. + +### What are model profiles? + +Model profiles describe key model properties such as: +- **Context window size** - Maximum tokens a model can process +- **Structured output support** - Whether the model supports native structured output mechanisms +- **Capabilities** - Model-specific features and limitations + +These profiles are automatically generated from [models.dev](https://models.dev) and maintained in provider packages, ensuring they stay up-to-date as models evolve. + +### Accessing model profiles + +Every chat model now exposes a `.profile` getter that returns its `ModelProfile`: + +```typescript +import { initChatModel } from "langchain"; + +const model = await initChatModel("gpt-4o"); + +// Access the model's profile +const profile = model.profile; + +console.log(profile.maxTokens); // Maximum context window size +console.log(profile.supportsStructuredOutput); // Native structured output support +``` + +### Benefits + +Model profiles enable several improvements across LangChain: + +1. **Accurate context management** - Middleware like summarization can now use accurate token limits instead of hardcoded values, preventing incorrect context window calculations. + +2. **Better structured output** - The `createAgent` abstraction can automatically detect if a model supports native structured output mechanisms, choosing the optimal approach for each model. + +3. **Improved testing** - Test suites can adapt to model-specific capabilities, making it easier to test across different models with varying constraints. + +4. **Future extensibility** - The profile system provides a foundation for model-aware features that can adapt to each model's unique characteristics. + +Profiles are automatically maintained and updated as new models are released or existing models gain new capabilities, ensuring your applications always have accurate information about model constraints. + ## System message improvements ### Concatenate system messages From c5b10a292dfc4b4c34201cc8ff0052d762b31aad Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Fri, 21 Nov 2025 12:39:55 -0800 Subject: [PATCH 3/3] revise --- pipeline/preprocessors/link_map.py | 3 + .../javascript/releases/langchain-v1-1.mdx | 162 +----------------- src/oss/langchain/middleware/custom.mdx | 73 ++++++++ 3 files changed, 83 insertions(+), 155 deletions(-) diff --git a/pipeline/preprocessors/link_map.py b/pipeline/preprocessors/link_map.py index a669356765..3663856c4d 100644 --- a/pipeline/preprocessors/link_map.py +++ b/pipeline/preprocessors/link_map.py @@ -302,6 +302,9 @@ class LinkMap(TypedDict): # @langchain/core references "AIMessage": "classes/_langchain_core.messages.AIMessage.html", "AIMessageChunk": "classes/_langchain_core.messages.AIMessageChunk.html", + "SystemMessage": "classes/_langchain_core.messages.SystemMessage.html", + "SystemMessage.concat": "classes/_langchain_core.messages.SystemMessage.html#concat", + "ModelRequest": "classes/_langchain_core.messages.ModelRequest.html", "BaseChatModel.invoke": "classes/_langchain_core.language_models_chat_models.BaseChatModel.html#invoke", "BaseChatModel.stream": "classes/_langchain_core.language_models_chat_models.BaseChatModel.html#stream", "BaseChatModel.streamEvents": "classes/_langchain_core.language_models_chat_models.BaseChatModel.html#streamEvents", diff --git a/src/oss/javascript/releases/langchain-v1-1.mdx b/src/oss/javascript/releases/langchain-v1-1.mdx index c6d0c14963..604be6f421 100644 --- a/src/oss/javascript/releases/langchain-v1-1.mdx +++ b/src/oss/javascript/releases/langchain-v1-1.mdx @@ -24,80 +24,29 @@ bun add @langchain/core @langchain/langgraph ## Model profiles -Model profiles provide a standardized way to understand model capabilities and constraints, enabling LangChain components to make better decisions based on model-specific characteristics. - -### What are model profiles? - -Model profiles describe key model properties such as: -- **Context window size** - Maximum tokens a model can process -- **Structured output support** - Whether the model supports native structured output mechanisms -- **Capabilities** - Model-specific features and limitations - -These profiles are automatically generated from [models.dev](https://models.dev) and maintained in provider packages, ensuring they stay up-to-date as models evolve. - -### Accessing model profiles - -Every chat model now exposes a `.profile` getter that returns its `ModelProfile`: +Model profiles provide a standardized way to understand model capabilities and constraints. Every chat model now exposes a `.profile` getter that returns information about context window size, structured output support, and other model-specific characteristics. ```typescript import { initChatModel } from "langchain"; const model = await initChatModel("gpt-4o"); - -// Access the model's profile const profile = model.profile; console.log(profile.maxTokens); // Maximum context window size console.log(profile.supportsStructuredOutput); // Native structured output support ``` -### Benefits - -Model profiles enable several improvements across LangChain: - -1. **Accurate context management** - Middleware like summarization can now use accurate token limits instead of hardcoded values, preventing incorrect context window calculations. - -2. **Better structured output** - The `createAgent` abstraction can automatically detect if a model supports native structured output mechanisms, choosing the optimal approach for each model. - -3. **Improved testing** - Test suites can adapt to model-specific capabilities, making it easier to test across different models with varying constraints. - -4. **Future extensibility** - The profile system provides a foundation for model-aware features that can adapt to each model's unique characteristics. - -Profiles are automatically maintained and updated as new models are released or existing models gain new capabilities, ensuring your applications always have accurate information about model constraints. +Profiles are automatically generated from [models.dev](https://models.dev) and enable middleware like summarization to use accurate token limits, while `createAgent` can automatically detect native structured output support. ## System message improvements -### Concatenate system messages - -You can now easily extend system messages with additional content using the new `concat` method. This simplifies extending system prompts without manually handling string or array content types. - -```typescript -import { SystemMessage } from "langchain"; - -const systemPrompt = new SystemMessage("You are a helpful assistant."); - -// Easily append additional content -const extendedPrompt = systemPrompt.concat(" Always be concise and accurate."); -``` - -Previously, extending system messages required complex conditional logic to handle both string and array content types. The `concat` method handles this automatically, making it much easier to build dynamic system prompts. - -### SystemMessage as systemPrompt - -You can now pass a `SystemMessage` instance directly to the `systemPrompt` parameter when creating agents, providing more flexibility in prompt design. This enables advanced features like cache control (e.g., Anthropic's ephemeral cache) and structured content blocks. +You can now pass a `SystemMessage` instance directly to the `systemPrompt` parameter when creating agents, and use the new `concat` method to extend system messages. This enables advanced features like cache control (e.g., Anthropic's ephemeral cache) and structured content blocks. ```typescript import { createAgent, SystemMessage } from "langchain"; -// Simple string (still supported) -const agent1 = createAgent({ - model: "gpt-4o", - tools: [myTool], - systemPrompt: "You are a helpful assistant.", -}); - // SystemMessage instance with cache control -const agent2 = createAgent({ +const agent = createAgent({ model: "anthropic:claude-3-5-sonnet", tools: [myTool], systemPrompt: new SystemMessage({ @@ -116,105 +65,11 @@ const agent2 = createAgent({ }); ``` -#### Middleware Support - -When using middleware with `wrapModelCall`, the request object provides both `systemPrompt` (as a string) and `systemMessage` (as a `SystemMessage` object) for maximum flexibility. This dual interface allows middleware to choose the most appropriate approach for their use case. - -**Key Behavior:** -- Middleware receives both `systemPrompt` (string) and `systemMessage` (SystemMessage) in the request -- You can modify either `systemPrompt` or `systemMessage`, but **cannot set both in the same middleware call** - this prevents conflicts -- Using `systemPrompt` creates a new simple system message (overwrites cache control metadata) -- Using `systemMessage.concat()` preserves existing cache control and structured content blocks -- Multiple middleware can chain modifications sequentially across different middleware calls - -**Example: Using `systemPrompt` (string)** - Simple string concatenation, loses cache control: -```typescript -import { createMiddleware } from "langchain"; - -const middleware = createMiddleware({ - name: "MyMiddleware", - wrapModelCall: async (request, handler) => { - return handler({ - ...request, - systemPrompt: `${request.systemPrompt}. \nAdditional context.`, - }); - }, -}); -``` - -**Example: Using `systemMessage` (SystemMessage)** - Preserves cache control and structured content: -```typescript -import { createMiddleware, SystemMessage } from "langchain"; - -const middleware = createMiddleware({ - name: "MyMiddleware", - wrapModelCall: async (request, handler) => { - return handler({ - ...request, - systemMessage: request.systemMessage.concat( - new SystemMessage({ - content: [ - { - type: "text", - text: " Additional context.", - cache_control: { type: "ephemeral", ttl: "10m" }, - }, - ], - }) - ), - }); - }, -}); -``` - -**Example: Chaining middleware** - Different middleware can use different approaches: -```typescript -// Middleware 1: Uses systemPrompt (string) -const myMiddleware = createMiddleware({ - name: "MyMiddleware", - wrapModelCall: async (request, handler) => { - return handler({ - ...request, - systemPrompt: `${request.systemPrompt} Additional context.`, - }); - }, -}); - -// Middleware 2: Uses systemMessage (preserves structure) -const myOtherMiddleware = createMiddleware({ - name: "MyOtherMiddleware", - wrapModelCall: async (request, handler) => { - return handler({ - ...request, - systemMessage: request.systemMessage.concat( - new SystemMessage({ - content: [ - { - type: "text", - text: " More additional context. This will be cached.", - cache_control: { type: "ephemeral", ttl: "5m" }, - }, - ], - }) - ), - }); - }, -}); - -const agent = createAgent({ - model: "anthropic:claude-4-5-sonnet", - systemPrompt: "You are a helpful assistant.", - middleware: [myMiddleware, myOtherMiddleware], -}); -``` - -**When to use each approach:** -- Use `systemPrompt` when you need simple string manipulation and don't need cache control -- Use `systemMessage.concat()` when you need to preserve cache control metadata or work with structured content blocks +When using middleware with `wrapModelCall`, you can modify system prompts using either `systemPrompt` (string) or `systemMessage` (SystemMessage object). See the [custom middleware documentation](/oss/langchain/middleware/custom#working-with-system-messages) for detailed examples and best practices. ## Model retry middleware -A new `modelRetryMiddleware` automatically retries failed model calls with configurable exponential backoff. This middleware improves agent reliability by handling transient model failures gracefully. +A new `modelRetryMiddleware` automatically retries failed model calls with configurable exponential backoff, improving agent reliability by handling transient model failures gracefully. ```typescript import { createAgent, modelRetryMiddleware } from "langchain"; @@ -232,10 +87,7 @@ const agent = createAgent({ }); ``` -The middleware supports: -- Configurable retry attempts with exponential backoff -- Custom exception filtering to determine which errors should trigger retries -- Flexible failure handling strategies +See the [built-in middleware documentation](/oss/langchain/middleware/built-in) for configuration options and detailed examples. ## OpenAI content moderation middleware diff --git a/src/oss/langchain/middleware/custom.mdx b/src/oss/langchain/middleware/custom.mdx index 318cc5d784..1c907ea253 100644 --- a/src/oss/langchain/middleware/custom.mdx +++ b/src/oss/langchain/middleware/custom.mdx @@ -908,6 +908,79 @@ const agent = createAgent({ ::: +### Working with system messages + +You can modify system prompts in middleware using either `systemPrompt` (`string`) or `systemMessage` (@[`SystemMessage`]). The @[`ModelRequest`] provides both for maximum flexibility. + +**Key behavior:** +- Middleware receives both `systemPrompt` (string) and `systemMessage` (@[`SystemMessage`]) in the request +- You can modify either `systemPrompt` or `systemMessage`, but **cannot set both in the same middleware call** - this prevents conflicts +- Using `systemPrompt` creates a new simple system message (may overwrite cache control metadata) +- Using `systemMessage` (JavaScript) or manually combining content blocks (Python) preserves existing cache control and structured content blocks +- Multiple middleware can chain modifications sequentially across different middleware calls + +:::python + +```python +@wrap_model_call +def add_context_preserve_cache( + request: ModelRequest, + handler: Callable[[ModelRequest], ModelResponse], +) -> ModelResponse: + new_system_message = SystemMessage(content="Additional context.") + return handler(request.override(system_message=new_system_message)) +``` +::: + +:::js +**Example: Chaining middleware** - Different middleware can use different approaches: + +```typescript +import { createMiddleware, SystemMessage, createAgent } from "langchain"; + +// Middleware 1: Uses systemPrompt (string) +const myMiddleware = createMiddleware({ + name: "MyMiddleware", + wrapModelCall: async (request, handler) => { + return handler({ + ...request, + systemPrompt: request.systemMessage.concat(`\nAdditional context.`), + }); + }, +}); + +// Middleware 2: Uses systemMessage (preserves structure) +const myOtherMiddleware = createMiddleware({ + name: "MyOtherMiddleware", + wrapModelCall: async (request, handler) => { + return handler({ + ...request, + systemMessage: request.systemMessage.concat( + new SystemMessage({ + content: [ + { + type: "text", + text: " More additional context. This will be cached.", + cache_control: { type: "ephemeral", ttl: "5m" }, + }, + ], + }) + ), + }); + }, +}); + +const agent = createAgent({ + model: "anthropic:claude-3-5-sonnet", + systemPrompt: "You are a helpful assistant.", + middleware: [myMiddleware, myOtherMiddleware], +}); +``` + +Use @[`SystemMessage.concat`] to preserve cache control metadata or structured content blocks created by other middleware. + +::: + ## Additional resources - [Middleware API reference](https://reference.langchain.com/python/langchain/middleware/)