chore: Add instructions for callback signatures

PiperOrigin-RevId: 815549924

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**:
@@ -275,6 +275,76 @@ Use other tools only when the knowledge agent doesn't have enough information.
 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:**
@@ -314,8 +384,8 @@ Use other tools only when the knowledge agent doesn't have enough information.
 
 ### 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
@@ -343,7 +413,7 @@ Use other tools only when the knowledge agent doesn't have enough information.
 **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
@@ -364,4 +434,4 @@ Use other tools only when the knowledge agent doesn't have enough information.
 **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`