feat(sdk): accept inline system_prompt kwarg on Agent (#2826)

Co-authored-by: openhands <openhands@all-hands.dev>

Author: xingyaoww

openhands-sdk/openhands/sdk/agent/agent.py

@@ -243,8 +243,16 @@ class Agent(CriticMixin, AgentBase):
     Attributes:
         llm: The language model instance used for reasoning.
         tools: List of tools available to the agent.
-        name: Optional agent identifier.
-        system_prompt: Custom system prompt (uses default if not provided).
+        system_prompt: Inline system prompt string. When provided the agent
+            uses this text verbatim instead of rendering from a template.
+            Mutually exclusive with a non-default ``system_prompt_filename``.
+            **Not recommended** unless you know what you are doing (e.g.
+            customising agent behaviour for a completely different task) —
+            this will override OpenHands' built-in system instructions.
+        system_prompt_filename: Jinja2 template filename resolved relative to
+            the agent's prompts directory, or an absolute path. Defaults to
+            ``"system_prompt.j2"``.
+        system_prompt_kwargs: Extra kwargs forwarded to the Jinja2 template.
 
     Example:
         ```python
@@ -255,6 +263,14 @@ class Agent(CriticMixin, AgentBase):
         tools = [Tool(name="TerminalTool"), Tool(name="FileEditorTool")]
         agent = Agent(llm=llm, tools=tools)
         ```
+
+        To override the system prompt entirely::
+
+            agent = Agent(
+                llm=llm,
+                tools=tools,
+                system_prompt="You are a helpful coding assistant.",
+            )
     """
 
     _parallel_executor: ParallelToolExecutor = PrivateAttr(

openhands-sdk/openhands/sdk/agent/base.py

@@ -13,6 +13,7 @@
     ConfigDict,
     Field,
     PrivateAttr,
+    model_validator,
 )
 
 from openhands.sdk.context.agent_context import AgentContext
@@ -135,6 +136,19 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             }
         ],
     )
+    system_prompt: str | None = Field(
+        default=None,
+        description=(
+            "Inline system prompt string.  When provided, the agent uses this "
+            "text verbatim as the system message instead of rendering from "
+            "`system_prompt_filename`.  Mutually exclusive with a non-default "
+            "`system_prompt_filename`.\n\n"
+            "**Warning**: This is not recommended unless you know what you are "
+            "doing (e.g. customising agent behaviour for a completely different "
+            "task).  Setting this will override OpenHands' built-in system "
+            "instructions that govern default agent behaviour."
+        ),
+    )
     system_prompt_filename: str = Field(
         default="system_prompt.j2",
         description=(
@@ -159,6 +173,23 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         examples=[{"cli_mode": True}],
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def _validate_system_prompt_fields(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        has_inline = data.get("system_prompt") is not None
+        has_custom_filename = (
+            "system_prompt_filename" in data
+            and data["system_prompt_filename"] != "system_prompt.j2"
+        )
+        if has_inline and has_custom_filename:
+            raise ValueError(
+                "Cannot set both 'system_prompt' and a non-default "
+                "'system_prompt_filename'. Use one or the other."
+            )
+        return data
+
     condenser: CondenserBase | None = Field(
         default=None,
         description="Optional condenser to use for condensing conversation history.",
@@ -223,9 +254,15 @@ def static_system_message(self) -> str:
         per-conversation context. This static portion can be cached and reused
         across conversations for better prompt caching efficiency.
 
+        When ``system_prompt`` is set, that string is returned verbatim,
+        bypassing Jinja2 template rendering entirely.
+
         Returns:
             The rendered system prompt template without dynamic context.
         """
+        if self.system_prompt is not None:
+            return self.system_prompt
+
         template_kwargs = dict(self.system_prompt_kwargs)
         # Auto-detect browser tools from the tool spec list
         template_kwargs.setdefault(

tests/sdk/agent/test_system_prompt.py

@@ -0,0 +1,86 @@
+"""Tests for the system_prompt inline override on Agent / AgentBase."""
+
+from __future__ import annotations
+
+import pytest
+
+from openhands.sdk.agent import Agent
+from openhands.sdk.agent.base import AgentBase
+from openhands.sdk.llm import LLM
+
+
+def _make_llm() -> LLM:
+    return LLM(model="test-model", usage_id="test")
+
+
+# --- construction ---
+
+
+def test_system_prompt_is_accepted_and_stored() -> None:
+    agent = Agent(llm=_make_llm(), tools=[], system_prompt="CUSTOM")
+    assert agent.system_prompt == "CUSTOM"
+
+
+def test_system_prompt_defaults_to_none() -> None:
+    agent = Agent(llm=_make_llm(), tools=[])
+    assert agent.system_prompt is None
+
+
+# --- static_system_message uses inline prompt ---
+
+
+def test_static_system_message_returns_inline_prompt() -> None:
+    agent = Agent(llm=_make_llm(), tools=[], system_prompt="MY PROMPT")
+    assert agent.static_system_message == "MY PROMPT"
+
+
+def test_static_system_message_falls_back_to_template_when_none() -> None:
+    agent = Agent(llm=_make_llm(), tools=[])
+    # The default template renders a non-empty string
+    assert len(agent.static_system_message) > 0
+    assert agent.static_system_message != ""
+
+
+# --- mutual-exclusivity validation ---
+
+
+def test_system_prompt_and_custom_filename_are_mutually_exclusive() -> None:
+    with pytest.raises(ValueError, match="Cannot set both"):
+        Agent(
+            llm=_make_llm(),
+            tools=[],
+            system_prompt="inline",
+            system_prompt_filename="custom.j2",
+        )
+
+
+def test_system_prompt_with_default_filename_is_ok() -> None:
+    """system_prompt + the default filename should be accepted."""
+    agent = Agent(
+        llm=_make_llm(),
+        tools=[],
+        system_prompt="inline",
+        system_prompt_filename="system_prompt.j2",
+    )
+    assert agent.system_prompt == "inline"
+    assert agent.static_system_message == "inline"
+
+
+# --- serialization round-trip ---
+
+
+def test_system_prompt_survives_json_round_trip() -> None:
+    agent = Agent(llm=_make_llm(), tools=[], system_prompt="ROUND TRIP")
+    agent_json = agent.model_dump_json()
+    restored = AgentBase.model_validate_json(agent_json)
+    assert isinstance(restored, Agent)
+    assert restored.system_prompt == "ROUND TRIP"
+    assert restored.static_system_message == "ROUND TRIP"
+
+
+def test_system_prompt_none_survives_json_round_trip() -> None:
+    agent = Agent(llm=_make_llm(), tools=[])
+    agent_json = agent.model_dump_json()
+    restored = AgentBase.model_validate_json(agent_json)
+    assert isinstance(restored, Agent)
+    assert restored.system_prompt is None