Python: Fix RedisContextProvider for redisvl 0.14.0 by using AggregateHybridQuery

python/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **agent-framework-redis**: Fix `RedisContextProvider` compatibility with redisvl 0.14.0 by using `AggregateHybridQuery` ([#3954](https://github.com/microsoft/agent-framework/pull/3954))
+
 ## [1.0.0rc3] - 2026-03-04
 
 ### Added

python/packages/redis/agent_framework_redis/_context_provider.py

@@ -22,7 +22,7 @@
     IntegrationInvalidRequestException,
 )
 from redisvl.index import AsyncSearchIndex
-from redisvl.query import HybridQuery, TextQuery
+from redisvl.query import AggregateHybridQuery, TextQuery
 from redisvl.query.filter import FilterExpression, Tag
 from redisvl.utils.token_escaper import TokenEscaper
 from redisvl.utils.vectorize import BaseVectorizer
@@ -341,7 +341,7 @@ async def _redis_search(
         filter_expression: Any | None = None,
         return_fields: list[str] | None = None,
         num_results: int = 10,
-        linear_alpha: float = 0.7,
+        alpha: float = 0.7,
     ) -> list[dict[str, Any]]:
         """Runs a text or hybrid vector-text search with optional filters."""
         await self._ensure_index()
@@ -371,14 +371,14 @@ async def _redis_search(
         try:
             if self.redis_vectorizer and self.vector_field_name:
                 vector = await self.redis_vectorizer.aembed(q)  # pyright: ignore[reportUnknownMemberType]
-                query = HybridQuery(
+                query = AggregateHybridQuery(
                     text=q,
                     text_field_name="content",
                     vector=vector,
                     vector_field_name=self.vector_field_name,
                     text_scorer=text_scorer,
                     filter_expression=combined_filter,
-                    linear_alpha=linear_alpha,
+                    alpha=alpha,
                     dtype=self.redis_vectorizer.dtype,  # pyright: ignore[reportUnknownMemberType]
                     num_results=num_results,
                     return_fields=return_fields,

python/packages/redis/tests/test_providers.py

@@ -271,6 +271,44 @@ async def test_aenter_returns_self(self, patch_index_from_dict: MagicMock):  # n
             assert p is provider
 
 
+class TestRedisContextProviderHybridQuery:
+    """Test for AggregateHybridQuery parameter compatibility with redisvl 0.14.0."""
+
+    async def test_aggregate_hybrid_query_uses_alpha(
+        self,
+        mock_index: AsyncMock,
+        patch_index_from_dict: MagicMock,  # noqa: ARG002 - fixture modifies behavior via side effects
+    ):
+        """Ensure AggregateHybridQuery is called with alpha parameter."""
+        from redisvl.utils.vectorize import BaseVectorizer
+
+        # Create a mock vectorizer that inherits from BaseVectorizer
+        mock_vectorizer = MagicMock(spec=BaseVectorizer)
+        mock_vectorizer.dims = 128
+        mock_vectorizer.dtype = "float32"
+        mock_vectorizer.aembed = AsyncMock(return_value=[0.1] * 128)
+
+        mock_index.query = AsyncMock(return_value=[{"content": "test result"}])
+
+        provider = RedisContextProvider(
+            source_id="ctx",
+            user_id="u1",
+            redis_vectorizer=mock_vectorizer,
+            vector_field_name="embedding",
+        )
+
+        # Call _redis_search with custom alpha
+        with patch("agent_framework_redis._context_provider.AggregateHybridQuery") as mock_hybrid_query:
+            mock_hybrid_query.return_value = MagicMock()
+            await provider._redis_search(text="test query", alpha=0.5)
+
+            # Verify AggregateHybridQuery was called with alpha parameter
+            mock_hybrid_query.assert_called_once()
+            call_kwargs = mock_hybrid_query.call_args.kwargs
+            assert "alpha" in call_kwargs
+            assert call_kwargs["alpha"] == 0.5
+
+
 # ===========================================================================
 # RedisHistoryProvider tests
 # ===========================================================================