Add 'auto' scope to ADK graph search tool (#519)

* Add 'auto' scope to ADK graph search tool

Add 'auto' as an allowed scope value for ZepGraphSearchTool, letting Zep
decide the best mix of edges, nodes, and episodes to return. Update scope
descriptions to be more precise and add integration test coverage for the
new auto scope.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix formatting in test_integration.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Remove ZepContextTool from auto-scope test to avoid false positive

The auto-scope test (Step 11) included ZepContextTool which injects
memory into every request, meaning the test could pass without the
graph search tool ever being invoked. Remove it so the model must
call ZepGraphSearchTool(scope="auto") to answer the question.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix mypy no-any-return in auto scope format handler

Annotate the getattr result so mypy knows context is str | None.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Bump zep-adk to 0.2.0 for release

Add auto scope, improved parameter descriptions, and None-pinning support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jackaldenryan

integrations/python/zep_adk/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.0 (2026-04-07)
+
+### Added
+
+- `auto` scope for `ZepGraphSearchTool` -- lets Zep decide the best mix of edges, nodes, and episodes to return.
+- Support for pinning optional parameters to `None` to hide them from the model schema without passing them to the SDK.
+
+### Changed
+
+- Improved `scope` parameter descriptions to be more precise about what each scope searches.
+
 ## 0.1.0 (2026-03-23)
 
 ### Added

integrations/python/zep_adk/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zep-adk"
-version = "0.1.0"
+version = "0.2.0"
 description = "Google ADK integration for Zep"
 readme = "README.md"
 requires-python = ">=3.10"

integrations/python/zep_adk/src/zep_adk/graph_search_tool.py

@@ -49,9 +49,11 @@
         "type": "STRING",
         "description": (
             "What to search for: 'edges' for facts and relationships, "
-            "'nodes' for entity summaries, 'episodes' for raw messages."
+            "'nodes' for entities and their summaries, "
+            "'episodes' for raw text data (unstructured text, messages, or JSON), "
+            "'auto' to let Zep decide the best mix of results."
         ),
-        "enum": ["edges", "nodes", "episodes"],
+        "enum": ["edges", "nodes", "episodes", "auto"],
         "default": "edges",
     },
     "reranker": {
@@ -110,6 +112,10 @@ class ZepGraphSearchTool(BaseTool):
     to the given value.  Parameters not pinned are exposed in the model's tool
     schema with sensible defaults.
 
+    Pinning an optional parameter to ``None`` hides it from the model schema
+    without passing it to the Zep SDK -- useful for suppressing irrelevant
+    parameters (e.g. ``mmr_lambda=None`` when the reranker is not ``mmr``).
+
     Args:
         zep_client: An initialised ``AsyncZep`` client.
         graph_id: Optional fixed graph ID for shared-graph search.  When set,
@@ -160,6 +166,14 @@ def __init__(
             raise ValueError(
                 f"Unknown pinned parameters: {unknown}. Allowed: {sorted(allowed_pinned)}"
             )
+        # Pinning to None means "hide from model but don't send to SDK".
+        # This is only valid for optional parameters.
+        for k, v in pinned.items():
+            if v is None and _SEARCH_PARAMS.get(k, {}).get("required"):
+                raise ValueError(
+                    f"Cannot pin required parameter '{k}' to None. "
+                    "Only optional parameters can be hidden with None."
+                )
 
         # Store pinned search params
         self._pinned: dict[str, Any] = dict(pinned)
@@ -229,9 +243,12 @@ async def run_async(self, *, args: dict[str, Any], tool_context: ToolContext) ->
             search_kwargs["user_id"] = user_id
 
         # --- Merge params: pinned > model-provided > default ----------
+        # A param pinned to None is hidden from the model and omitted from
+        # the SDK call (used to suppress optional params from the schema).
         for param_name, param_def in _SEARCH_PARAMS.items():
             if param_name in self._pinned:
-                search_kwargs[param_name] = self._pinned[param_name]
+                if self._pinned[param_name] is not None:
+                    search_kwargs[param_name] = self._pinned[param_name]
             elif param_name in args:
                 search_kwargs[param_name] = args[param_name]
             elif "default" in param_def:
@@ -279,7 +296,13 @@ def _format_results(result: Any, scope: str) -> str:
         """Format search results as readable text for the model."""
         parts: list[str] = []
 
-        if scope == "edges" and result.edges:
+        if scope == "auto":
+            # Auto scope returns a pre-formatted context string in result.context
+            # rather than populating the individual edges/nodes/episodes lists.
+            context: str | None = getattr(result, "context", None)
+            if context and context.strip():
+                return context.strip()
+        elif scope == "edges" and result.edges:
             for edge in result.edges:
                 if edge.fact:
                     parts.append(f"- {edge.fact}")

integrations/python/zep_adk/tests/test_integration.py

@@ -60,6 +60,7 @@
 SESSION_2_ID = f"adk-integ-s2-{_suffix}"
 SESSION_3_ID = f"adk-integ-s3-{_suffix}"
 SESSION_4_ID = f"adk-integ-s4-{_suffix}"
+SESSION_5_ID = f"adk-integ-s5-{_suffix}"
 THREAD_1_ID = f"adk-integ-t1-{_suffix}"
 THREAD_2_ID = f"adk-integ-t2-{_suffix}"
 THREAD_3_ID = f"adk-integ-t3-{_suffix}"
@@ -442,10 +443,68 @@ async def on_user_created(zep: AsyncZep, user_id: str) -> None:
             passed = False
 
         # ==================================================================
-        # Step 11: Tool-call message persistence — verify only final
+        # Step 11: Session 5 — ZepGraphSearchTool with scope="auto"
+        # ==================================================================
+        print("\n[Step 11] Session 5: testing ZepGraphSearchTool with scope='auto'...")
+
+        # Build a separate agent with ONLY the graph search tool (no
+        # ZepContextTool) so the model has no pre-injected memory and must
+        # call the search tool to answer questions about the user.
+        auto_agent = Agent(
+            name="zep_integ_auto_scope_agent",
+            model="gemini-2.5-flash",
+            description="A test agent with auto-scope graph search.",
+            instruction=(
+                "You have no prior knowledge about the user. You MUST use "
+                "the search_user_memory tool to answer any question about them."
+            ),
+            tools=[
+                ZepGraphSearchTool(
+                    zep_client=zep_client,
+                    name="search_user_memory",
+                    description="Search the user's knowledge graph.",
+                    scope="auto",
+                ),
+            ],
+        )
+
+        auto_runner = Runner(
+            agent=auto_agent,
+            app_name=APP_NAME,
+            session_service=session_service,
+        )
+
+        await session_service.create_session(
+            app_name=APP_NAME,
+            user_id=USER_ID,
+            session_id=SESSION_5_ID,
+            state={"zep_user_id": USER_ID},
+        )
+
+        auto_search_message = (
+            "Use the search_user_memory tool to search for what you know "
+            "about where I live. Tell me exactly what the search returns."
+        )
+        print(f"  User:  {auto_search_message}")
+        response5 = await send_message(auto_runner, SESSION_5_ID, USER_ID, auto_search_message)
+        print(f"  Agent: {response5}\n")
+
+        response5_lower = response5.lower()
+        auto_keywords = ["portland", "oregon"]
+        found_auto_kw = [kw for kw in auto_keywords if kw in response5_lower]
+        print(f"  Auto-scope keywords found: {found_auto_kw}")
+
+        passed &= check(
+            "Auto-scope graph search returned location facts",
+            len(found_auto_kw) > 0,
+            f"found={found_auto_kw}, expected_one_of={auto_keywords}",
+        )
+
+        # ==================================================================
+        # Step 12: Tool-call message persistence — verify only final
         # assistant message is persisted (not intermediate "thoughts")
         # ==================================================================
-        print("\n[Step 11] Session 4: tool-call persistence test (get_current_weather)...")
+        print("\n[Step 12] Session 4: tool-call persistence test (get_current_weather)...")
 
         await session_service.create_session(
             app_name=APP_NAME,