Merge remote-tracking branch 'upstream/main' into feature/redactedContent

Author: mazyu36

.github/workflows/pr-and-push.yml

@@ -0,0 +1,19 @@
+name: Pull Request and Push Action
+
+on:
+  pull_request:  # Safer than pull_request_target for untrusted code
+    branches: [ main ]
+    types: [opened, synchronize, reopened, ready_for_review, review_requested, review_request_removed]
+  push:
+    branches: [ main ]  # Also run on direct pushes to main
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  call-test-lint:
+    uses: ./.github/workflows/test-lint.yml
+    permissions:
+      contents: read
+    with:
+      ref: ${{ github.event.pull_request.head.sha }}

.github/workflows/pypi-publish-on-release.yml

@@ -0,0 +1,82 @@
+name: Publish Python Package
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  call-test-lint:
+    uses: ./.github/workflows/test-lint.yml
+    with:
+      ref: ${{ github.event.release.target_commitish }}
+
+  build:
+    name: Build distribution 📦
+    permissions:
+      contents: read
+    needs:
+      - call-test-lint
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install hatch twine
+
+    - name: Validate version
+      run: |
+        version=$(hatch version)
+        if [[ $version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Valid version format"
+            exit 0
+        else
+            echo "Invalid version format"
+            exit 1
+        fi
+
+    - name: Build
+      run: |
+        hatch build
+
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  deploy:
+    name: Upload release to PyPI
+    permissions:
+      contents: read
+    needs:
+    - build
+    runs-on: ubuntu-latest
+
+    # environment is used by PyPI Trusted Publisher and is strongly encouraged
+    # https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+    environment:
+      name: pypi
+      url: https://pypi.org/p/strands-agents
+    permissions:
+      # IMPORTANT: this permission is mandatory for Trusted Publishing
+      id-token: write
+    
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test-lint-pr.yml renamed to .github/workflows/test-lint.yml

@@ -1,14 +1,11 @@
 name: Test and Lint
 
 on:
-  pull_request:  # Safer than pull_request_target for untrusted code
-    branches: [ main ]
-    types: [opened, synchronize, reopened, ready_for_review, review_requested, review_request_removed]
-  push:
-    branches: [ main ]  # Also run on direct pushes to main
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
+  workflow_call:
+    inputs:
+      ref:
+        required: true
+        type: string
 
 jobs:
   unit-test:
@@ -56,7 +53,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.event.pull_request.head.sha }}  # Explicitly define which commit to check out
+          ref: ${{ inputs.ref }}  # Explicitly define which commit to check out
           persist-credentials: false  # Don't persist credentials for subsequent actions
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -78,7 +75,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.event.pull_request.head.sha }}
+          ref: ${{ inputs.ref }}
           persist-credentials: false
 
       - name: Set up Python

.gitignore

@@ -7,4 +7,5 @@ __pycache__*
 .pytest_cache
 .ruff_cache
 *.bak
-.vscode
+.vscode
+dist

pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"
 
 [project]
 name = "strands-agents"
-version = "0.1.5"
+dynamic = ["version"]
 description = "A model-driven approach to building AI agents in just a few lines of code"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -79,6 +79,10 @@ openai = [
     "openai>=1.68.0,<2.0.0",
 ]
 
