feat: Add configurable security policy example

- Add example 20_configurable_security_policy.py demonstrating security policy customization
- Include example_custom_security_policy.j2 template for demonstration
- Show how to use security_policy_filename field with custom policies
- Demonstrate model_copy functionality with different security policies
- Provide educational content about creating custom security policies

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

Author: openhands-agent

examples/20_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_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 / "openhands" / "sdk" / "agent" / "prompts"
+
+    # Read the example custom security policy
+    example_policy_path = current_dir / "example_custom_security_policy.j2"
+    target_policy_path = sdk_dir / "example_custom_security_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 "example_custom_security_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/example_custom_security_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/prompts/example_custom_security_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