Skip to content

The agent engineering platform.

feat(langchain_v1): implement nicer devx for dynamic prompt (#33264)

Sydney Runkleacd1aa813c84
diff --git a/libs/langchain_v1/langchain/agents/middleware/__init__.py b/libs/langchain_v1/langchain/agents/middleware/__init__.py
index 89923b47f0..0222dba1f9 100644
--- a/libs/langchain_v1/langchain/agents/middleware/__init__.py
+++ b/libs/langchain_v1/langchain/agents/middleware/__init__.py
@@ -10,6 +10,7 @@ from .types import (
ModelRequest,
after_model,
before_model,
+ dynamic_prompt,
hook_config,
modify_model_request,
)
@@ -25,6 +26,7 @@ __all__ = [
"SummarizationMiddleware",
"after_model",
"before_model",
+ "dynamic_prompt",
"hook_config",
"modify_model_request",
]
diff --git a/libs/langchain_v1/langchain/agents/middleware/types.py b/libs/langchain_v1/langchain/agents/middleware/types.py
index d0328e1191..b3101ddb42 100644
--- a/libs/langchain_v1/langchain/agents/middleware/types.py
+++ b/libs/langchain_v1/langchain/agents/middleware/types.py
@@ -45,6 +45,7 @@ __all__ = [
"ModelRequest",
"OmitFromSchema",
"PublicAgentState",
+ "dynamic_prompt",
"hook_config",
]
@@ -180,6 +181,16 @@ class _CallableWithModelRequestAndStateAndRuntime(Protocol[StateT_contra, Contex
...
+class _CallableReturningPromptString(Protocol[StateT_contra, ContextT]):
+ """Callable that returns a prompt string given ModelRequest, AgentState, and Runtime."""
+
+ def __call__(
+ self, request: ModelRequest, state: StateT_contra, runtime: Runtime[ContextT]
+ ) -> str | Awaitable[str]:
+ """Generate a system prompt string based on the request, state, and runtime."""
+ ...
+
+
CallableT = TypeVar("CallableT", bound=Callable[..., Any])
@@ -639,3 +650,126 @@ def after_model(
if func is not None:
return decorator(func)
return decorator
+
+
+@overload
+def dynamic_prompt(
+ func: _CallableReturningPromptString[StateT, ContextT],
+) -> AgentMiddleware[StateT, ContextT]: ...
+
+
+@overload
+def dynamic_prompt(
+ func: None = None,
+) -> Callable[
+ [_CallableReturningPromptString[StateT, ContextT]],
+ AgentMiddleware[StateT, ContextT],
+]: ...
+
+
+def dynamic_prompt(
+ func: _CallableReturningPromptString[StateT, ContextT] | None = None,
+) -> (
+ Callable[
+ [_CallableReturningPromptString[StateT, ContextT]],
+ AgentMiddleware[StateT, ContextT],
+ ]
+ | AgentMiddleware[StateT, ContextT]
+):
+ """Decorator used to dynamically generate system prompts for the model.
+
+ This is a convenience decorator that creates middleware using `modify_model_request`
+ specifically for dynamic prompt generation. The decorated function should return
+ a string that will be set as the system prompt for the model request.
+
+ Args:
+ func: The function to be decorated. Must accept:
+ `request: ModelRequest, state: StateT, runtime: Runtime[ContextT]` -
+ Model request, state, and runtime context
+
+ Returns:
+ Either an AgentMiddleware instance (if func is provided) or a decorator function
+ that can be applied to a function.
+
+ The decorated function should return:
+ - `str` - The system prompt to use for the model request
+
+ Examples:
+ Basic usage with dynamic content:
+ ```python
+ @dynamic_prompt
+ def my_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ user_name = runtime.context.get("user_name", "User")
+ return f"You are a helpful assistant helping {user_name}."
+ ```
+
+ Using state to customize the prompt:
+ ```python
+ @dynamic_prompt
+ def context_aware_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ msg_count = len(state["messages"])
+ if msg_count > 10:
+ return "You are in a long conversation. Be concise."
+ return "You are a helpful assistant."
+ ```
+
+ Using with agent:
+ ```python
+ agent = create_agent(model, middleware=[my_prompt])
+ ```
+ """
+
+ def decorator(
+ func: _CallableReturningPromptString[StateT, ContextT],
+ ) -> AgentMiddleware[StateT, ContextT]:
+ is_async = iscoroutinefunction(func)
+
+ if is_async:
+
+ async def async_wrapped(
+ self: AgentMiddleware[StateT, ContextT], # noqa: ARG001
+ request: ModelRequest,
+ state: StateT,
+ runtime: Runtime[ContextT],
+ ) -> ModelRequest:
+ prompt = await func(request, state, runtime) # type: ignore[misc]
+ request.system_prompt = prompt
+ return request
+
+ middleware_name = cast("str", getattr(func, "__name__", "DynamicPromptMiddleware"))
+
+ return type(
+ middleware_name,
+ (AgentMiddleware,),
+ {
+ "state_schema": AgentState,
+ "tools": [],
+ "amodify_model_request": async_wrapped,
+ },
+ )()
+
+ def wrapped(
+ self: AgentMiddleware[StateT, ContextT], # noqa: ARG001
+ request: ModelRequest,
+ state: StateT,
+ runtime: Runtime[ContextT],
+ ) -> ModelRequest:
+ prompt = cast("str", func(request, state, runtime))
+ request.system_prompt = prompt
+ return request
+
+ middleware_name = cast("str", getattr(func, "__name__", "DynamicPromptMiddleware"))
+
+ return type(
+ middleware_name,
+ (AgentMiddleware,),
+ {
+ "state_schema": AgentState,
+ "tools": [],
+ "modify_model_request": wrapped,
+ },
+ )()
+
+ if func is not None:
+ return decorator(func)
+ return decorator
diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_middleware_decorators.py b/libs/langchain_v1/tests/unit_tests/agents/test_middleware_decorators.py
index 535bd9bfae..536d5fdc6e 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/test_middleware_decorators.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/test_middleware_decorators.py
@@ -16,6 +16,7 @@ from langchain.agents.middleware.types import (
ModelRequest,
before_model,
after_model,
+ dynamic_prompt,
modify_model_request,
hook_config,
)
@@ -572,3 +573,145 @@ def test_async_middleware_with_can_jump_to_graph_snapshot(snapshot: SnapshotAsse
)
assert agent_mixed.compile().get_graph().draw_mermaid() == snapshot
+
+
+def test_dynamic_prompt_decorator() -> None:
+ """Test dynamic_prompt decorator with basic usage."""
+
+ @dynamic_prompt
+ def my_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ return "Dynamic test prompt"
+
+ assert isinstance(my_prompt, AgentMiddleware)
+ assert my_prompt.state_schema == AgentState
+ assert my_prompt.tools == []
+ assert my_prompt.__class__.__name__ == "my_prompt"
+
+ # Verify it modifies the request correctly
+ original_request = ModelRequest(
+ model="test-model",
+ system_prompt="Original",
+ messages=[HumanMessage("Hello")],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ )
+ result = my_prompt.modify_model_request(
+ original_request, {"messages": [HumanMessage("Hello")]}, None
+ )
+ assert result.system_prompt == "Dynamic test prompt"
+
+
+def test_dynamic_prompt_uses_state() -> None:
+ """Test that dynamic_prompt can use state information."""
+
+ @dynamic_prompt
+ def custom_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ msg_count = len(state["messages"])
+ return f"Prompt with {msg_count} messages"
+
+ # Verify it uses state correctly
+ original_request = ModelRequest(
+ model="test-model",
+ system_prompt="Original",
+ messages=[HumanMessage("Hello")],
+ tool_choice=None,
+ tools=[],
+ response_format=None,
+ )
+ result = custom_prompt.modify_model_request(
+ original_request, {"messages": [HumanMessage("Hello"), HumanMessage("World")]}, None
+ )
+ assert result.system_prompt == "Prompt with 2 messages"
+
+
+def test_dynamic_prompt_integration() -> None:
+ """Test dynamic_prompt decorator in a full agent."""
+
+ prompt_calls = 0
+
+ @dynamic_prompt
+ def context_aware_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ nonlocal prompt_calls
+ prompt_calls += 1
+ return f"you are a helpful assistant."
+
+ agent = create_agent(model=FakeToolCallingModel(), middleware=[context_aware_prompt])
+ agent = agent.compile()
+
+ result = agent.invoke({"messages": [HumanMessage("Hello")]})
+
+ assert prompt_calls == 1
+ assert result["messages"][-1].content == "you are a helpful assistant.-Hello"
+
+
+async def test_async_dynamic_prompt_decorator() -> None:
+ """Test dynamic_prompt decorator with async function."""
+
+ @dynamic_prompt
+ async def async_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ return "Async dynamic prompt"
+
+ assert isinstance(async_prompt, AgentMiddleware)
+ assert async_prompt.state_schema == AgentState
+ assert async_prompt.tools == []
+ assert async_prompt.__class__.__name__ == "async_prompt"
+
+
+async def test_async_dynamic_prompt_integration() -> None:
+ """Test async dynamic_prompt decorator in a full agent."""
+
+ prompt_calls = 0
+
+ @dynamic_prompt
+ async def async_context_prompt(
+ request: ModelRequest, state: AgentState, runtime: Runtime
+ ) -> str:
+ nonlocal prompt_calls
+ prompt_calls += 1
+ return f"Async assistant."
+
+ agent = create_agent(model=FakeToolCallingModel(), middleware=[async_context_prompt])
+ agent = agent.compile()
+
+ result = await agent.ainvoke({"messages": [HumanMessage("Hello")]})
+ assert prompt_calls == 1
+ assert result["messages"][-1].content == "Async assistant.-Hello"
+
+
+def test_dynamic_prompt_overwrites_system_prompt() -> None:
+ """Test that dynamic_prompt overwrites the original system_prompt."""
+
+ @dynamic_prompt
+ def override_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ return "Overridden prompt."
+
+ agent = create_agent(
+ model=FakeToolCallingModel(),
+ system_prompt="Original static prompt",
+ middleware=[override_prompt],
+ )
+ agent = agent.compile()
+
+ result = agent.invoke({"messages": [HumanMessage("Hello")]})
+ assert result["messages"][-1].content == "Overridden prompt.-Hello"
+
+
+def test_dynamic_prompt_multiple_in_sequence() -> None:
+ """Test multiple dynamic_prompt decorators in sequence (last wins)."""
+
+ @dynamic_prompt
+ def first_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ return "First prompt."
+
+ @dynamic_prompt
+ def second_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
+ return "Second prompt."
+
+ # When used together, the last middleware in the list should win
+ # since they're both modify_model_request hooks executed in sequence
+ agent = create_agent(model=FakeToolCallingModel(), middleware=[first_prompt, second_prompt])
+ agent = agent.compile()
+
+ result = agent.invoke({"messages": [HumanMessage("Hello")]})
+ assert result["messages"][-1].content == "Second prompt.-Hello"