Support input-rendered coded DeepAgent prompts

Author: andreitava-uip

samples/coded-deepagent/README.md

@@ -13,6 +13,7 @@ bucket backend.
 ## What It Shows
 
 - Typed coded-agent input and output with Pydantic models.
+- System and user prompts rendered from typed input.
 - A standard LangChain tool used by the main DeepAgent.
 - A DeepAgents subagent used for risk review.
 - Runtime-provided workspace persistence through the UiPath contract.

samples/coded-deepagent/graph.py

@@ -55,12 +55,16 @@ def score_launch_readiness(audience: str, constraints: list[str]) -> str:
     "model": MODEL,
 }
 
-SYSTEM_PROMPT = """You are a product launch planning agent.
+
+def build_system_prompt(args: dict) -> str:
+    return f"""You are a product launch planning agent for {args["product_name"]}.
 
 Use the planning tools provided by DeepAgents. Use score_launch_readiness to get
 a deterministic readiness signal. Delegate a plan review to risk_reviewer before
 finalizing the answer.
 
+Tailor all planning to this audience: {args["audience"]}.
+
 The UiPath runtime provides your DeepAgents filesystem through the tagged graph
 contract. Write these workspace files before producing the final answer:
 - /launch/brief.md with the final launch brief
@@ -70,7 +74,7 @@ def score_launch_readiness(audience: str, constraints: list[str]) -> str:
 you wrote in workspace_files."""
 
 
-def build_user_message(args: dict) -> str:
+def build_user_prompt(args: dict) -> str:
     constraints = args.get("constraints") or []
     constraint_lines = "\n".join(f"- {item}" for item in constraints) or "- None"
     return f"""Create a launch brief.
@@ -87,8 +91,8 @@ def build_user_message(args: dict) -> str:
     model=MODEL,
     input_schema=BriefInput,
     output_schema=BriefOutput,
-    system_prompt=SYSTEM_PROMPT,
+    system_prompt=build_system_prompt,
+    user_prompt=build_user_prompt,
     tools=[score_launch_readiness],
     subagents=[RISK_REVIEWER],
-    build_user_message=build_user_message,
 )

src/uipath_langchain/agent/advanced/agent.py

@@ -9,7 +9,7 @@
 from deepagents.backends.protocol import BackendFactory
 from langchain.agents.structured_output import ResponseFormat
 from langchain_core.language_models import BaseChatModel
-from langchain_core.messages import HumanMessage
+from langchain_core.messages import HumanMessage, SystemMessage
 from langchain_core.runnables.config import RunnableConfig
 from langchain_core.tools import BaseTool
 from langgraph.graph import END, START
