Skip to content

The agent engineering platform.

feat(langchain): support `SystemMessage` in `create_agent`'s `system_prompt` (#34055)

Sydney Runkle4ab94579ad36
diff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.py
index 673ac347dc..bc1bf632ca 100644
--- a/libs/langchain_v1/langchain/agents/factory.py
+++ b/libs/langchain_v1/langchain/agents/factory.py
@@ -542,7 +542,7 @@ def create_agent( # noqa: PLR0915
model: str | BaseChatModel,
tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
*,
- system_prompt: str | None = None,
+ system_prompt: str | SystemMessage | None = None,
middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (),
response_format: ResponseFormat[ResponseT] | type[ResponseT] | None = None,
state_schema: type[AgentState[ResponseT]] | None = None,
@@ -588,9 +588,9 @@ def create_agent( # noqa: PLR0915
docs for more information.
system_prompt: An optional system prompt for the LLM.
- Prompts are converted to a
- [`SystemMessage`][langchain.messages.SystemMessage] and added to the
- beginning of the message list.
+ Can be a `str` (which will be converted to a `SystemMessage`) or a
+ `SystemMessage` instance directly. The system message is added to the
+ beginning of the message list when calling the model.
middleware: A sequence of middleware instances to apply to the agent.
Middleware can intercept and modify agent behavior at various stages.
@@ -685,6 +685,14 @@ def create_agent( # noqa: PLR0915
if isinstance(model, str):
model = init_chat_model(model)
+ # Convert system_prompt to SystemMessage if needed
+ system_message: SystemMessage | None = None
+ if system_prompt is not None:
+ if isinstance(system_prompt, SystemMessage):
+ system_message = system_prompt
+ else:
+ system_message = SystemMessage(content=system_prompt)
+
# Handle tools being None or empty
if tools is None:
tools = []
@@ -1088,8 +1096,8 @@ def create_agent( # noqa: PLR0915
# Get the bound model (with auto-detection if needed)
model_, effective_response_format = _get_bound_model(request)
messages = request.messages
- if request.system_prompt:
- messages = [SystemMessage(request.system_prompt), *messages]
+ if request.system_message:
+ messages = [request.system_message, *messages]
output = model_.invoke(messages)
@@ -1108,7 +1116,7 @@ def create_agent( # noqa: PLR0915
request = ModelRequest(
model=model,
tools=default_tools,
- system_prompt=system_prompt,
+ system_message=system_message,
response_format=initial_response_format,
messages=state["messages"],
tool_choice=None,
@@ -1141,8 +1149,8 @@ def create_agent( # noqa: PLR0915
# Get the bound model (with auto-detection if needed)
model_, effective_response_format = _get_bound_model(request)
messages = request.messages
- if request.system_prompt:
- messages = [SystemMessage(request.system_prompt), *messages]
+ if request.system_message:
+ messages = [request.system_message, *messages]
output = await model_.ainvoke(messages)
@@ -1161,7 +1169,7 @@ def create_agent( # noqa: PLR0915
request = ModelRequest(
model=model,
tools=default_tools,
- system_prompt=system_prompt,
+ system_message=system_message,
response_format=initial_response_format,
messages=state["messages"],
tool_choice=None,
diff --git a/libs/langchain_v1/langchain/agents/middleware/context_editing.py b/libs/langchain_v1/langchain/agents/middleware/context_editing.py
index 42488276ab..538b6ee567 100644
--- a/libs/langchain_v1/langchain/agents/middleware/context_editing.py
+++ b/libs/langchain_v1/langchain/agents/middleware/context_editing.py
@@ -18,7 +18,6 @@ from langchain_core.messages import (
AIMessage,
AnyMessage,
BaseMessage,
- SystemMessage,
ToolMessage,
)
from langchain_core.messages.utils import count_tokens_approximately
@@ -230,9 +229,7 @@ class ContextEditingMiddleware(AgentMiddleware):
def count_tokens(messages: Sequence[BaseMessage]) -> int:
return count_tokens_approximately(messages)
else:
- system_msg = (
- [SystemMessage(content=request.system_prompt)] if request.system_prompt else []
- )
+ system_msg = [request.system_message] if request.system_message else []
def count_tokens(messages: Sequence[BaseMessage]) -> int:
return request.model.get_num_tokens_from_messages(
@@ -259,9 +256,7 @@ class ContextEditingMiddleware(AgentMiddleware):
def count_tokens(messages: Sequence[BaseMessage]) -> int:
return count_tokens_approximately(messages)
else:
- system_msg = (
- [SystemMessage(content=request.system_prompt)] if request.system_prompt else []
- )
+ system_msg = [request.system_message] if request.system_message else []
def count_tokens(messages: Sequence[BaseMessage]) -> int:
return request.model.get_num_tokens_from_messages(
diff --git a/libs/langchain_v1/langchain/agents/middleware/todo.py b/libs/langchain_v1/langchain/agents/middleware/todo.py
index ac5bfbee08..32b3d280a0 100644
--- a/libs/langchain_v1/langchain/agents/middleware/todo.py
+++ b/libs/langchain_v1/langchain/agents/middleware/todo.py
@@ -3,12 +3,12 @@
from __future__ import annotations
-from typing import TYPE_CHECKING, Annotated, Literal
+from typing import TYPE_CHECKING, Annotated, Literal, cast
if TYPE_CHECKING:
from collections.abc import Awaitable, Callable
-from langchain_core.messages import ToolMessage
+from langchain_core.messages import SystemMessage, ToolMessage
from langchain_core.tools import tool
from langgraph.types import Command
from typing_extensions import NotRequired, TypedDict
@@ -193,23 +193,33 @@ class TodoListMiddleware(AgentMiddleware):
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
- """Update the system prompt to include the todo system prompt."""
- new_system_prompt = (
- request.system_prompt + "\n\n" + self.system_prompt
- if request.system_prompt
- else self.system_prompt
+ """Update the system message to include the todo system prompt."""
+ if request.system_message is not None:
+ new_system_content = [
+ *request.system_message.content_blocks,
+ {"type": "text", "text": f"\n\n{self.system_prompt}"},
+ ]
+ else:
+ new_system_content = [{"type": "text", "text": self.system_prompt}]
+ new_system_message = SystemMessage(
+ content=cast("list[str | dict[str, str]]", new_system_content)
)
- return handler(request.override(system_prompt=new_system_prompt))
+ return handler(request.override(system_message=new_system_message))
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
- """Update the system prompt to include the todo system prompt (async version)."""
- new_system_prompt = (
- request.system_prompt + "\n\n" + self.system_prompt
- if request.system_prompt
- else self.system_prompt
+ """Update the system message to include the todo system prompt (async version)."""
+ if request.system_message is not None:
+ new_system_content = [
+ *request.system_message.content_blocks,
+ {"type": "text", "text": f"\n\n{self.system_prompt}"},
+ ]
+ else:
+ new_system_content = [{"type": "text", "text": self.system_prompt}]
+ new_system_message = SystemMessage(
+ content=cast("list[str | dict[str, str]]", new_system_content)
)
- return await handler(request.override(system_prompt=new_system_prompt))
+ return await handler(request.override(system_message=new_system_message))
diff --git a/libs/langchain_v1/langchain/agents/middleware/types.py b/libs/langchain_v1/langchain/agents/middleware/types.py
index 998fec8571..5d7ab319d1 100644
--- a/libs/langchain_v1/langchain/agents/middleware/types.py
+++ b/libs/langchain_v1/langchain/agents/middleware/types.py
@@ -20,12 +20,14 @@ if TYPE_CHECKING:
from collections.abc import Awaitable
# Needed as top level import for Pydantic schema generation on AgentState
+import warnings
from typing import TypeAlias
-from langchain_core.messages import ( # noqa: TC002
+from langchain_core.messages import (
AIMessage,
AnyMessage,
BaseMessage,
+ SystemMessage,
ToolMessage,
)
from langgraph.channels.ephemeral_value import EphemeralValue
@@ -72,7 +74,7 @@ class _ModelRequestOverrides(TypedDict, total=False):
"""Possible overrides for `ModelRequest.override()` method."""
model: BaseChatModel
- system_prompt: str | None
+ system_message: SystemMessage | None
messages: list[AnyMessage]
tool_choice: Any | None
tools: list[BaseTool | dict]
@@ -80,13 +82,13 @@ class _ModelRequestOverrides(TypedDict, total=False):
model_settings: dict[str, Any]
-@dataclass
+@dataclass(init=False)
class ModelRequest:
"""Model request information for the agent."""
model: BaseChatModel
- system_prompt: str | None
- messages: list[AnyMessage] # excluding system prompt
+ messages: list[AnyMessage] # excluding system message
+ system_message: SystemMessage | None
tool_choice: Any | None
tools: list[BaseTool | dict]
response_format: ResponseFormat | None
@@ -94,6 +96,65 @@ class ModelRequest:
runtime: Runtime[ContextT] # type: ignore[valid-type]
model_settings: dict[str, Any] = field(default_factory=dict)
+ def __init__(
+ self,
+ *,
+ model: BaseChatModel,
+ messages: list[AnyMessage],
+ system_message: SystemMessage | None = None,
+ system_prompt: str | None = None,
+ tool_choice: Any | None = None,
+ tools: list[BaseTool | dict] | None = None,
+ response_format: ResponseFormat | None = None,
+ state: AgentState | None = None,
+ runtime: Runtime[ContextT] | None = None,
+ model_settings: dict[str, Any] | None = None,
+ ) -> None:
+ """Initialize ModelRequest with backward compatibility for system_prompt.
+
+ Args:
+ model: The chat model to use.
+ messages: List of messages (excluding system prompt).
+ tool_choice: Tool choice configuration.
+ tools: List of available tools.
+ response_format: Response format specification.
+ state: Agent state.
+ runtime: Runtime context.
+ model_settings: Additional model settings.
+ system_message: System message instance (preferred).
+ system_prompt: System prompt string (deprecated, converted to SystemMessage).
+ """
+ # Handle system_prompt/system_message conversion and validation
+ if system_prompt is not None and system_message is not None:
+ msg = "Cannot specify both system_prompt and system_message"
+ raise ValueError(msg)
+
+ if system_prompt is not None:
+ system_message = SystemMessage(content=system_prompt)
+
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore", category=DeprecationWarning)
+ self.model = model
+ self.messages = messages
+ self.system_message = system_message
+ self.tool_choice = tool_choice
+ self.tools = tools if tools is not None else []
+ self.response_format = response_format
+ self.state = state if state is not None else {"messages": []}
+ self.runtime = runtime # type: ignore[assignment]
+ self.model_settings = model_settings if model_settings is not None else {}
+
+ @property
+ def system_prompt(self) -> str | None:
+ """Get system prompt text from system_message.
+
+ Returns:
+ The content of the system message if present, otherwise `None`.
+ """
+ if self.system_message is None:
+ return None
+ return self.system_message.text
+
def __setattr__(self, name: str, value: Any) -> None:
"""Set an attribute with a deprecation warning.
@@ -104,20 +165,29 @@ class ModelRequest:
name: Attribute name.
value: Attribute value.
"""
- import warnings
-
- # Allow setting attributes during __init__ (when object is being constructed)
- if not hasattr(self, "__dataclass_fields__") or not hasattr(self, name):
- object.__setattr__(self, name, value)
- else:
+ # Special handling for system_prompt - convert to system_message
+ if name == "system_prompt":
warnings.warn(
- f"Direct attribute assignment to ModelRequest.{name} is deprecated. "
- f"Use request.override({name}=...) instead to create a new request "
- f"with the modified attribute.",
+ "Direct attribute assignment to ModelRequest.system_prompt is deprecated. "
+ "Use request.override(system_message=SystemMessage(...)) instead to create "
+ "a new request with the modified system message.",
DeprecationWarning,
stacklevel=2,
)
- object.__setattr__(self, name, value)
+ if value is None:
+ object.__setattr__(self, "system_message", None)
+ else:
+ object.__setattr__(self, "system_message", SystemMessage(content=value))
+ return
+
+ warnings.warn(
+ f"Direct attribute assignment to ModelRequest.{name} is deprecated. "
+ f"Use request.override({name}=...) instead to create a new request "
+ f"with the modified attribute.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ object.__setattr__(self, name, value)
def override(self, **overrides: Unpack[_ModelRequestOverrides]) -> ModelRequest:
"""Replace the request with a new request with the given overrides.
@@ -132,7 +202,8 @@ class ModelRequest:
Supported keys:
- `model`: `BaseChatModel` instance
- - `system_prompt`: Optional system prompt string
+ - `system_prompt`: deprecated, use `system_message` instead
+ - `system_message`: `SystemMessage` instance
- `messages`: `list` of messages
- `tool_choice`: Tool choice configuration
- `tools`: `list` of available tools
@@ -149,12 +220,37 @@ class ModelRequest:
new_request = request.override(model=different_model)
```
+ !!! example "Override system message (preferred)"
+
+ ```python
+ from langchain_core.messages import SystemMessage
+
+ new_request = request.override(
+ system_message=SystemMessage(content="New instructions")
+ )
+ ```
+
!!! example "Override multiple attributes"
```python
- new_request = request.override(system_prompt="New instructions", tool_choice="auto")
+ new_request = request.override(
+ model=ChatOpenAI(model="gpt-4o"),
+ system_message=SystemMessage(content="New instructions"),
+ )
```
"""
+ # Handle system_prompt/system_message conversion
+ if "system_prompt" in overrides and "system_message" in overrides:
+ msg = "Cannot specify both system_prompt and system_message"
+ raise ValueError(msg)
+
+ if "system_prompt" in overrides:
+ system_prompt = cast("str", overrides.pop("system_prompt")) # type: ignore[typeddict-item]
+ if system_prompt is None:
+ overrides["system_message"] = None
+ else:
+ overrides["system_message"] = SystemMessage(content=system_prompt)
+
return replace(self, **overrides)
@@ -602,11 +698,13 @@ class _CallableWithStateAndRuntime(Protocol[StateT_contra, ContextT]):
...
-class _CallableReturningPromptString(Protocol[StateT_contra, ContextT]): # type: ignore[misc]
- """Callable that returns a prompt string given `ModelRequest` (contains state and runtime)."""
+class _CallableReturningSystemMessage(Protocol[StateT_contra, ContextT]): # type: ignore[misc]
+ """Callable that returns a prompt string or SystemMessage given `ModelRequest`."""
- def __call__(self, request: ModelRequest) -> str | Awaitable[str]:
- """Generate a system prompt string based on the request."""
+ def __call__(
+ self, request: ModelRequest
+ ) -> str | SystemMessage | Awaitable[str | SystemMessage]:
+ """Generate a system prompt string or SystemMessage based on the request."""
...
@@ -1287,7 +1385,7 @@ def after_agent(
@overload
def dynamic_prompt(
- func: _CallableReturningPromptString[StateT, ContextT],
+ func: _CallableReturningSystemMessage[StateT, ContextT],
) -> AgentMiddleware[StateT, ContextT]: ...
@@ -1295,16 +1393,16 @@ def dynamic_prompt(
def dynamic_prompt(
func: None = None,
) -> Callable[
- [_CallableReturningPromptString[StateT, ContextT]],
+ [_CallableReturningSystemMessage[StateT, ContextT]],
AgentMiddleware[StateT, ContextT],
]: ...
def dynamic_prompt(
- func: _CallableReturningPromptString[StateT, ContextT] | None = None,
+ func: _CallableReturningSystemMessage[StateT, ContextT] | None = None,
) -> (
Callable[
- [_CallableReturningPromptString[StateT, ContextT]],
+ [_CallableReturningSystemMessage[StateT, ContextT]],
AgentMiddleware[StateT, ContextT],
]
| AgentMiddleware[StateT, ContextT]
@@ -1326,7 +1424,8 @@ def dynamic_prompt(
function that can be applied to a function.
The decorated function should return:
- - `str` – The system prompt to use for the model request
+ - `str` – The system prompt string to use for the model request
+ - `SystemMessage` – A complete system message to use for the model request
Examples:
Basic usage with dynamic content:
@@ -1357,7 +1456,7 @@ def dynamic_prompt(
"""
def decorator(
- func: _CallableReturningPromptString[StateT, ContextT],
+ func: _CallableReturningSystemMessage[StateT, ContextT],
) -> AgentMiddleware[StateT, ContextT]:
is_async = iscoroutinefunction(func)
@@ -1369,7 +1468,10 @@ def dynamic_prompt(
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
prompt = await func(request) # type: ignore[misc]
- request = request.override(system_prompt=prompt)
+ if isinstance(prompt, SystemMessage):
+ request = request.override(system_message=prompt)
+ else:
+ request = request.override(system_message=SystemMessage(content=prompt))
return await handler(request)
middleware_name = cast("str", getattr(func, "__name__", "DynamicPromptMiddleware"))
@@ -1389,8 +1491,11 @@ def dynamic_prompt(
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
- prompt = cast("str", func(request))
- request = request.override(system_prompt=prompt)
+ prompt = cast("Callable[[ModelRequest], SystemMessage | str]", func)(request)
+ if isinstance(prompt, SystemMessage):
+ request = request.override(system_message=prompt)
+ else:
+ request = request.override(system_message=SystemMessage(content=prompt))
return handler(request)
async def async_wrapped_from_sync(
@@ -1399,8 +1504,11 @@ def dynamic_prompt(
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
# Delegate to sync function
- prompt = cast("str", func(request))
- request = request.override(system_prompt=prompt)
+ prompt = cast("Callable[[ModelRequest], SystemMessage | str]", func)(request)
+ if isinstance(prompt, SystemMessage):
+ request = request.override(system_message=prompt)
+ else:
+ request = request.override(system_message=SystemMessage(content=prompt))
return await handler(request)
middleware_name = cast("str", getattr(func, "__name__", "DynamicPromptMiddleware"))
diff --git a/libs/langchain_v1/tests/unit_tests/agents/model.py b/libs/langchain_v1/tests/unit_tests/agents/model.py
index 8b948f658a..247c64c80f 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/model.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/model.py
@@ -59,7 +59,7 @@ class FakeToolCallingModel(BaseChatModel, Generic[StructuredResponseT]):
content_obj = self.structured_response
message = AIMessage(content=json.dumps(content_obj), id=str(self.index))
else:
- messages_string = "-".join([m.content for m in messages])
+ messages_string = "-".join([m.text for m in messages])
message = AIMessage(
content=messages_string,
id=str(self.index),
diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_system_message.py b/libs/langchain_v1/tests/unit_tests/agents/test_system_message.py
new file mode 100644
index 0000000000..e75b150db5
--- /dev/null
+++ b/libs/langchain_v1/tests/unit_tests/agents/test_system_message.py
@@ -0,0 +1,1013 @@
+"""Comprehensive unit tests for system message handling in agents.
+
+This module consolidates all system message and dynamic prompt tests:
+- Basic system message scenarios (none, string, SystemMessage)
+- ModelRequest system_message field support
+- System message updates via middleware
+- Multiple middleware chaining
+- Cache control preservation
+- Metadata merging
+- Dynamic system prompt middleware
+- Edge cases and error handling
+
+These tests replicate functionality from langchainjs PR #9459.
+"""
+
+from typing import cast
+
+import pytest
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+from langgraph.runtime import Runtime
+
+from langchain.agents.factory import create_agent
+from langchain.agents.middleware.types import ModelRequest, ModelResponse
+
+from .model import FakeToolCallingModel
+
+
+def _fake_runtime(context: dict | None = None) -> Runtime:
+ """Create a fake runtime with optional context."""
+ if context:
+ # Create a simple object with context
+ class FakeRuntime:
+ def __init__(self):
+ self.context = type("Context", (), context)()
+
+ return cast(Runtime, FakeRuntime())
+ return cast(Runtime, object())
+
+
+def _make_request(
+ system_message: SystemMessage | None = None,
+ system_prompt: str | None = None,
+) -> ModelRequest:
+ """Create a minimal ModelRequest for testing."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ return ModelRequest(
+ model=model,
+ system_message=system_message,
+ system_prompt=system_prompt,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ model_settings={},
+ )
+
+
+# =============================================================================
+# ModelRequest Tests
+# =============================================================================
+
+
+class TestModelRequestSystemMessage:
+ """Test ModelRequest with system_message field."""
+
+ @pytest.mark.parametrize(
+ "system_message,system_prompt,expected_msg,expected_prompt",
+ [
+ # Test with SystemMessage
+ (
+ SystemMessage(content="You are helpful"),
+ None,
+ SystemMessage(content="You are helpful"),
+ "You are helpful",
+ ),
+ # Test with None
+ (None, None, None, None),
+ # Test with string (backward compat)
+ (None, "You are helpful", SystemMessage(content="You are helpful"), "You are helpful"),
+ ],
+ )
+ def test_create_with_various_system_inputs(
+ self, system_message, system_prompt, expected_msg, expected_prompt
+ ) -> None:
+ """Test creating ModelRequest with various system message inputs."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+
+ request = ModelRequest(
+ model=model,
+ system_message=system_message,
+ system_prompt=system_prompt,
+ messages=[HumanMessage("Hi")],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+
+ if expected_msg is None:
+ assert request.system_message is None
+ else:
+ assert request.system_message.content == expected_msg.content
+ assert request.system_prompt == expected_prompt
+
+ def test_system_prompt_property_with_list_content(self) -> None:
+ """Test system_prompt property handles list content."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+ system_msg = SystemMessage(content=["Part 1", "Part 2"])
+
+ request = ModelRequest(
+ model=model,
+ system_message=system_msg,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+
+ assert request.system_prompt is not None
+ assert "Part 1" in request.system_prompt
+
+ @pytest.mark.parametrize(
+ "override_with,expected_text",
+ [
+ ("system_message", "New"),
+ ("system_prompt", "New prompt"),
+ ],
+ )
+ def test_override_methods(self, override_with, expected_text) -> None:
+ """Test override() with system_message and system_prompt parameters."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+ original_msg = SystemMessage(content="Original")
+
+ original_request = ModelRequest(
+ model=model,
+ system_message=original_msg,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+
+ if override_with == "system_message":
+ new_request = original_request.override(system_message=SystemMessage(content="New"))
+ else: # system_prompt
+ new_request = original_request.override(system_prompt="New prompt")
+
+ assert isinstance(new_request.system_message, SystemMessage)
+ assert new_request.system_prompt == expected_text
+ assert original_request.system_prompt == "Original"
+
+ def test_override_system_prompt_to_none(self) -> None:
+ """Test override() setting system_prompt to None."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+
+ original_request = ModelRequest(
+ model=model,
+ system_message=SystemMessage(content="Original"),
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+
+ new_request = original_request.override(system_prompt=None)
+
+ assert new_request.system_message is None
+ assert new_request.system_prompt is None
+
+ @pytest.mark.parametrize(
+ "use_constructor",
+ [True, False],
+ ids=["constructor", "override"],
+ )
+ def test_cannot_set_both_system_prompt_and_system_message(self, use_constructor) -> None:
+ """Test that setting both system_prompt and system_message raises error."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+
+ with pytest.raises(ValueError, match="Cannot specify both"):
+ if use_constructor:
+ ModelRequest(
+ model=model,
+ system_prompt="String prompt",
+ system_message=SystemMessage(content="Message prompt"),
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+ else:
+ request = ModelRequest(
+ model=model,
+ system_message=None,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+ request.override(
+ system_prompt="String prompt",
+ system_message=SystemMessage(content="Message prompt"),
+ )
+
+ @pytest.mark.parametrize(
+ "new_value,should_be_none",
+ [
+ ("New prompt", False),
+ (None, True),
+ ],
+ )
+ def test_setattr_system_prompt_deprecated(self, new_value, should_be_none) -> None:
+ """Test that setting system_prompt via setattr raises deprecation warning."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+
+ request = ModelRequest(
+ model=model,
+ system_message=SystemMessage(content="Original") if not should_be_none else None,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+
+ with pytest.warns(DeprecationWarning, match="system_prompt is deprecated"):
+ request.system_prompt = new_value
+
+ if should_be_none:
+ assert request.system_message is None
+ assert request.system_prompt is None
+ else:
+ assert isinstance(request.system_message, SystemMessage)
+ assert request.system_message.content_blocks[0]["text"] == new_value
+
+ def test_system_message_with_complex_content(self) -> None:
+ """Test SystemMessage with complex content (list of dicts)."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+ system_msg = SystemMessage(
+ content=[
+ {"type": "text", "text": "You are helpful"},
+ {"type": "text", "text": "Be concise", "cache_control": {"type": "ephemeral"}},
+ ]
+ )
+
+ request = ModelRequest(
+ model=model,
+ system_message=system_msg,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+
+ assert isinstance(request.system_message.content_blocks, list)
+ assert len(request.system_message.content_blocks) == 2
+ assert request.system_message.content_blocks[1].get("cache_control") == {
+ "type": "ephemeral"
+ }
+
+ def test_multiple_overrides_with_system_message(self) -> None:
+ """Test chaining overrides with system_message."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+
+ original_request = ModelRequest(
+ model=model,
+ system_message=SystemMessage(content="Prompt 1"),
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={},
+ runtime=None,
+ )
+
+ final_request = (
+ original_request.override(system_message=SystemMessage(content="Prompt 2"))
+ .override(tool_choice="auto")
+ .override(system_message=SystemMessage(content="Prompt 3"))
+ )
+
+ assert final_request.system_prompt == "Prompt 3"
+ assert final_request.tool_choice == "auto"
+ assert original_request.system_prompt == "Prompt 1"
+
+
+# =============================================================================
+# create_agent Tests
+# =============================================================================
+
+
+class TestCreateAgentSystemMessage:
+ """Test create_agent with various system message inputs."""
+
+ @pytest.mark.parametrize(
+ "system_prompt",
+ [
+ None,
+ "You are a helpful assistant",
+ SystemMessage(content="You are a helpful assistant"),
+ SystemMessage(
+ content="You are a helpful assistant",
+ additional_kwargs={"role": "system_admin", "priority": "high"},
+ response_metadata={"model": "gpt-4", "temperature": 0.7},
+ ),
+ SystemMessage(
+ content=[
+ {"type": "text", "text": "You are a helpful assistant"},
+ {
+ "type": "text",
+ "text": "Follow these rules carefully",
+ "cache_control": {"type": "ephemeral"},
+ },
+ ]
+ ),
+ ],
+ ids=[
+ "none",
+ "string",
+ "system_message",
+ "system_message_with_metadata",
+ "system_message_with_complex_content",
+ ],
+ )
+ def test_create_agent_with_various_system_prompts(self, system_prompt) -> None:
+ """Test create_agent accepts various system_prompt formats."""
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="Hello")]))
+
+ agent = create_agent(
+ model=model,
+ system_prompt=system_prompt,
+ )
+
+ assert agent is not None
+
+
+# =============================================================================
+# Middleware Tests
+# =============================================================================
+
+
+class TestSystemMessageUpdateViaMiddleware:
+ """Test updating system messages through middleware."""
+
+ def test_middleware_can_set_initial_system_message(self) -> None:
+ """Test middleware setting system message when none exists."""
+
+ def set_system_message_middleware(
+ request: ModelRequest,
+ handler,
+ ) -> ModelResponse:
+ """Middleware that sets initial system message."""
+ new_request = request.override(
+ system_message=SystemMessage(content="Set by middleware")
+ )
+ return handler(new_request)
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=None,
+ messages=[HumanMessage(content="Hello")],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ captured_request = None
+
+ def mock_handler(req: ModelRequest) -> ModelResponse:
+ nonlocal captured_request
+ captured_request = req
+ return ModelResponse(result=[AIMessage(content="response")])
+
+ set_system_message_middleware(request, mock_handler)
+
+ assert captured_request is not None
+ assert captured_request.system_message is not None
+ assert len(captured_request.system_message.content_blocks) == 1
+ assert captured_request.system_message.content_blocks[0]["text"] == "Set by middleware"
+
+ def test_middleware_can_update_via_system_message_object(self) -> None:
+ """Test middleware updating system message using SystemMessage objects."""
+
+ def append_with_metadata_middleware(
+ request: ModelRequest,
+ handler,
+ ) -> ModelResponse:
+ """Append using SystemMessage to preserve metadata."""
+ base_content = request.system_message.text if request.system_message else ""
+ base_kwargs = request.system_message.additional_kwargs if request.system_message else {}
+
+ new_message = SystemMessage(
+ content=base_content + " Additional instructions.",
+ additional_kwargs={**base_kwargs, "middleware": "applied"},
+ )
+ new_request = request.override(system_message=new_message)
+ return handler(new_request)
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=SystemMessage(
+ content="Base prompt", additional_kwargs={"base": "value"}
+ ),
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ captured_request = None
+
+ def mock_handler(req: ModelRequest) -> ModelResponse:
+ nonlocal captured_request
+ captured_request = req
+ return ModelResponse(result=[AIMessage(content="response")])
+
+ append_with_metadata_middleware(request, mock_handler)
+
+ assert captured_request is not None
+ assert "Base prompt Additional instructions." == captured_request.system_message.text
+ assert captured_request.system_message.additional_kwargs["base"] == "value"
+ assert captured_request.system_message.additional_kwargs["middleware"] == "applied"
+
+
+class TestMultipleMiddlewareChaining:
+ """Test multiple middleware modifying system message in sequence."""
+
+ def test_multiple_middleware_can_chain_modifications(self) -> None:
+ """Test that multiple middleware can modify system message sequentially."""
+
+ def first_middleware(request: ModelRequest, handler) -> ModelResponse:
+ """First middleware sets base system message."""
+ new_request = request.override(
+ system_message=SystemMessage(
+ content="Base prompt",
+ additional_kwargs={"middleware_1": "applied"},
+ )
+ )
+ return handler(new_request)
+
+ def second_middleware(request: ModelRequest, handler) -> ModelResponse:
+ """Second middleware appends to system message."""
+ current_content = request.system_message.text
+ current_kwargs = request.system_message.additional_kwargs
+
+ new_request = request.override(
+ system_message=SystemMessage(
+ content=current_content + " + middleware 2",
+ additional_kwargs={**current_kwargs, "middleware_2": "applied"},
+ )
+ )
+ return handler(new_request)
+
+ def third_middleware(request: ModelRequest, handler) -> ModelResponse:
+ """Third middleware appends to system message."""
+ current_content = request.system_message.text
+ current_kwargs = request.system_message.additional_kwargs
+
+ new_request = request.override(
+ system_message=SystemMessage(
+ content=current_content + " + middleware 3",
+ additional_kwargs={**current_kwargs, "middleware_3": "applied"},
+ )
+ )
+ return handler(new_request)
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=None,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ def final_handler(req: ModelRequest) -> ModelResponse:
+ # Verify all middleware applied
+ assert req.system_message.text == "Base prompt + middleware 2 + middleware 3"
+ assert req.system_message.additional_kwargs["middleware_1"] == "applied"
+ assert req.system_message.additional_kwargs["middleware_2"] == "applied"
+ assert req.system_message.additional_kwargs["middleware_3"] == "applied"
+ return ModelResponse(result=[AIMessage(content="response")])
+
+ # Chain middleware calls
+ first_middleware(
+ request,
+ lambda req: second_middleware(req, lambda req2: third_middleware(req2, final_handler)),
+ )
+
+ def test_middleware_can_mix_string_and_system_message_updates(self) -> None:
+ """Test mixing string and SystemMessage updates across middleware."""
+
+ def string_middleware(request: ModelRequest, handler) -> ModelResponse:
+ """Use string-based update."""
+ new_request = request.override(system_prompt="String prompt")
+ return handler(new_request)
+
+ def system_message_middleware(request: ModelRequest, handler) -> ModelResponse:
+ """Use SystemMessage-based update."""
+ current_content = request.system_message.text if request.system_message else ""
+ new_request = request.override(
+ system_message=SystemMessage(
+ content=current_content + " + SystemMessage",
+ additional_kwargs={"metadata": "added"},
+ )
+ )
+ return handler(new_request)
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=None,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ def final_handler(req: ModelRequest) -> ModelResponse:
+ assert "String prompt + SystemMessage" == req.system_message.text
+ assert req.system_message.additional_kwargs["metadata"] == "added"
+ return ModelResponse(result=[AIMessage(content="response")])
+
+ string_middleware(request, lambda req: system_message_middleware(req, final_handler))
+
+
+class TestCacheControlPreservation:
+ """Test cache control metadata preservation in system messages."""
+
+ def test_middleware_can_add_cache_control(self) -> None:
+ """Test middleware adding cache control to system message."""
+
+ def cache_control_middleware(request: ModelRequest, handler) -> ModelResponse:
+ """Add cache control to system message."""
+ new_message = SystemMessage(
+ content=[
+ {"type": "text", "text": "Base instructions"},
+ {
+ "type": "text",
+ "text": "Cached instructions",
+ "cache_control": {"type": "ephemeral"},
+ },
+ ]
+ )
+ new_request = request.override(system_message=new_message)
+ return handler(new_request)
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=None,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ captured_request = None
+
+ def mock_handler(req: ModelRequest) -> ModelResponse:
+ nonlocal captured_request
+ captured_request = req
+ return ModelResponse(result=[AIMessage(content="response")])
+
+ cache_control_middleware(request, mock_handler)
+
+ assert captured_request is not None
+ assert isinstance(captured_request.system_message.content_blocks, list)
+ assert captured_request.system_message.content_blocks[1]["cache_control"] == {
+ "type": "ephemeral"
+ }
+
+ def test_cache_control_preserved_across_middleware(self) -> None:
+ """Test that cache control is preserved when middleware modifies message."""
+
+ def first_middleware_with_cache(request: ModelRequest, handler) -> ModelResponse:
+ """Set system message with cache control."""
+ new_message = SystemMessage(
+ content=[
+ {
+ "type": "text",
+ "text": "Cached content",
+ "cache_control": {"type": "ephemeral"},
+ }
+ ]
+ )
+ new_request = request.override(system_message=new_message)
+ return handler(new_request)
+
+ def second_middleware_appends(request: ModelRequest, handler) -> ModelResponse:
+ """Append to system message while preserving cache control."""
+ existing_content = request.system_message.content_blocks
+ new_content = existing_content + [{"type": "text", "text": "Additional text"}]
+
+ new_message = SystemMessage(content=new_content)
+ new_request = request.override(system_message=new_message)
+ return handler(new_request)
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=None,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ def final_handler(req: ModelRequest) -> ModelResponse:
+ # Verify cache control was preserved
+ assert isinstance(req.system_message.content_blocks, list)
+ assert len(req.system_message.content_blocks) == 2
+ assert req.system_message.content_blocks[0]["cache_control"] == {"type": "ephemeral"}
+ return ModelResponse(result=[AIMessage(content="response")])
+
+ first_middleware_with_cache(
+ request, lambda req: second_middleware_appends(req, final_handler)
+ )
+
+
+class TestMetadataMerging:
+ """Test metadata merging behavior when updating system messages."""
+
+ @pytest.mark.parametrize(
+ "metadata_type,initial_metadata,update_metadata,expected_result",
+ [
+ # additional_kwargs merging
+ (
+ "additional_kwargs",
+ {"key1": "value1", "shared": "original"},
+ {"key2": "value2", "shared": "updated"},
+ {"key1": "value1", "key2": "value2", "shared": "updated"},
+ ),
+ # response_metadata merging
+ (
+ "response_metadata",
+ {"model": "gpt-4", "region": "us-east"},
+ {"tokens": 100, "region": "eu-west"},
+ {"model": "gpt-4", "tokens": 100, "region": "eu-west"},
+ ),
+ ],
+ ids=["additional_kwargs", "response_metadata"],
+ )
+ def test_metadata_merge_across_updates(
+ self, metadata_type, initial_metadata, update_metadata, expected_result
+ ) -> None:
+ """Test that metadata merges correctly when updating system message."""
+ base_message = SystemMessage(
+ content="Base",
+ **{metadata_type: initial_metadata},
+ )
+
+ def update_middleware(request: ModelRequest, handler) -> ModelResponse:
+ """Update system message, merging metadata."""
+ current_metadata = getattr(request.system_message, metadata_type)
+ new_metadata = {**current_metadata, **update_metadata}
+
+ new_request = request.override(
+ system_message=SystemMessage(content="Updated", **{metadata_type: new_metadata})
+ )
+ return handler(new_request)
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=base_message,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ captured_request = None
+
+ def mock_handler(req: ModelRequest) -> ModelResponse:
+ nonlocal captured_request
+ captured_request = req
+ return ModelResponse(result=[AIMessage(content="response")])
+
+ update_middleware(request, mock_handler)
+
+ assert captured_request is not None
+ assert getattr(captured_request.system_message, metadata_type) == expected_result
+
+
+# =============================================================================
+# Dynamic System Prompt Middleware Tests
+# =============================================================================
+
+
+class TestDynamicSystemPromptMiddleware:
+ """Test middleware that accepts SystemMessage return types."""
+
+ def test_middleware_can_return_system_message(self) -> None:
+ """Test that middleware can return a SystemMessage with dynamic content."""
+
+ def dynamic_system_prompt_middleware(request: ModelRequest) -> SystemMessage:
+ """Return a SystemMessage with dynamic content."""
+ region = getattr(request.runtime.context, "region", "n/a")
+ return SystemMessage(content=f"You are a helpful assistant. Region: {region}")
+
+ runtime = _fake_runtime(context={"region": "EU"})
+ request = ModelRequest(
+ model=GenericFakeChatModel(messages=iter([AIMessage(content="response")])),
+ system_message=None,
+ messages=[HumanMessage(content="Hello")],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=runtime,
+ model_settings={},
+ )
+
+ new_system_message = dynamic_system_prompt_middleware(request)
+
+ assert isinstance(new_system_message, SystemMessage)
+ assert len(new_system_message.content_blocks) == 1
+ assert (
+ new_system_message.content_blocks[0]["text"]
+ == "You are a helpful assistant. Region: EU"
+ )
+
+ def test_middleware_can_use_system_message_with_metadata(self) -> None:
+ """Test middleware creating SystemMessage with additional metadata."""
+
+ def metadata_middleware(request: ModelRequest) -> SystemMessage:
+ """Return SystemMessage with metadata."""
+ return SystemMessage(
+ content="You are a helpful assistant",
+ additional_kwargs={"temperature": 0.7, "model": "gpt-4"},
+ response_metadata={"region": "us-east"},
+ )
+
+ request = _make_request()
+ new_system_message = metadata_middleware(request)
+
+ assert len(new_system_message.content_blocks) == 1
+ assert new_system_message.content_blocks[0]["text"] == "You are a helpful assistant"
+ assert new_system_message.additional_kwargs == {
+ "temperature": 0.7,
+ "model": "gpt-4",
+ }
+ assert new_system_message.response_metadata == {"region": "us-east"}
+
+ def test_middleware_handles_none_system_message(self) -> None:
+ """Test middleware creating new SystemMessage when none exists."""
+
+ def create_if_none_middleware(request: ModelRequest) -> SystemMessage:
+ """Create a system message if none exists."""
+ if request.system_message is None:
+ return SystemMessage(content="Default system prompt")
+ return request.system_message
+
+ request = _make_request(system_message=None)
+ new_system_message = create_if_none_middleware(request)
+
+ assert isinstance(new_system_message, SystemMessage)
+ assert len(new_system_message.content_blocks) == 1
+ assert new_system_message.content_blocks[0]["text"] == "Default system prompt"
+
+ def test_middleware_with_content_blocks(self) -> None:
+ """Test middleware creating SystemMessage with content blocks."""
+
+ def content_blocks_middleware(request: ModelRequest) -> SystemMessage:
+ """Create SystemMessage with content blocks including cache control."""
+ return SystemMessage(
+ content=[
+ {"type": "text", "text": "Base instructions"},
+ {
+ "type": "text",
+ "text": "Cached instructions",
+ "cache_control": {"type": "ephemeral"},
+ },
+ ]
+ )
+
+ request = _make_request()
+ new_system_message = content_blocks_middleware(request)
+
+ assert isinstance(new_system_message.content_blocks, list)
+ assert len(new_system_message.content_blocks) == 2
+ assert new_system_message.content_blocks[0]["text"] == "Base instructions"
+ assert new_system_message.content_blocks[1]["cache_control"] == {"type": "ephemeral"}
+
+
+class TestSystemMessageMiddlewareIntegration:
+ """Test integration of SystemMessage with middleware chain."""
+
+ def test_multiple_middleware_can_modify_system_message(self) -> None:
+ """Test that multiple middleware can modify system message in sequence."""
+
+ def first_middleware(request: ModelRequest) -> ModelRequest:
+ """First middleware adds base system message."""
+ new_message = SystemMessage(
+ content="You are an assistant.",
+ additional_kwargs={"middleware_1": "applied"},
+ )
+ return request.override(system_message=new_message)
+
+ def second_middleware(request: ModelRequest) -> ModelRequest:
+ """Second middleware appends to system message."""
+ current_content = request.system_message.text
+ new_content = current_content + " Be helpful."
+
+ merged_kwargs = {
+ **request.system_message.additional_kwargs,
+ "middleware_2": "applied",
+ }
+
+ new_message = SystemMessage(
+ content=new_content,
+ additional_kwargs=merged_kwargs,
+ )
+ return request.override(system_message=new_message)
+
+ request = _make_request(system_message=None)
+
+ # Apply middleware in sequence
+ request = first_middleware(request)
+ assert len(request.system_message.content_blocks) == 1
+ assert request.system_message.content_blocks[0]["text"] == "You are an assistant."
+ assert request.system_message.additional_kwargs["middleware_1"] == "applied"
+
+ request = second_middleware(request)
+ assert len(request.system_message.content_blocks) == 1
+ assert (
+ request.system_message.content_blocks[0]["text"] == "You are an assistant. Be helpful."
+ )
+ assert request.system_message.additional_kwargs["middleware_1"] == "applied"
+ assert request.system_message.additional_kwargs["middleware_2"] == "applied"
+
+ def test_middleware_preserves_system_message_metadata(self) -> None:
+ """Test that metadata is preserved when middleware modifies system message."""
+ base_message = SystemMessage(
+ content="Base prompt",
+ additional_kwargs={"key1": "value1", "key2": "value2"},
+ response_metadata={"model": "gpt-4"},
+ )
+
+ def preserving_middleware(request: ModelRequest) -> ModelRequest:
+ """Middleware that preserves existing metadata."""
+ new_message = SystemMessage(
+ content=request.system_message.text + " Extended.",
+ additional_kwargs=request.system_message.additional_kwargs,
+ response_metadata=request.system_message.response_metadata,
+ )
+ return request.override(system_message=new_message)
+
+ request = _make_request(system_message=base_message)
+ new_request = preserving_middleware(request)
+
+ assert len(new_request.system_message.content_blocks) == 1
+ assert new_request.system_message.content_blocks[0]["text"] == "Base prompt Extended."
+ assert new_request.system_message.additional_kwargs == {
+ "key1": "value1",
+ "key2": "value2",
+ }
+ assert new_request.system_message.response_metadata == {"model": "gpt-4"}
+
+ def test_backward_compatibility_with_string_system_prompt(self) -> None:
+ """Test that middleware still works with string system prompts."""
+
+ def string_middleware(request: ModelRequest) -> ModelRequest:
+ """Middleware using string system prompt (backward compatible)."""
+ current_prompt = request.system_prompt or ""
+ new_prompt = current_prompt + " Additional instructions."
+ return request.override(system_prompt=new_prompt.strip())
+
+ request = _make_request(system_prompt="Base prompt")
+ new_request = string_middleware(request)
+
+ assert new_request.system_prompt == "Base prompt Additional instructions."
+ assert isinstance(new_request.system_message, SystemMessage)
+
+ @pytest.mark.parametrize(
+ "initial_value",
+ [
+ SystemMessage(content="Hello"),
+ "Hello",
+ None,
+ ],
+ ids=["system_message", "string", "none"],
+ )
+ def test_middleware_can_switch_between_formats(self, initial_value) -> None:
+ """Test middleware can work with SystemMessage, string, or None."""
+
+ def flexible_middleware(request: ModelRequest) -> ModelRequest:
+ """Middleware that works with various formats."""
+ if request.system_message:
+ new_message = SystemMessage(content=request.system_message.text + " [modified]")
+ return request.override(system_message=new_message)
+ else:
+ new_message = SystemMessage(content="[created]")
+ return request.override(system_message=new_message)
+
+ if isinstance(initial_value, SystemMessage):
+ request = _make_request(system_message=initial_value)
+ expected_text = "Hello [modified]"
+ elif isinstance(initial_value, str):
+ request = _make_request(system_prompt=initial_value)
+ expected_text = "Hello [modified]"
+ else: # None
+ request = _make_request(system_message=None)
+ expected_text = "[created]"
+
+ result = flexible_middleware(request)
+ assert len(result.system_message.content_blocks) == 1
+ assert result.system_message.content_blocks[0]["text"] == expected_text
+
+
+# =============================================================================
+# Edge Cases and Error Handling
+# =============================================================================
+
+
+class TestEdgeCasesAndErrorHandling:
+ """Test edge cases and error handling for system messages."""
+
+ @pytest.mark.parametrize(
+ "content,expected_blocks,expected_prompt",
+ [
+ ("", 0, ""),
+ (
+ [
+ {"type": "text", "text": "Block 1"},
+ {"type": "text", "text": "Block 2"},
+ {"type": "text", "text": "Block 3"},
+ ],
+ 3,
+ None,
+ ),
+ ],
+ ids=["empty_content", "multiple_blocks"],
+ )
+ def test_system_message_content_variations(
+ self, content, expected_blocks, expected_prompt
+ ) -> None:
+ """Test SystemMessage with various content variations."""
+ system_message = SystemMessage(content=content)
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=system_message,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ if isinstance(content, list):
+ assert isinstance(request.system_message.content_blocks, list)
+ assert len(request.system_message.content_blocks) == expected_blocks
+ else:
+ assert len(request.system_message.content_blocks) == expected_blocks
+ assert request.system_prompt == expected_prompt
+
+ def test_reset_system_prompt_to_none(self) -> None:
+ """Test resetting system prompt to None."""
+ base_message = SystemMessage(content="Original prompt")
+
+ model = GenericFakeChatModel(messages=iter([AIMessage(content="response")]))
+ request = ModelRequest(
+ model=model,
+ system_message=base_message,
+ messages=[],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state=cast("AgentState", {"messages": []}), # type: ignore[name-defined]
+ runtime=_fake_runtime(),
+ )
+
+ new_request = request.override(system_message=None)
+
+ assert new_request.system_message is None
+ assert new_request.system_prompt is None
diff --git a/libs/partners/anthropic/langchain_anthropic/middleware/anthropic_tools.py b/libs/partners/anthropic/langchain_anthropic/middleware/anthropic_tools.py
index f185e9f7e1..5641f76895 100644
--- a/libs/partners/anthropic/langchain_anthropic/middleware/anthropic_tools.py
+++ b/libs/partners/anthropic/langchain_anthropic/middleware/anthropic_tools.py
@@ -20,7 +20,7 @@ from langchain.agents.middleware.types import (
_ModelRequestOverrides,
)
from langchain.tools import ToolRuntime, tool
-from langchain_core.messages import ToolMessage
+from langchain_core.messages import SystemMessage, ToolMessage
from langgraph.types import Command
from typing_extensions import NotRequired, TypedDict
@@ -275,11 +275,17 @@ class _StateClaudeFileToolMiddleware(AgentMiddleware):
# Inject system prompt if provided
overrides: _ModelRequestOverrides = {"tools": tools}
if self.system_prompt:
- overrides["system_prompt"] = (
- request.system_prompt + "\n\n" + self.system_prompt
- if request.system_prompt
- else self.system_prompt
+ if request.system_message is not None:
+ new_system_content = [
+ *request.system_message.content_blocks,
+ {"type": "text", "text": f"\n\n{self.system_prompt}"},
+ ]
+ else:
+ new_system_content = [{"type": "text", "text": self.system_prompt}]
+ new_system_message = SystemMessage(
+ content=cast("list[str | dict[str, str]]", new_system_content)
)
+ overrides["system_message"] = new_system_message
return handler(request.override(**overrides))
@@ -299,11 +305,17 @@ class _StateClaudeFileToolMiddleware(AgentMiddleware):
# Inject system prompt if provided
overrides: _ModelRequestOverrides = {"tools": tools}
if self.system_prompt:
- overrides["system_prompt"] = (
- request.system_prompt + "\n\n" + self.system_prompt
- if request.system_prompt
- else self.system_prompt
+ if request.system_message is not None:
+ new_system_content = [
+ *request.system_message.content_blocks,
+ {"type": "text", "text": f"\n\n{self.system_prompt}"},
+ ]
+ else:
+ new_system_content = [{"type": "text", "text": self.system_prompt}]
+ new_system_message = SystemMessage(
+ content=cast("list[str | dict[str, str]]", new_system_content)
)
+ overrides["system_message"] = new_system_message
return await handler(request.override(**overrides))
@@ -751,11 +763,17 @@ class _FilesystemClaudeFileToolMiddleware(AgentMiddleware):
# Inject system prompt if provided
overrides: _ModelRequestOverrides = {"tools": tools}
if self.system_prompt:
- overrides["system_prompt"] = (
- request.system_prompt + "\n\n" + self.system_prompt
- if request.system_prompt
- else self.system_prompt
+ if request.system_message is not None:
+ new_system_content = [
+ *request.system_message.content_blocks,
+ {"type": "text", "text": f"\n\n{self.system_prompt}"},
+ ]
+ else:
+ new_system_content = [{"type": "text", "text": self.system_prompt}]
+ new_system_message = SystemMessage(
+ content=cast("list[str | dict[str, str]]", new_system_content)
)
+ overrides["system_message"] = new_system_message
return handler(request.override(**overrides))
@@ -775,11 +793,17 @@ class _FilesystemClaudeFileToolMiddleware(AgentMiddleware):
# Inject system prompt if provided
overrides: _ModelRequestOverrides = {"tools": tools}
if self.system_prompt:
- overrides["system_prompt"] = (
- request.system_prompt + "\n\n" + self.system_prompt
- if request.system_prompt
- else self.system_prompt
+ if request.system_message is not None:
+ new_system_content = [
+ *request.system_message.content_blocks,
+ {"type": "text", "text": f"\n\n{self.system_prompt}"},
+ ]
+ else:
+ new_system_content = [{"type": "text", "text": self.system_prompt}]
+ new_system_message = SystemMessage(
+ content=cast("list[str | dict[str, str]]", new_system_content)
)
+ overrides["system_message"] = new_system_message
return await handler(request.override(**overrides))
diff --git a/libs/partners/anthropic/langchain_anthropic/middleware/prompt_caching.py b/libs/partners/anthropic/langchain_anthropic/middleware/prompt_caching.py
index f32c130803..eb37d17837 100644
--- a/libs/partners/anthropic/langchain_anthropic/middleware/prompt_caching.py
+++ b/libs/partners/anthropic/langchain_anthropic/middleware/prompt_caching.py
@@ -89,7 +89,7 @@ class AnthropicPromptCachingMiddleware(AgentMiddleware):
messages_count = (
len(request.messages) + 1
- if request.system_prompt
+ if request.system_message
else len(request.messages)
)
return messages_count >= self.min_messages_to_cache
diff --git a/libs/partners/anthropic/tests/unit_tests/middleware/test_anthropic_tools.py b/libs/partners/anthropic/tests/unit_tests/middleware/test_anthropic_tools.py
index 85d824d93d..bd523d1726 100644
--- a/libs/partners/anthropic/tests/unit_tests/middleware/test_anthropic_tools.py
+++ b/libs/partners/anthropic/tests/unit_tests/middleware/test_anthropic_tools.py
@@ -1,7 +1,9 @@
"""Unit tests for Anthropic text editor and memory tool middleware."""
+from unittest.mock import MagicMock
+
import pytest
-from langchain_core.messages import ToolMessage
+from langchain_core.messages import SystemMessage, ToolMessage
from langgraph.types import Command
from langchain_anthropic.middleware.anthropic_tools import (
@@ -279,3 +281,171 @@ class TestFileOperations:
# New path has the file data
assert files.get("/memories/new.txt") is not None
assert files["/memories/new.txt"]["content"] == ["line1"]
+
+
+class TestSystemMessageHandling:
+ """Test system message handling in wrap_model_call."""
+
+ def test_text_editor_no_system_message(self) -> None:
+ """Test text editor middleware without system message."""
+ from langchain.agents.middleware.types import ModelRequest
+
+ middleware = StateClaudeTextEditorMiddleware()
+
+ request = ModelRequest(
+ model=MagicMock(),
+ messages=[],
+ system_message=None,
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={"messages": []},
+ runtime=MagicMock(),
+ )
+
+ captured_request = None
+
+ def handler(req: ModelRequest) -> MagicMock:
+ nonlocal captured_request
+ captured_request = req
+ return MagicMock()
+
+ middleware.wrap_model_call(request, handler)
+
+ # No system message should be added for text editor
+ assert captured_request is not None
+ assert captured_request.system_message is None
+
+ def test_memory_middleware_adds_system_message(self) -> None:
+ """Test memory middleware adds system message when none exists."""
+ from langchain.agents.middleware.types import ModelRequest
+
+ middleware = StateClaudeMemoryMiddleware()
+
+ request = ModelRequest(
+ model=MagicMock(),
+ messages=[],
+ system_message=None,
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={"messages": []},
+ runtime=MagicMock(),
+ )
+
+ captured_request = None
+
+ def handler(req: ModelRequest) -> MagicMock:
+ nonlocal captured_request
+ captured_request = req
+ return MagicMock()
+
+ middleware.wrap_model_call(request, handler)
+
+ # System message should be added
+ assert captured_request is not None
+ assert captured_request.system_message is not None
+ assert isinstance(captured_request.system_message, SystemMessage)
+ assert "MEMORY PROTOCOL" in captured_request.system_message.text
+
+ def test_memory_middleware_merges_system_message(self) -> None:
+ """Test memory middleware merges with existing system message."""
+ from langchain.agents.middleware.types import ModelRequest
+
+ middleware = StateClaudeMemoryMiddleware()
+
+ existing_message = SystemMessage("You are a helpful assistant.")
+ request = ModelRequest(
+ model=MagicMock(),
+ messages=[],
+ system_message=existing_message,
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={"messages": []},
+ runtime=MagicMock(),
+ )
+
+ captured_request = None
+
+ def handler(req: ModelRequest) -> MagicMock:
+ nonlocal captured_request
+ captured_request = req
+ return MagicMock()
+
+ middleware.wrap_model_call(request, handler)
+
+ # System message should be merged
+ assert captured_request is not None
+ assert captured_request.system_message is not None
+ assert isinstance(captured_request.system_message, SystemMessage)
+ assert "You are a helpful assistant." in captured_request.system_message.text
+ assert "MEMORY PROTOCOL" in captured_request.system_message.text
+
+ async def test_async_memory_middleware_merges_system_message(self) -> None:
+ """Test async memory middleware merges with existing system message."""
+ from langchain.agents.middleware.types import ModelRequest
+
+ middleware = StateClaudeMemoryMiddleware()
+
+ existing_message = SystemMessage("You are a helpful assistant.")
+ request = ModelRequest(
+ model=MagicMock(),
+ messages=[],
+ system_message=existing_message,
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={"messages": []},
+ runtime=MagicMock(),
+ )
+
+ captured_request = None
+
+ async def handler(req: ModelRequest) -> MagicMock:
+ nonlocal captured_request
+ captured_request = req
+ return MagicMock()
+
+ await middleware.awrap_model_call(request, handler)
+
+ # System message should be merged
+ assert captured_request is not None
+ assert captured_request.system_message is not None
+ assert isinstance(captured_request.system_message, SystemMessage)
+ assert "You are a helpful assistant." in captured_request.system_message.text
+ assert "MEMORY PROTOCOL" in captured_request.system_message.text
+
+ def test_custom_system_prompt_merges_correctly(self) -> None:
+ """Test custom system prompt merges with existing system message."""
+ from langchain.agents.middleware.types import ModelRequest
+
+ custom_prompt = "Custom instructions for memory tool."
+ middleware = StateClaudeMemoryMiddleware(system_prompt=custom_prompt)
+
+ existing_message = SystemMessage("Existing instructions.")
+ request = ModelRequest(
+ model=MagicMock(),
+ messages=[],
+ system_message=existing_message,
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ state={"messages": []},
+ runtime=MagicMock(),
+ )
+
+ captured_request = None
+
+ def handler(req: ModelRequest) -> MagicMock:
+ nonlocal captured_request
+ captured_request = req
+ return MagicMock()
+
+ middleware.wrap_model_call(request, handler)
+
+ # Both prompts should be in the final message
+ assert captured_request is not None
+ assert captured_request.system_message is not None
+ assert "Existing instructions." in captured_request.system_message.text
+ assert custom_prompt in captured_request.system_message.text