Merge branch 'main' into add-gemma-via-api

Author: boyangsvl

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"`
@@ -265,6 +274,77 @@ Always reference this schema when creating configurations to ensure compliance.
 6. **Implement simple functions**: For obvious functions like `is_prime`, `roll_dice`, replace TODO with actual implementation
 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
+9. **Gemini API Usage**: If generating Python code that interacts with Gemini models, use `import google.genai as genai`, not `google.generativeai`.
+
+### 🚨 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
 
@@ -305,8 +385,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 +414,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 +435,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}"
+ ),
+ )

contributing/samples/adk_agent_builder_assistant/remote_agents/adk_knowledge_agent/README.md renamed to contributing/samples/adk_knowledge_agent/README.md

@@ -0,0 +1,143 @@
+# OAuth2 Client Credentials Weather Agent
+
+This sample demonstrates OAuth2 client credentials flow with ADK's `AuthenticatedFunctionTool` using a practical weather assistant agent.
+
+## Overview
+
+The OAuth2 client credentials grant type is used for server-to-server authentication where no user interaction is required. This demo shows:
+
+- How to configure OAuth2 client credentials in ADK
+- Using `AuthenticatedFunctionTool` for automatic token management
+- Transparent authentication in a practical weather assistant
+- Testing the OAuth2 client credentials implementation
+
+## Architecture
+
+```
+[WeatherAssistant] -> [AuthenticatedFunctionTool] -> [OAuth2CredentialExchanger] -> [OAuth2 Server] -> [Weather API]
+```
+
+1. **WeatherAssistant** calls weather tool when user asks for weather data
+2. **AuthenticatedFunctionTool** automatically handles OAuth2 flow
+3. **OAuth2CredentialExchanger** exchanges client credentials for access token
+4. **Authenticated requests** are made to weather API
+
+## Files
+
+### `agent.py` - WeatherAssistant Agent
+
+Weather assistant agent that demonstrates OAuth2 client credentials flow transparently:
+
+- **OAuth2 Configuration**: Client credentials setup with token URL and scopes
+- **Weather Tool**: Single `get_weather_data` tool for fetching weather information
+- **Agent Definition**: ADK LLM agent focused on providing weather information
+
+**Key Features:**
+- Automatic token exchange using client ID and secret
+- Bearer token authentication
+- Transparent OAuth2 handling (invisible to the model)
+- Practical use case demonstrating machine-to-machine authentication
+
+### `main.py` - CLI Interface
+
+Command-line interface for running the WeatherAssistant agent:
+
+```bash
+# Ask for weather
+python contributing/samples/oauth2_client_credentials/main.py "What's the weather in Tokyo?"
+```
+
+**Requirements:**
+- LLM API key (Google AI or Vertex AI)
+- OAuth2 test server running
+
+### `oauth2_test_server.py` - Local OAuth2 Server
+
+Mock OAuth2 server for testing the client credentials flow:
+
+```bash
+python contributing/samples/oauth2_client_credentials/oauth2_test_server.py
+```
+
+**Features:**
+- OIDC discovery endpoint (`/.well-known/openid_configuration`)
+- Client credentials token exchange (`/token`)
+- Protected weather API (`/api/weather`)
+- Supports both `authorization_code` and `client_credentials` grant types
+- Test credentials: `client_id="test_client"`, `client_secret="test_secret"`
+
+**Endpoints:**
+- `GET /.well-known/openid_configuration` - OIDC discovery
+- `POST /token` - Token exchange
+- `GET /api/weather` - Weather API (requires Bearer token)
+- `GET /` - Server info
+
+## Quick Start
+
+1. **Start the OAuth2 server:**
+ ```bash
+ python contributing/samples/oauth2_client_credentials/oauth2_test_server.py &
+ ```
+2. Create a `.env` file in the project root with your API credentials:
+
+```bash
+# Choose Model Backend: 0 -> ML Dev, 1 -> Vertex
+GOOGLE_GENAI_USE_VERTEXAI=1
+
+# ML Dev backend config
+GOOGLE_API_KEY=your_google_api_key_here
+
+# Vertex backend config
+GOOGLE_CLOUD_PROJECT=your_project_id
+GOOGLE_CLOUD_LOCATION=us-central1
+```
+
+3. **Run the agent:**
+ ```bash
+ # Ask for weather
+ python contributing/samples/oauth2_client_credentials/main.py "What's the weather in Tokyo?"
+ ```
+
+3. **Interactive demo (use ADK commands):**
+ ```bash
+ # Interactive CLI
+ adk run contributing/samples/oauth2_client_credentials
+
+ # Interactive web UI
+ adk web contributing/samples
+ ```
+
+## OAuth2 Configuration
+
+The agent uses these OAuth2 settings (configured in `agent.py`):
+
+```python
+flows = OAuthFlows(
+ clientCredentials=OAuthFlowClientCredentials(
+ tokenUrl="http://localhost:8000/token",
+ scopes={
+ "read": "Read access to weather data",
+ "write": "Write access for data updates",
+ "admin": "Administrative access",
+ },
+ )
+)
+
+raw_credential = AuthCredential(
+ auth_type=AuthCredentialTypes.OAUTH2,
+ oauth2=OAuth2Auth(
+ client_id="test_client",
+ client_secret="test_secret",
+ ),
+)
+```
+
+## Authentication Flow
+
+1. **Weather Request**: User asks WeatherAssistant for weather information
+2. **Tool Invocation**: Agent calls `get_weather_data` authenticated function tool
+3. **Credential Loading**: CredentialManager loads OAuth2 configuration
+4. **Token Exchange**: OAuth2CredentialExchanger uses client credentials to get access token
+5. **Request Enhancement**: AuthenticatedFunctionTool adds `Authorization: Bearer <token>` header
+6. **API Call**: Weather API accessed with valid token
+7. **Response**: Weather data returned to user