feat: Add configurable security policy support to Agent

This commit adds support for configurable security policies in the Agent class,
allowing users to customize the security guidelines included in the system prompt.

Key changes:
- Added security_policy_filename field to Agent class with default 'security_policy.j2'
- Updated system_prompt.j2 to use configurable security policy template
- Added comprehensive tests for the new functionality
- Created working example demonstrating usage

Files changed:
- openhands/sdk/agent/base.py: Added security_policy_filename field
- openhands/sdk/agent/prompts/system_prompt.j2: Updated to use configurable policy
- tests/sdk/agent/test_security_policy_integration.py: Added comprehensive tests
- examples/20_security_policy/configurable_security_policy.py: Working example
- examples/20_security_policy/custom_policy.j2: Example custom policy template

Co-authored-by: openhands <[email protected]>

Author: openhands-agent

examples/20_security_policy/configurable_security_policy.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+Example: Configurable Security Policy
+
+This example demonstrates how to use the security_policy_filename field
+to customize the security policy included in agent system prompts.
+
+The security policy is a critical component that defines what actions
+the agent is allowed to perform and under what conditions. By making
+it configurable, you can:
+
+1. Use different security policies for different environments
+2. Customize security rules for specific use cases
+3. Implement organization-specific security guidelines
+4. Test with relaxed or stricter security policies
+
+Usage:
+    python examples/20_security_policy/configurable_security_policy.py
+"""
+
+from pathlib import Path
+
+from pydantic import SecretStr
+
+from openhands.sdk import LLM
+from openhands.sdk.agent import Agent
+
+
+def setup_example_security_policy():
+    """Set up the example custom security policy template."""
+    # Get the path to the SDK prompts directory
+    current_dir = Path(__file__).parent
+    sdk_dir = current_dir.parent.parent / "openhands" / "sdk" / "agent" / "prompts"
+
+    # Read the example custom security policy
+    example_policy_path = current_dir / "custom_policy.j2"
+    target_policy_path = sdk_dir / "custom_policy.j2"
+
+    # Copy the example policy to the prompts directory if it doesn't exist
+    if not target_policy_path.exists():
+        with open(example_policy_path, "r") as f:
+            content = f.read()
+        with open(target_policy_path, "w") as f:
+            f.write(content)
+        print(f"Created example security policy at: {target_policy_path}")
+
+    return "custom_policy.j2"
+
+
+def main():
+    """Demonstrate configurable security policy functionality."""
+    print("=== Configurable Security Policy Example ===\n")
+
+    # Set up the example security policy
+    custom_policy_filename = setup_example_security_policy()
+
+    # Create LLM instance for testing
+    llm = LLM(model="test-model", api_key=SecretStr("test-key"), base_url="http://test")
+
+    # 1. Agent with default security policy
+    print("1. Agent with default security policy:")
+    default_agent = Agent(llm=llm)
+    print(f"   Security policy filename: {default_agent.security_policy_filename}")
+
+    # Extract security section from system message
+    system_message = default_agent.system_message
+    security_start = system_message.find("<SECURITY>")
+    security_end = system_message.find("</SECURITY>") + len("</SECURITY>")
+    security_section = system_message[security_start:security_end]
+
+    print("   Security section preview:")
+    print(f"   {security_section[:100]}...")
+    print()
+
+    # 2. Agent with custom security policy
+    print("2. Agent with custom security policy:")
+    custom_agent = Agent(llm=llm, security_policy_filename=custom_policy_filename)
+    print(f"   Security policy filename: {custom_agent.security_policy_filename}")
+
+    # Extract security section from system message
+    custom_system_message = custom_agent.system_message
+    custom_security_start = custom_system_message.find("<SECURITY>")
+    custom_security_end = custom_system_message.find("</SECURITY>") + len("</SECURITY>")
+    custom_security_section = custom_system_message[
+        custom_security_start:custom_security_end
+    ]
+
+    print("   Security section preview:")
+    print(f"   {custom_security_section[:100]}...")
+    print()
+
+    # 3. Demonstrate model_copy with different security policy
+    print("3. Using model_copy to change security policy:")
+    copied_agent = default_agent.model_copy(
+        update={"security_policy_filename": custom_policy_filename}
+    )
+    print(f"   Original agent: {default_agent.security_policy_filename}")
+    print(f"   Copied agent: {copied_agent.security_policy_filename}")
+    print()
+
+    # 4. Show that different policies produce different system messages
+    print("4. Verification that different policies produce different content:")
+    default_has_custom = "🔒 Example Custom Security Policy" in system_message
+    custom_has_custom = "🔒 Example Custom Security Policy" in custom_system_message
+
+    print(f"   Default agent has example custom policy content: {default_has_custom}")
+    print(f"   Custom agent has example custom policy content: {custom_has_custom}")
+
+    default_has_default = "🔐 Security Policy" in system_message
+    custom_has_default = "🔐 Security Policy" in custom_system_message
+
+    print(f"   Default agent has default policy content: {default_has_default}")
+    print(f"   Custom agent has default policy content: {custom_has_default}")
+
+    print("\n=== Example Complete ===")
+    print("\nKey takeaways:")
+    print(
+        "- The security_policy_filename field allows customization of security policies"
+    )
+    print("- Default value is 'security_policy.j2' for backward compatibility")
+    print("- Different security policies produce different system message content")
+    print(
+        "- You can use model_copy() to create agents with different security policies"
+    )
+    print("\nTo create your own security policy:")
+    print("1. Create a new .j2 template file in openhands/sdk/agent/prompts/")
+    print("2. Define your security rules and guidelines")
+    print("3. Pass the filename to the Agent constructor")
+
+
+if __name__ == "__main__":
+    main()

examples/20_security_policy/custom_policy.j2

@@ -0,0 +1,35 @@
+# 🔒 Example Custom Security Policy
+
+This is a custom security policy template created for demonstration purposes.
+It shows how you can create your own security policies for different use cases.
+
+## Custom Security Rules for Example
+
+### Allowed Actions
+- Read and analyze files in the current directory
+- Perform basic calculations and data processing
+- Generate reports and summaries
+- Create temporary files for processing
+
+### Restricted Actions
+- No network access to external services
+- No modification of system files
+- No execution of arbitrary shell commands
+- No access to sensitive environment variables
+
+### Special Guidelines for Examples
+- Always explain what actions are being taken
+- Provide clear reasoning for security decisions
+- Use safe, predictable operations only
+- Focus on educational value over functionality
+
+## Implementation Notes
+
+This custom policy is more restrictive than the default policy and is designed
+specifically for educational examples where safety and predictability are
+more important than full functionality.
+
+You can create your own security policies by:
+1. Creating a new .j2 template file
+2. Defining your specific security rules
+3. Referencing the template filename when creating agents

openhands/sdk/agent/base.py

@@ -109,6 +109,12 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         description="Optional kwargs to pass to the system prompt Jinja2 template.",
         examples=[{"cli_mode": True}],
     )
+    security_policy_filename: str = Field(
+        default="security_policy.j2",
+        description=(
+            "Filename of the security policy template to include in system prompt."
+        ),
+    )
     security_analyzer: analyzer.SecurityAnalyzerBase | None = Field(
         default=None,
         description="Optional security analyzer to evaluate action risks.",
@@ -156,6 +162,9 @@ def system_message(self) -> str:
         if hasattr(self, "cli_mode"):
             template_kwargs["cli_mode"] = getattr(self, "cli_mode")
 
+        # Add security_policy_filename to template kwargs
+        template_kwargs["security_policy_filename"] = self.security_policy_filename
+
         system_message = render_template(
             prompt_dir=self.prompt_dir,
             template_name=self.system_prompt_filename,

openhands/sdk/agent/prompts/system_prompt.j2

@@ -62,7 +62,7 @@ Your primary role is to assist users by executing commands, modifying code, and
 </PROBLEM_SOLVING_WORKFLOW>
 
 <SECURITY>
-{% include 'security_policy.j2' %}
+{% include security_policy_filename %}
 </SECURITY>
 
 <SECURITY_RISK_ASSESSMENT>

tests/sdk/agent/test_security_policy_integration.py

@@ -69,3 +69,92 @@ def test_security_policy_template_rendering():
     # Verify it's properly formatted (no extra whitespace at start/end)
     assert not security_policy.startswith(" ")
     assert not security_policy.endswith(" ")
+
+
+def test_configurable_security_policy_filename():
+    """Test that security policy filename can be configured."""
+    # First, set up the custom policy by copying from examples
+    import shutil
+    from pathlib import Path
+
+    current_dir = Path(__file__).parent
+    examples_dir = current_dir.parent.parent.parent / "examples" / "20_security_policy"
+    prompts_dir = (
+        current_dir.parent.parent.parent / "openhands" / "sdk" / "agent" / "prompts"
+    )
+
+    # Copy the example custom policy to prompts directory for testing
+    example_policy = examples_dir / "custom_policy.j2"
+    test_policy = prompts_dir / "custom_policy.j2"
+
+    if example_policy.exists():
+        shutil.copy(example_policy, test_policy)
+
+    try:
+        # Create agent with custom security policy filename
+        agent = Agent(
+            llm=LLM(
+                model="test-model",
+                api_key=SecretStr("test-key"),
+                base_url="http://test",
+            ),
+            security_policy_filename="custom_policy.j2",
+        )
+
+        # Get the system message
+        system_message = agent.system_message
+
+        # Verify that the custom security policy content is included
+        assert "🔒 Example Custom Security Policy" in system_message
+        assert "This is a custom security policy template" in system_message
+
+        # Verify that the default security policy content is NOT included
+        assert "🔐 Security Policy" not in system_message
+        assert "OK to do without Explicit User Consent" not in system_message
+    finally:
+        # Clean up the test file
+        if test_policy.exists():
+            test_policy.unlink()
+
+
+def test_default_security_policy_filename():
+    """Test that default security policy filename works correctly."""
+    # Create agent with default security policy filename
+    agent = Agent(
+        llm=LLM(
+            model="test-model", api_key=SecretStr("test-key"), base_url="http://test"
+        )
+    )
+
+    # Verify the default filename is set correctly
+    assert agent.security_policy_filename == "security_policy.j2"
+
+    # Get the system message
+    system_message = agent.system_message
+
+    # Verify that the default security policy content is included
+    assert "🔐 Security Policy" in system_message
+    assert "OK to do without Explicit User Consent" in system_message
+
+
+def test_security_policy_filename_field_access():
+    """Test that security_policy_filename field can be accessed and modified."""
+    # Create agent with custom security policy filename
+    agent = Agent(
+        llm=LLM(
+            model="test-model", api_key=SecretStr("test-key"), base_url="http://test"
+        ),
+        security_policy_filename="custom_security_policy.j2",
+    )
+
+    # Verify the field is accessible
+    assert agent.security_policy_filename == "custom_security_policy.j2"
+
+    # Test model_copy with different security policy filename
+    agent_copy = agent.model_copy(
+        update={"security_policy_filename": "security_policy.j2"}
+    )
+    assert agent_copy.security_policy_filename == "security_policy.j2"
+    assert (
+        agent.security_policy_filename == "custom_security_policy.j2"
+    )  # Original unchanged