+[tool.hatch.version]
+# Tells Hatch to use your version control system (git) to determine the version.
+source = "vcs"
+
 [tool.hatch.envs.hatch-static-analysis]
 features = ["anthropic", "litellm", "llamaapi", "ollama", "openai"]
 dependencies = [

src/strands/agent/agent.py

@@ -44,6 +44,16 @@
 logger = logging.getLogger(__name__)
 
 
+# Sentinel class and object to distinguish between explicit None and default parameter value
+class _DefaultCallbackHandlerSentinel:
+    """Sentinel class to distinguish between explicit None and default parameter value."""
+
+    pass
+
+
+_DEFAULT_CALLBACK_HANDLER = _DefaultCallbackHandlerSentinel()
+
+
 class Agent:
     """Core Agent interface.
 
@@ -70,7 +80,7 @@ def __init__(self, agent: "Agent") -> None:
             #          agent tools and thus break their execution.
             self._agent = agent
 
-        def __getattr__(self, name: str) -> Callable:
+        def __getattr__(self, name: str) -> Callable[..., Any]:
             """Call tool as a function.
 
             This method enables the method-style interface (e.g., `agent.tool.tool_name(param="value")`).
@@ -165,7 +175,7 @@ def caller(**kwargs: Any) -> Any:
                     self._agent._record_tool_execution(tool_use, tool_result, user_message_override, messages)
 
                 # Apply window management
-                self._agent.conversation_manager.apply_management(self._agent.messages)
+                self._agent.conversation_manager.apply_management(self._agent)
 
                 return tool_result
 
@@ -177,7 +187,9 @@ def __init__(
         messages: Optional[Messages] = None,
         tools: Optional[List[Union[str, Dict[str, str], Any]]] = None,
         system_prompt: Optional[str] = None,
-        callback_handler: Optional[Callable] = PrintingCallbackHandler(),
+        callback_handler: Optional[
+            Union[Callable[..., Any], _DefaultCallbackHandlerSentinel]
+        ] = _DEFAULT_CALLBACK_HANDLER,
         conversation_manager: Optional[ConversationManager] = None,
         max_parallel_tools: int = os.cpu_count() or 1,
         record_direct_tool_call: bool = True,
@@ -204,7 +216,8 @@ def __init__(
             system_prompt: System prompt to guide model behavior.
                 If None, the model will behave according to its default settings.
             callback_handler: Callback for processing events as they happen during agent execution.
-                Defaults to strands.handlers.PrintingCallbackHandler if None.
+                If not provided (using the default), a new PrintingCallbackHandler instance is created.
+                If explicitly set to None, null_callback_handler is used.
             conversation_manager: Manager for conversation history and context window.
                 Defaults to strands.agent.conversation_manager.SlidingWindowConversationManager if None.
             max_parallel_tools: Maximum number of tools to run in parallel when the model returns multiple tool calls.
@@ -222,7 +235,17 @@ def __init__(
         self.messages = messages if messages is not None else []
 
         self.system_prompt = system_prompt
-        self.callback_handler = callback_handler or null_callback_handler
+
+        # If not provided, create a new PrintingCallbackHandler instance
+        # If explicitly set to None, use null_callback_handler
+        # Otherwise use the passed callback_handler
+        self.callback_handler: Union[Callable[..., Any], PrintingCallbackHandler]
+        if isinstance(callback_handler, _DefaultCallbackHandlerSentinel):
+            self.callback_handler = PrintingCallbackHandler()
+        elif callback_handler is None:
+            self.callback_handler = null_callback_handler
+        else:
+            self.callback_handler = callback_handler
 
         self.conversation_manager = conversation_manager if conversation_manager else SlidingWindowConversationManager()
 
@@ -415,7 +438,7 @@ def target_callback() -> None:
             thread.join()
 
     def _run_loop(
-        self, prompt: str, kwargs: Any, supplementary_callback_handler: Optional[Callable] = None
+        self, prompt: str, kwargs: Dict[str, Any], supplementary_callback_handler: Optional[Callable[..., Any]] = None
     ) -> AgentResult:
         """Execute the agent's event loop with the given prompt and parameters."""
         try:
@@ -439,9 +462,9 @@ def _run_loop(
             return self._execute_event_loop_cycle(invocation_callback_handler, kwargs)
 
         finally:
-            self.conversation_manager.apply_management(self.messages)
+            self.conversation_manager.apply_management(self)
 
-    def _execute_event_loop_cycle(self, callback_handler: Callable, kwargs: dict[str, Any]) -> AgentResult:
+    def _execute_event_loop_cycle(self, callback_handler: Callable[..., Any], kwargs: Dict[str, Any]) -> AgentResult:
         """Execute the event loop cycle with retry logic for context window limits.
 
         This internal method handles the execution of the event loop cycle and implements
@@ -483,7 +506,7 @@ def _execute_event_loop_cycle(self, callback_handler: Callable, kwargs: dict[str
         except ContextWindowOverflowException as e:
             # Try reducing the context size and retrying
 
-            self.conversation_manager.reduce_context(messages, e=e)
+            self.conversation_manager.reduce_context(self, e=e)
             return self._execute_event_loop_cycle(callback_handler_override, kwargs)
 
     def _record_tool_execution(

src/strands/agent/conversation_manager/conversation_manager.py

@@ -1,9 +1,10 @@
 """Abstract interface for conversation history management."""
 
 from abc import ABC, abstractmethod
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 
-from ...types.content import Messages
+if TYPE_CHECKING:
+    from ...agent.agent import Agent
 
 
 class ConversationManager(ABC):
@@ -19,22 +20,22 @@ class ConversationManager(ABC):
 
     @abstractmethod
     # pragma: no cover
-    def apply_management(self, messages: Messages) -> None:
-        """Applies management strategy to the provided list of messages.
+    def apply_management(self, agent: "Agent") -> None:
+        """Applies management strategy to the provided agent.
 
         Processes the conversation history to maintain appropriate size by modifying the messages list in-place.
         Implementations should handle message pruning, summarization, or other size management techniques to keep the
         conversation context within desired bounds.
 
         Args:
-            messages: The conversation history to manage.
+            agent: The agent whose conversation history will be manage.
                 This list is modified in-place.
         """
         pass
 
     @abstractmethod
     # pragma: no cover
-    def reduce_context(self, messages: Messages, e: Optional[Exception] = None) -> None:
+    def reduce_context(self, agent: "Agent", e: Optional[Exception] = None) -> None:
         """Called when the model's context window is exceeded.
 
         This method should implement the specific strategy for reducing the window size when a context overflow occurs.
@@ -48,7 +49,7 @@ def reduce_context(self, messages: Messages, e: Optional[Exception] = None) -> N
         - Maintaining critical conversation markers
 
         Args:
-            messages: The conversation history to reduce.
+            agent: The agent whose conversation history will be reduced.
                 This list is modified in-place.
             e: The exception that triggered the context reduction, if any.
         """

src/strands/agent/conversation_manager/null_conversation_manager.py

@@ -1,8 +1,10 @@
 """Null implementation of conversation management."""
 
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ...agent.agent import Agent
 
-from ...types.content import Messages
 from ...types.exceptions import ContextWindowOverflowException
 from .conversation_manager import ConversationManager
 
@@ -17,19 +19,19 @@ class NullConversationManager(ConversationManager):
     - Situations where the full conversation history should be preserved
     """
 
-    def apply_management(self, messages: Messages) -> None:
+    def apply_management(self, _agent: "Agent") -> None:
         """Does nothing to the conversation history.
 
         Args:
-            messages: The conversation history that will remain unmodified.
+            agent: The agent whose conversation history will remain unmodified.
         """
         pass
 
-    def reduce_context(self, messages: Messages, e: Optional[Exception] = None) -> None:
+    def reduce_context(self, _agent: "Agent", e: Optional[Exception] = None) -> None:
         """Does not reduce context and raises an exception.
 
         Args:
-            messages: The conversation history that will remain unmodified.
+            agent: The agent whose conversation history will remain unmodified.
             e: The exception that triggered the context reduction, if any.
 
         Raises: