feat: add per_turn parameter to SlidingWindowConversationManager

[zastrowm]

Description

Allow conversation managers to act as hook providers and add an option to built-in conversation managers to proactively apply message management during the agent loop execution.

Use that functionality to add an option to SlidingWindowConversationManager to allow per_turn management application

Addresses #509

Public API Changes

manager = SlidingWindowConversationManager(
    window_size=40,
    should_truncate_results=True,
    per_turn=True  # or per_turn=5 for every 5 model calls
)
# Can be changed dynamically
manager.per_turn = 3

Default per_turn=False maintains current behavior

Parameter Options

• per_turn=False (default): Current behavior - management only at end
• per_turn=True: Apply management before every model call
• per_turn=N (int): Apply management before every N model calls

ConversationManager as HookProviders

ConversationManager now provides a register_hooks() method that subclasses can override to integrate with the agent's event lifecycle and at initialization time, it will have it's hook subscribed to. SlidingWindowConversationManager leverages this underneath the hood.

Added @runtime_checkable to HookProvider protocol to enable proper isinstance checks.

Before:

class CustomConversationManager(ConversationManager):
    def apply_management(self, agent, **kwargs):
        # Only called at end of execution
        pass

After:

class CustomConversationManager(ConversationManager):
    def register_hooks(self, registry, **kwargs):
        super().register_hooks(registry, **kwargs)
        # Can now respond to lifecycle events
        registry.add_callback(BeforeModelCallEvent, self._on_before_model_call)
        registry.add_callback(AfterToolCallEvent, self._on_after_tool_call)
    
    def apply_management(self, agent, **kwargs):
        # Still called at end of execution
        pass

We guide folks to call super().register_hooks(registry, **kwargs) because in the future I'd like to re-implement the default conversation-management behavior (where apply_management and reduce_context is called) using hooks - if we do that and folks aren't calling super().register_hooks(registry, **kwargs) then once we migrate to hooks then derived classes that do not call super().register_hooks would lose the default behavior which would be a breaking change.

Related Issues

• [FEATURE] Applying ConversationManager during the Agent Loop Execution (on specific Hook Events) #509
• Docs PR: feat: Add docs about conversation-managers being HookProviders docs#401

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

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

[codecov]

Codecov Report

❌ Patch coverage is 97.05882% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ion_manager/sliding_window_conversation_manager.py	96.29%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!