feat: Add dynamic system prompt override functionality

[Shubhamraut01]

System Prompt Override Implementation - Resolves Issue #103

Description

This PR implements the system prompt override functionality requested in issue #103, allowing users to dynamically override the system prompt on a per-call basis when invoking an agent. The implementation preserves backward compatibility while enabling powerful new use cases for dynamic prompt management.

Key Changes:

• Modified Agent._execute_event_loop_cycle() to extract system_prompt from kwargs with fallback to instance value
• Replaced problematic kwargs.pop("system_prompt", None) behavior that ignored user overrides
• Added comprehensive test coverage for all system prompt override scenarios
• Consolidated related tests for better maintainability

Before:

# system_prompt parameter was ignored
agent = Agent(system_prompt="Default prompt")
response = agent("Hello", system_prompt="Custom prompt")  # ❌ Ignored

After:

# system_prompt parameter works as expected
agent = Agent(system_prompt="Default prompt")
response = agent("Hello", system_prompt="Custom prompt")  # ✅ Works!

Related Issues

Fixes #103 - [BUG] Agent.call() removes kwargs preventing dynamic system_prompt override

Documentation PR

N/A - This is a bug fix with enhanced functionality, no separate documentation changes required.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

This change is both a bug fix (resolving the ignored kwargs) and a new feature (enabling dynamic system prompt override functionality).

Testing

Automated Testing

• hatch fmt --linter - ✅ All linting checks pass
• hatch fmt --formatter - ✅ Code formatting verified
• hatch test --all - ✅ Full test suite passes
• Verified that the changes do not break functionality or introduce warnings in consuming repositories

Implementation Testing

Test Coverage includes:

1. Default system prompt behavior - Uses instance system_prompt when no override provided
2. Per-call override - Successfully overrides system_prompt for specific calls
3. Revert behavior - Returns to default system_prompt after override
4. Multiple overrides - Handles consecutive different overrides correctly
5. None override - Properly handles system_prompt=None parameter
6. Empty string override - Correctly processes system_prompt="" parameter
7. No default prompt - Works when agent has no default system_prompt set

Test Results:

# Comprehensive system prompt override test
$ python -m pytest tests/strands/agent/test_agent.py -k "test_agent_system_prompt_overrides_all_cases" -v
================= test session starts ==================
collected 36 items / 35 deselected / 1 selected        
tests/strands/agent/test_agent.py::test_agent_system_prompt_overrides_all_cases PASSED [100%]
===== 1 passed, 35 deselected in 0.92s =====

# Full test suite validation
$ hatch test
================================ All tests pass ✅ ================================

Manual Testing Examples

from strands import Agent
from strands.models.openai import OpenAIModel

# Initialize agent with default system prompt
agent = Agent(
    model=OpenAIModel(), 
    system_prompt="You are a helpful assistant."
)

# 1. Use default system prompt
response1 = agent("Hello")

# 2. Override system prompt for specific interaction
response2 = agent("Analyze this code", system_prompt="You are a senior code reviewer.")

# 3. Use different prompt for creative tasks
response3 = agent("Write a poem", system_prompt="You are a creative poet.")

# 4. Revert to default (no override specified)
response4 = agent("Help me with math")

Real-World Use Cases Enabled

1. Multi-purpose agents - Single agent instance with different expertise per interaction
2. Dynamic context injection - System prompts that include conversation history or context
3. CLI tools - Command-line interfaces that modify behavior based on flags/options
4. Testing scenarios - Evaluation of different prompts without creating new agent instances
5. Conversation management - Adaptive prompts based on conversation state

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Technical Implementation Details

Core Changes in src/strands/agent/agent.py

Before (Problematic):

def _execute_event_loop_cycle(self, callback_handler: Callable, kwargs: dict[str, Any]) -> AgentResult:
    # ... docstring ...
    kwargs.pop("agent", None)
    kwargs.pop("model", None)
    kwargs.pop("system_prompt", None)  # ❌ This ignored user overrides
    kwargs.pop("tool_execution_handler", None)
    # ... rest of method uses self.system_prompt instead

After (Fixed):

def _execute_event_loop_cycle(self, callback_handler: Callable, kwargs: dict[str, Any]) -> AgentResult:
    # ... docstring ...
    # Extract parameters with fallbacks to instance values
    system_prompt = kwargs.pop("system_prompt", self.system_prompt)  # ✅ Respects user override
    model = kwargs.pop("model", self.model)
    tool_execution_handler = kwargs.pop("tool_execution_handler", self.thread_pool_wrapper)
    # ... rest of method uses extracted system_prompt value

Test Implementation

Added comprehensive test function test_agent_system_prompt_overrides_all_cases() in tests/strands/agent/test_agent.py:

def test_agent_system_prompt_overrides_all_cases():
    """Test all system prompt override scenarios in one function."""
    
    class MockModel(Model):
        def __init__(self):
            self.captured_system_prompts = []
        
        def converse(self, messages, tools=None, system_prompt=None, **kwargs):
            self.captured_system_prompts.append(system_prompt)
            # ... mock implementation
    
    # Test all 7 scenarios with proper verification

Backward Compatibility

This change is 100% backward compatible:

• Existing code continues to work exactly as before
• No changes to method signatures or public APIs
• Default behavior unchanged when no override is provided
• All existing tests pass without modification

Performance Impact

• Positive impact: Eliminates need to create new agent instances for different prompts
• Negligible overhead: Simple parameter extraction with fallback pattern
• Memory efficiency: Reuses single agent instance across different prompt scenarios

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[awsarron]

Hi @Shubhamraut01, thank you for your contribution!

A couple of comments on the changes. Please also use the pull request template as it includes some extra useful details about clarifying how the changes have been tested, along with some other information.

[Shubhamraut01]

Hello,
Thanks for reviewing my PR.
I have done the needful.

[awsarron]

Thank you for the updates @Shubhamraut01.

A couple of small comments and then we'll get this merged 🚀

[cagataycali]

looks great to me!

Thank you for your contribution and making your first contribution! 🚀

[Shubhamraut01]

You're welcome — glad to be part of it! Excited for more contributions ahead! 🚀

[Shubhamraut01]

@awsarron I think it looks good now.

[awsarron]

Last couple of nits and then we'll merge this. Thank you so much @Shubhamraut01 !

Works great, I gave it a test locally as well ☺️

[Shubhamraut01]

Last couple of nits and then we'll merge this. Thank you so much @Shubhamraut01 !

Works great, I gave it a test locally as well ☺️

Welcome @awsarron,

Sounds Good. I have done the final changes.

[awsarron]

Awesome, thank you @Shubhamraut01. We'll get these improvements published in the next SDK release 🚀

[Shubhamraut01]

Awesome, thank you @Shubhamraut01. We'll get these improvements published in the next SDK release 🚀

Thank you so much @awsarron and @cagataycali ! 🎉

I'm thrilled to have contributed to the Strands SDK and excited to see these system prompt override improvements help developers build more flexible and dynamic AI agents.