Merge branch 'main' into feat/function-tools-enum-support

Author: SOORAJTS2001

contributing/samples/adk_agent_builder_assistant/agent_builder_assistant.py

@@ -26,6 +26,7 @@
 from google.adk.tools import FunctionTool
 from google.genai import types
 
+from .sub_agents.adk_knowledge_agent import create_adk_knowledge_agent
 from .sub_agents.google_search_agent import create_google_search_agent
 from .sub_agents.url_context_agent import create_url_context_agent
 from .tools.cleanup_unused_files import cleanup_unused_files
@@ -71,9 +72,14 @@ def create_agent(
     # - Maintains compatibility with existing ADK tool ecosystem
 
     # Built-in ADK tools wrapped as sub-agents
+    adk_knowledge_agent = create_adk_knowledge_agent()
     google_search_agent = create_google_search_agent()
     url_context_agent = create_url_context_agent()
-    agent_tools = [AgentTool(google_search_agent), AgentTool(url_context_agent)]
+    agent_tools = [
+        AgentTool(adk_knowledge_agent),
+        AgentTool(google_search_agent),
+        AgentTool(url_context_agent),
+    ]
 
     # CUSTOM FUNCTION TOOLS: Agent Builder specific capabilities
     #

contributing/samples/adk_agent_builder_assistant/instruction_embedded.template

@@ -42,7 +42,7 @@ Always reference this schema when creating configurations to ensure compliance.
     - Questions about ADK capabilities, concepts, or existing implementations
     - **CRITICAL**: For informational questions, provide the requested information and STOP. Do NOT offer to create, build, or generate anything unless explicitly asked.
   * **CREATION/BUILDING INTENT** (Only then ask for root directory):
-    - "Create a new agent..." / "Build me an agent..." 
+    - "Create a new agent..." / "Build me an agent..."
     - "Generate an agent..." / "Implement an agent..."
     - "Update my agent..." / "Modify my agent..." / "Change my agent..."
     - "I want to create..." / "Help me build..." / "Help me update..."
@@ -71,7 +71,7 @@ Always reference this schema when creating configurations to ensure compliance.
 - Explore existing project structure using the RESOLVED ABSOLUTE PATH
 - Identify integration needs (APIs, databases, external services)
 
-### 2. Design Phase  
+### 2. Design Phase
 - **MANDATORY HIGH-LEVEL DESIGN CONFIRMATION**: Present complete architecture design BEFORE any implementation
 - **ASK FOR EXPLICIT CONFIRMATION**: "Does this design approach work for you? Should I proceed with implementation?"
 - **INCLUDE IN DESIGN PRESENTATION**:
@@ -194,6 +194,9 @@ Always reference this schema when creating configurations to ensure compliance.
 
 ### ADK Knowledge and Research Tools
 
+#### Remote Semantic Search
+- **adk_knowledge_agent**: Search ADK knowledge base for ADK examples, patterns, and documentation
+
 #### Web-based Research
 - **google_search_agent**: Search web for ADK examples, patterns, and documentation (returns full page content as results)
 - **url_context_agent**: Fetch content from specific URLs when mentioned in search results or user queries (use only when specific URLs need additional fetching)
@@ -207,8 +210,10 @@ Always reference this schema when creating configurations to ensure compliance.
   * Follow up with **read_files** to get complete file contents
 
 **Research Workflow for ADK Questions:**
+Mainly rely on **adk_knowledge_agent** for ADK questions. Use other tools only when the knowledge agent doesn't have enough information.
+
 1. **search_adk_source** - Find specific code patterns with regex
-2. **read_files** - Read complete source files for detailed analysis  
+2. **read_files** - Read complete source files for detailed analysis
 3. **google_search_agent** - Find external examples and documentation
 4. **url_context_agent** - Fetch specific GitHub files or documentation pages
 
@@ -224,6 +229,10 @@ Always reference this schema when creating configurations to ensure compliance.
 
 **Research Tool Usage Patterns:**
 
+**Default Research Tool:**
+Use **adk_knowledge_agent** as the primary research tool for ADK questions.
+Use other tools only when the knowledge agent doesn't have enough information.
+
 **For ADK Code Questions (NEW - Preferred Method):**
 1. **search_adk_source** - Find exact code patterns:
    * Class definitions: `"class FunctionTool"` or `"class.*Agent"`
@@ -266,6 +275,76 @@ Always reference this schema when creating configurations to ensure compliance.
 7. **Keep TODO for complex**: For complex business logic, leave TODO comments
 8. **Follow current ADK patterns**: Always search for and reference the latest examples from contributing/samples
 
+### 🚨 CRITICAL: Callback Correct Signatures
+ADK supports different callback types with DIFFERENT signatures. Use FUNCTION-based callbacks (never classes):
+
+## 1. Agent Callbacks (before_agent_callbacks / after_agent_callbacks)
+
+**✅ CORRECT Agent Callback:**
+```python
+from typing import Optional
+from google.genai import types
+from google.adk.agents.callback_context import CallbackContext
+
+def content_filter_callback(context: CallbackContext) -> Optional[types.Content]:
+    """After agent callback to filter sensitive content."""
+    # Access the response content through context
+    if hasattr(context, 'response') and context.response:
+        response_text = str(context.response)
+        if "confidential" in response_text.lower():
+            filtered_text = response_text.replace("confidential", "[FILTERED]")
+            return types.Content(parts=[types.Part(text=filtered_text)])
+    return None  # Return None to keep original response
+```
+
+## 2. Model Callbacks (before_model_callbacks / after_model_callbacks)
+
+**✅ CORRECT Model Callback:**
+```python
+from typing import Optional
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.adk.agents.callback_context import CallbackContext
+
+def log_model_request(context: CallbackContext, request: LlmRequest) -> Optional[LlmResponse]:
+    """Before model callback to log requests."""
+    print(f"Model request: {{request.contents}}")
+    return None  # Return None to proceed with original request
+
+def modify_model_response(context: CallbackContext, response: LlmResponse) -> Optional[LlmResponse]:
+    """After model callback to modify response."""
+    # Modify response if needed
+    return response  # Return modified response or None for original
+```
+
+## 3. Tool Callbacks (before_tool_callbacks / after_tool_callbacks)
+
+**✅ CORRECT Tool Callback:**
+```python
+from typing import Any, Dict, Optional
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.tool_context import ToolContext
+
+def validate_tool_input(tool: BaseTool, args: Dict[str, Any], context: ToolContext) -> Optional[Dict]:
+    """Before tool callback to validate input."""
+    # Validate or modify tool arguments
+    if "unsafe_param" in args:
+        del args["unsafe_param"]
+    return args  # Return modified args or None for original
+
+def log_tool_result(tool: BaseTool, args: Dict[str, Any], context: ToolContext, result: Dict) -> Optional[Dict]:
+    """After tool callback to log results."""
+    print(f"Tool {{tool.name}} executed with result: {{result}}")
+    return None  # Return None to keep original result
+```
+
+## Callback Signature Summary:
+- **Agent Callbacks**: `(CallbackContext) -> Optional[types.Content]`
+- **Before Model**: `(CallbackContext, LlmRequest) -> Optional[LlmResponse]`
+- **After Model**: `(CallbackContext, LlmResponse) -> Optional[LlmResponse]`
+- **Before Tool**: `(BaseTool, Dict[str, Any], ToolContext) -> Optional[Dict]`
+- **After Tool**: `(BaseTool, Dict[str, Any], ToolContext, Dict) -> Optional[Dict]`
+
 ## Important ADK Requirements
 
 **File Naming & Structure:**
@@ -305,8 +384,8 @@ Always reference this schema when creating configurations to ensure compliance.
 
 ### Examples:
 - **User input**: `./config_agents/roll_and_check`
-- **WRONG approach**: Create files at `/config_agents/roll_and_check` 
-- **CORRECT approach**: 
+- **WRONG approach**: Create files at `/config_agents/roll_and_check`
+- **CORRECT approach**:
   1. Call `resolve_root_directory("./config_agents/roll_and_check")`
   2. Get resolved path: `/Users/user/Projects/adk-python/config_agents/roll_and_check`
   3. Use the resolved absolute path for all operations
@@ -334,7 +413,7 @@ Always reference this schema when creating configurations to ensure compliance.
 **Your primary role is to be a collaborative architecture consultant that follows an efficient, user-centric workflow:**
 
 1. **Always ask for root folder first** - Know where to create the project
-2. **Design with specific paths** - Include exact file locations in proposals  
+2. **Design with specific paths** - Include exact file locations in proposals
 3. **Provide high-level architecture overview** - When confirming design, always include:
    * Overall system architecture and component relationships
    * Agent types and their responsibilities
@@ -355,4 +434,4 @@ Always reference this schema when creating configurations to ensure compliance.
 **Incorrect Commands to Avoid:**
 - `adk run [root_directory]/root_agent.yaml` - Do NOT specify the YAML file directly
 - `adk web` without parent directory - Must specify the parent folder containing the agent projects
-- Always use the project directory for `adk run`, and parent directory for `adk web`
+- Always use the project directory for `adk run`, and parent directory for `adk web`

contributing/samples/adk_agent_builder_assistant/sub_agents/__init__.py

@@ -14,7 +14,12 @@
 
 """Sub-agents for Agent Builder Assistant."""
 
+from .adk_knowledge_agent import create_adk_knowledge_agent
 from .google_search_agent import create_google_search_agent
 from .url_context_agent import create_url_context_agent
 
-__all__ = ['create_google_search_agent', 'create_url_context_agent']
+__all__ = [
+    'create_adk_knowledge_agent',
+    'create_google_search_agent',
+    'create_url_context_agent',
+]

contributing/samples/adk_agent_builder_assistant/sub_agents/adk_knowledge_agent.py

@@ -0,0 +1,33 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Sub-agent for ADK Knowledge."""
+
+from google.adk.agents.llm_agent import Agent
+from google.adk.agents.remote_a2a_agent import AGENT_CARD_WELL_KNOWN_PATH
+from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
+
+
+def create_adk_knowledge_agent() -> Agent:
+  """Create a sub-agent that only uses google_search tool."""
+  return RemoteA2aAgent(
+      name="adk_knowledge_agent",
+      description=(
+          "Agent for performing Vertex AI Search to find ADK knowledge and"
+          " documentation"
+      ),
+      agent_card=(
+          f"https://adk-agent-builder-knowledge-service-654646711756.us-central1.run.app/a2a/adk_knowledge_agent{AGENT_CARD_WELL_KNOWN_PATH}"
+      ),
+  )