@@ -63,6 +63,7 @@ def create_advanced_agent_graph(
     input_schema: type[BaseModel] | None,
     output_schema: type[BaseModel],
     build_user_message: Callable[[dict[str, Any]], str],
+    build_system_message: Callable[[dict[str, Any]], str] | None = None,
     subagents: Sequence[SubAgent | CompiledSubAgent] = (),
 ) -> StateGraph[Any, Any, Any, Any]:
     """Wrap the advanced agent in a parent graph that maps typed I/O to/from messages.
@@ -112,8 +113,14 @@ async def transform_input_async(
                 state=state,
                 config=config,
             )
+        messages = []
+        if build_system_message is not None:
+            system_text = build_system_message(input_args)
+            if system_text:
+                messages.append(SystemMessage(content=system_text, id="system-input"))
         user_text = build_user_message(input_args)
-        return {"messages": [HumanMessage(content=user_text, id="user-input")]}
+        messages.append(HumanMessage(content=user_text, id="user-input"))
+        return {"messages": messages}
 
     def transform_output(state: BaseModel) -> dict[str, Any]:
         structured = getattr(state, "structured_response", {})

src/uipath_langchain/deepagents/__init__.py

@@ -2,6 +2,7 @@
 
 from .agent import (
     UiPathDeepAgent,
+    UiPathDeepAgentPrompt,
     create_uipath_deep_agent,
     create_uipath_deep_agent_graph,
 )
@@ -16,6 +17,7 @@
 __all__ = [
     "UiPathDeepAgent",
     "UiPathDeepAgentHydrationPolicy",
+    "UiPathDeepAgentPrompt",
     "UiPathDeepAgentRuntimeSpec",
     "create_uipath_deep_agent",
     "create_uipath_deep_agent_graph",

src/uipath_langchain/deepagents/agent.py

@@ -24,6 +24,8 @@
     set_uipath_deep_agent_runtime_spec,
 )
 
+UiPathDeepAgentPrompt = str | Callable[[dict[str, Any]], str]
+
 
 @dataclass(frozen=True)
 class UiPathDeepAgent:
@@ -38,7 +40,8 @@ def create_uipath_deep_agent(
     model: BaseChatModel,
     input_schema: type[BaseModel] | None = None,
     output_schema: type[BaseModel],
-    system_prompt: str = "",
+    system_prompt: UiPathDeepAgentPrompt = "",
+    user_prompt: UiPathDeepAgentPrompt | None = None,
     tools: Sequence[BaseTool] = (),
     subagents: Sequence[SubAgent | CompiledSubAgent] = (),
     backend: BackendProtocol | BackendFactory | None = None,
@@ -60,6 +63,7 @@ def create_uipath_deep_agent(
         input_schema=input_schema,
         output_schema=output_schema,
         system_prompt=system_prompt,
+        user_prompt=user_prompt,
         tools=tools,
         subagents=subagents,
         backend=backend,
@@ -85,7 +89,8 @@ def create_uipath_deep_agent_graph(
     model: BaseChatModel,
     input_schema: type[BaseModel] | None = None,
     output_schema: type[BaseModel],
-    system_prompt: str = "",
+    system_prompt: UiPathDeepAgentPrompt = "",
+    user_prompt: UiPathDeepAgentPrompt | None = None,
     tools: Sequence[BaseTool] = (),
     subagents: Sequence[SubAgent | CompiledSubAgent] = (),
     backend: BackendProtocol | BackendFactory | None = None,
@@ -112,18 +117,27 @@ def create_uipath_deep_agent_graph(
         workspace_config_key=workspace_config_key,
     )
     response_format = response_format or ToolStrategy(output_schema)
-    build_user_message = build_user_message or _default_user_message
+    if user_prompt is not None and build_user_message is not None:
+        raise ValueError("Use either user_prompt or build_user_message, not both.")
+
+    static_system_prompt, build_system_message = _split_system_prompt(system_prompt)
+    build_user_message = (
+        _coerce_prompt_renderer(user_prompt)
+        if user_prompt is not None
+        else build_user_message or _default_user_message
+    )
 
     graph = create_advanced_agent_graph(
         model=model,
         tools=tools,
         subagents=subagents,
-        system_prompt=system_prompt,
+        system_prompt=static_system_prompt,
         backend=backend,
         response_format=response_format,
         input_schema=input_schema,
         output_schema=output_schema,
         build_user_message=build_user_message,
+        build_system_message=build_system_message,
     )
     set_uipath_deep_agent_runtime_spec(
         graph,
@@ -137,6 +151,22 @@ def create_uipath_deep_agent_graph(
     return graph
 
 
+def _split_system_prompt(
+    system_prompt: UiPathDeepAgentPrompt,
+) -> tuple[str, Callable[[dict[str, Any]], str] | None]:
+    if callable(system_prompt):
+        return "", system_prompt
+    return system_prompt, None
+
+
+def _coerce_prompt_renderer(
+    prompt: UiPathDeepAgentPrompt,
+) -> Callable[[dict[str, Any]], str]:
+    if callable(prompt):
+        return prompt
+    return lambda _args: prompt
+
+
 def _default_user_message(args: dict[str, Any]) -> str:
     if not args:
         return ""

tests/agent/advanced/test_create_advanced_agent_graph.py

@@ -5,7 +5,7 @@
 
 import pytest
 from langchain_core.language_models import BaseChatModel
-from langchain_core.messages import HumanMessage
+from langchain_core.messages import HumanMessage, SystemMessage
 from pydantic import BaseModel, ConfigDict, Field
 
 from uipath_langchain.agent.advanced.agent import create_advanced_agent_graph
@@ -86,6 +86,41 @@ async def test_transform_input_without_schema_builds_single_user_message() -> No
     assert message.id == "user-input"
 
 
+@pytest.mark.asyncio
+async def test_transform_input_includes_dynamic_system_message() -> None:
+    """Runtime input can render a system message before the user message."""
+    graph = _build(
+        input_schema=_Input,
+        build_system_message=lambda args: f"system:{args['question']}",
+        build_user_message=lambda args: f"user:{args['question']}",
+    )
+    state_cls = create_state_with_input(_Input)
+    state = state_cls(question="q")
+
+    out = await graph.nodes["transform_input"].runnable.ainvoke(state)
+
+    system_message, user_message = out["messages"]
+    assert isinstance(system_message, SystemMessage)
+    assert system_message.content == "system:q"
+    assert system_message.id == "system-input"
+    assert isinstance(user_message, HumanMessage)
+    assert user_message.content == "user:q"
+    assert user_message.id == "user-input"
+
+
+@pytest.mark.asyncio
+async def test_transform_input_omits_empty_dynamic_system_message() -> None:
+    """An empty rendered system prompt does not create a blank message."""
+    graph = _build(build_system_message=lambda _args: "")
+
+    out = await graph.nodes["transform_input"].runnable.ainvoke(
+        AdvancedAgentGraphState()
+    )
+
+    assert len(out["messages"]) == 1
+    assert isinstance(out["messages"][0], HumanMessage)
+
+
 @pytest.mark.asyncio
 async def test_transform_input_resolves_attachments_when_present() -> None:
     """With an input schema and attachment paths, input attachments are resolved first."""

tests/deepagents/test_metadata.py

@@ -91,3 +91,46 @@ def test_subagents_are_forwarded_to_advanced_agent_graph() -> None:
         )
 
     assert mock_create.call_args.kwargs["subagents"] == [subagent]
+
+
+def test_dynamic_system_prompt_is_forwarded_as_runtime_renderer() -> None:
+    def build_system_prompt(args: dict[str, str]) -> str:
+        return f"System for {args['topic']}"
+
+    with patch(
+        "uipath_langchain.deepagents.agent.create_advanced_agent_graph",
+        return_value=_graph(),
+    ) as mock_create:
+        create_uipath_deep_agent_graph(
+            model=object(),  # type: ignore[arg-type]
+            output_schema=Output,
+            system_prompt=build_system_prompt,
+        )
+
+    assert mock_create.call_args.kwargs["system_prompt"] == ""
+    assert mock_create.call_args.kwargs["build_system_message"] is build_system_prompt
+
+
+def test_static_user_prompt_is_forwarded_as_user_renderer() -> None:
+    with patch(
+        "uipath_langchain.deepagents.agent.create_advanced_agent_graph",
+        return_value=_graph(),
+    ) as mock_create:
+        create_uipath_deep_agent_graph(
+            model=object(),  # type: ignore[arg-type]
+            output_schema=Output,
+            user_prompt="Create the brief.",
+        )
+
+    build_user_message = mock_create.call_args.kwargs["build_user_message"]
+    assert build_user_message({}) == "Create the brief."
+
+
+def test_user_prompt_and_build_user_message_are_mutually_exclusive() -> None:
+    with pytest.raises(ValueError, match="either user_prompt or build_user_message"):
+        create_uipath_deep_agent_graph(
+            model=object(),  # type: ignore[arg-type]
+            output_schema=Output,
+            user_prompt="Create the brief.",
+            build_user_message=lambda _args: "Create the brief.",
+        )