From 34f0b4eb6dc9efa58e90f2243066a303991d4bde Mon Sep 17 00:00:00 2001
From: Christian Bromann <git@bromann.dev>
Date: Sat, 22 Nov 2025 14:17:56 -0800
Subject: [PATCH] chore: extend changelog docs on changing dynamic system
 prompt middleware

---
 src/oss/javascript/releases/changelog.mdx |  3 ++-
 src/oss/langchain/middleware/custom.mdx   | 19 ++++++++++++++++++-
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/oss/javascript/releases/changelog.mdx b/src/oss/javascript/releases/changelog.mdx
index 097a63005e..c78abb81b7 100644
--- a/src/oss/javascript/releases/changelog.mdx
+++ b/src/oss/javascript/releases/changelog.mdx
@@ -11,9 +11,10 @@ A chronological log of updates and improvements to LangChain JavaScript.
 * [Summarization middleware](/oss/langchain/middleware/built-in#summarization): Updated to support flexible trigger points using model profiles for context-aware summarization.
 * [Structured output](/oss/langchain/structured-output): `ProviderStrategy` support (native structured output) can now be inferred from model profiles.
 * [`SystemMessage` for `createAgent`](/oss/langchain/middleware/custom#working-with-system-messages): Support for passing `SystemMessage` instances directly to `createAgent`'s `systemPrompt` parameter and a new `concat` method for extending system messages. Enables advanced features like cache control and structured content blocks.
+* [Dynamic system prompt middleware](/oss/langchain/agents#dynamic-system-prompt): Return values from `dynamicSystemPromptMiddleware` are now purely additive. When returning a @[`SystemMessage`] or `string`, they are merged with existing system messages rather than replacing them, making it easier to compose multiple middleware that modify the prompt.
 * [Model retry middleware](/oss/langchain/middleware/built-in#model-retry): New middleware for automatically retrying failed model calls with configurable exponential backoff, improving agent reliability.
 * [Content moderation middleware](/oss/langchain/middleware/built-in#content-moderation): OpenAI content moderation middleware for detecting and handling unsafe content in agent interactions. Supports checking user input, model output, and tool results.
-* * __Compatibility improvements:__ Fixed error handling for Zod v4 validation errors in structured output and tool schemas, ensuring detailed error messages are properly displayed.
+* __Compatibility improvements:__ Fixed error handling for Zod v4 validation errors in structured output and tool schemas, ensuring detailed error messages are properly displayed.
 
 ### Resources
 
diff --git a/src/oss/langchain/middleware/custom.mdx b/src/oss/langchain/middleware/custom.mdx
index 0591c90883..c7bf3dfcd8 100644
--- a/src/oss/langchain/middleware/custom.mdx
+++ b/src/oss/langchain/middleware/custom.mdx
@@ -1049,6 +1049,8 @@ class CachedContextMiddleware(AgentMiddleware):
 :::
 
 :::js
+Modify system messages in middleware using the `systemMessage` field in `ModelRequest`. It contains a @[`SystemMessage`] object (even if the agent was created with a string @[`systemPrompt`]).
+
 **Example: Chaining middleware** - Different middleware can use different approaches:
 
 ```typescript
@@ -1060,7 +1062,7 @@ const myMiddleware = createMiddleware({
   wrapModelCall: async (request, handler) => {
     return handler({
       ...request,
-      systemMessage: request.systemMessage.concat(`\nAdditional context.`),
+      systemMessage: request.systemMessage.concat(`Additional context.`),
     });
   },
 });
@@ -1093,6 +1095,21 @@ const agent = createAgent({
 });
 ```
 
+The resulting system message will be:
+```typescript
+new SystemMessage({
+  content: [
+    { type: "text", text: "You are a helpful assistant." },
+    { type: "text", text: "Additional context." },
+    {
+        type: "text",
+        text: " More additional context. This will be cached.",
+        cache_control: { type: "ephemeral", ttl: "5m" },
+    },
+  ],
+});
+```
+
 Use @[`SystemMessage.concat`] to preserve cache control metadata or structured content blocks created by other middleware.
 
 :::