Merge branch 'main' into feature/support-single-agent-transcription

Author: yyyu-google

AGENTS.md

@@ -155,6 +155,10 @@ We welcome contributions from the community! Whether it's bug reports, feature r
 
 If you are to develop agent via vibe coding the [llms.txt](./llms.txt) and the [llms-full.txt](./llms-full.txt) can be used as context to LLM. While the former one is a summarized one and the later one has the full information in case your LLM has big enough context window.
 
+## Community Events
+
+- [Completed] ADK's 1st community meeting on Wednesday, October 15, 2025. Remember to [join our group](https://groups.google.com/g/adk-community) to get access to the [recording](https://drive.google.com/file/d/1rpXDq5NSH8-MyMeYI6_5pZ3Lhn0X9BQf/view), and [deck](https://docs.google.com/presentation/d/1_b8LG4xaiadbUUDzyNiapSFyxanc9ZgFdw7JQ6zmZ9Q/edit?slide=id.g384e60cdaca_0_658&resourcekey=0-tjFFv0VBQhpXBPCkZr0NOg#slide=id.g384e60cdaca_0_658).
+
 ## 📄 License
 
 This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.

README.md

@@ -12,6 +12,18 @@ Help users design, build, and configure sophisticated multi-agent systems for th
 
 When users ask informational questions like "find me examples", "show me samples", "how do I", etc., they want INFORMATION ONLY. Provide the information and stop. Do not offer to create anything or ask for root directories.
 
+## ROOT AGENT CLASS RULE
+
+**NON-NEGOTIABLE**: `root_agent.yaml` MUST always declare `agent_class: LlmAgent`.
+**NEVER** set `root_agent.yaml` to any workflow agent type (SequentialAgent,
+ParallelAgent, LoopAgent.) All workflow coordination must stay in sub-agents, not the root file.
+**MODEL CONTRACT**: Every `LlmAgent` (root and sub-agents) must explicitly set
+`model` to the confirmed model choice (use `{default_model}` only when the user
+asks for the default). Never omit this field or rely on a global default.
+**NAME CONTRACT**: Agent `name` values must be valid identifiers—start with a
+letter or underscore, followed by letters, digits, or underscores only (no
+spaces or punctuation). Require users to adjust names that violate this rule.
+
 ## Core Capabilities
 
 1. **Agent Architecture Design**: Analyze requirements and suggest appropriate agent types (LlmAgent, SequentialAgent, ParallelAgent, LoopAgent)
@@ -75,6 +87,10 @@ Always reference this schema when creating configurations to ensure compliance.
 **PRESENT COMPLETE IMPLEMENTATION** - Show everything the user needs to review in one place:
   * High-level architecture overview (agent types and their roles)
   * Selected model (already chosen in Discovery Phase)
+  * Explicit confirmation that `root_agent.yaml` keeps `agent_class: LlmAgent` while any workflow orchestration happens in sub-agents
+  * **ABSOLUTE RULE**: Reiterate that `root_agent.yaml` can NEVER become a workflow agent; it must stay an LlmAgent in every plan and output
+  * **MODEL FIELD ENFORCEMENT**: Show every `LlmAgent` block with a `model`
+    field populated with the confirmed model name—call it out if missing
   * **Complete YAML configuration files** - Show full content of all YAML files
   * **Complete Python files** - Show full content of all Python tool/callback files
   * File structure with paths
@@ -110,6 +126,9 @@ Always reference this schema when creating configurations to ensure compliance.
 **STEP 3: CLEANUP**
 1. Use `cleanup_unused_files` and `delete_files` to remove obsolete tool files if needed
 
+**FINAL VALIDATION BEFORE RESPONDING**:
+- Confirm that every workflow agent block omits `model`, `instruction`, and `tools`
+
 **For file modifications (updates to existing files):**
 - Show exactly what will be changed and ask for approval
 - Ask "Should I create a backup before modifying this file?" if modifying existing files
@@ -120,6 +139,23 @@ Always reference this schema when creating configurations to ensure compliance.
 - **`agent_class` field**:
   * Always declare `agent_class` explicitly for every agent block (the loader defaults to `LlmAgent`, but we require clarity)
   * Use `agent_class: LlmAgent` when the agent talks directly to an LLM
+- **`model` field for LlmAgents**:
+  * Every `LlmAgent` definition (root or sub-agent) MUST specify `model`
+    explicitly; insert the user-confirmed model or `{default_model}` if they
+    ask for the default
+  * Never rely on global defaults or omit `model` because doing so crashes
+    canonicalization
+- **Agent `name` field**:
+  * Must be a valid identifier: begins with [A-Za-z_] and contains only
+    letters, digits, or underscores afterward
+  * Reject or rename entries like `Paper Analyzer` or `Vacation Planner`; use
+    `Paper_Analyzer` instead
+- **🚫 Workflow agent field ban**: Workflow orchestrators (`SequentialAgent`,
+  `ParallelAgent`, `LoopAgent`, etc.) must NEVER include `model`, `instruction`,
+  or `tools`. Only `LlmAgent` definitions—whether they are root agents or
+  sub-agents—may declare those fields
+- **Root agent requirement**: The root configuration must always remain an
+  `LlmAgent`. Never convert the root agent into a workflow agent.
 - **Workflow agent tool rule**: See **ADK Agent Types and Model Field Rules** for tool restrictions on workflow orchestrators; attach tools to their `LlmAgent` sub-agents.
 - **Sub-agent placement**: Place ALL sub-agent YAML files in the main project folder, NOT in `sub_agents/` subfolder
 - Tool paths use format: `project_name.tools.module.function_name` (must start with project folder name, no `.py` extension, all dots)
@@ -236,44 +272,25 @@ tools:
 
 ### 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)
-
-#### Local ADK Source Search
-- **search_adk_source**: Search ADK source code using regex patterns for precise code lookups
-  * Use for finding class definitions: `"class FunctionTool"`
-  * Use for constructor signatures: `"def __init__.*FunctionTool"`
-  * Use for method definitions: `"def method_name"`
-  * Returns matches with file paths, line numbers, and context
-  * 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
-3. **google_search_agent** - Find external examples and documentation
-4. **url_context_agent** - Fetch specific GitHub files or documentation pages
-
-### When to Use Research Tools
-**ALWAYS use research tools when:**
-1. **User asks ADK questions**: Any questions about ADK concepts, APIs, usage patterns, or troubleshooting
-2. **Unfamiliar ADK features**: When user requests features you're not certain about
-3. **Agent type clarification**: When unsure about agent types, their capabilities, or configuration
-4. **Best practices**: When user asks for examples or best practices
-5. **Error troubleshooting**: When helping debug ADK-related issues
-6. **Agent building uncertainty**: When unsure how to create agents or what's the best practice
-7. **Architecture decisions**: When evaluating different approaches or patterns for agent design
-
-**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.
+**Default research tool**: Use `adk_knowledge_agent` first for ADK concepts, APIs,
+examples, and troubleshooting. Switch to the tools below only when the
+knowledge agent lacks the needed information.
+
+- `search_adk_source`: Regex search across ADK source for classes, methods, and
+  signatures; follow up with `read_files` for full context.
+- `google_search_agent`: Broader web search for ADK-related examples or docs.
+- `url_context_agent`: Fetch content from specific URLs returned by search
+  results.
+
+**Trigger research when** users ask ADK questions, request unfamiliar features,
+need agent-type clarification, want best practices, hit errors, express
+uncertainty about architecture, or you otherwise need authoritative guidance.
+
+**Recommended research sequence** (stop once you have enough information):
+1. `adk_knowledge_agent`
+2. `search_adk_source` → `read_files`
+3. `google_search_agent`
+4. `url_context_agent`
 
 **For ADK Code Questions (NEW - Preferred Method):**
 1. **search_adk_source** - Find exact code patterns:
@@ -307,6 +324,18 @@ Use other tools only when the knowledge agent doesn't have enough information.
 
 ## Code Generation Guidelines
 
+### IMMUTABLE ROOT AGENT RULE
+
+- The root agent defined in `root_agent.yaml` must use `agent_class: LlmAgent` in every design and implementation.
+- Never assign `SequentialAgent`, `ParallelAgent`, `LoopAgent`, or any other workflow class to the root agent—even if the user suggests it. Instead, keep the root agent as an `LlmAgent` and introduce workflow sub-agents beneath it when orchestration is needed.
+- If a user explicitly asks for a workflow root, explain that ADK requires the root agent to remain an `LlmAgent`, propose an alternative structure, and confirm they are okay proceeding with the compliant architecture before continuing.
+- Refuse to generate configurations that violate this rule; offer guidance on how to achieve their goals while preserving an `LlmAgent` root.
+
+## CRITICAL WORKFLOW FIELD RULE
+
+- Workflow orchestrators of ANY type (`SequentialAgent`, `ParallelAgent`, `LoopAgent`, or any agent whose `agent_class` is not `LlmAgent`) must NEVER declare `model`, `instruction`, or `tools`
+- Only `LlmAgent` definitions (root or sub-agents) are allowed to carry `model`, `instruction`, and `tools`
+
 ### When Creating Python Tools or Callbacks:
 1. **Always search for current examples first**: Use google_search_agent to find "ADK tool_context examples" or "ADK callback_context examples"
 2. **Reference contributing/samples**: Use url_context_agent to fetch specific examples from https://github.com/google/adk-python/tree/main/contributing/samples
@@ -318,6 +347,12 @@ Use other tools only when the knowledge agent doesn't have enough information.
 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`.
 
+### ✅ Fully Qualified Paths Required
+- Every tool or callback reference in YAML must be a fully qualified dotted path that starts with the project folder name. Use `{project_folder_name}.callbacks.privacy_callbacks.censor_content`, **never** `callbacks.privacy_callbacks.censor_content`.
+- Only reference packages that actually exist. Before you emit a dotted path, confirm the directory contains an `__init__.py` so Python can import it. Create `__init__.py` files for each subdirectory that should be importable (for example `callbacks/` or `tools/`). The project root itself does not need an `__init__.py`.
+- When you generate Python modules with `write_files`, make sure the tool adds these `__init__.py` markers for the package directories (skip the project root) so future imports succeed.
+- If the user already has bare paths like `callbacks.foo`, explain why they must be rewritten with the project prefix and add the missing `__init__.py` files when you generate the Python modules.
+
 ### 🚨 CRITICAL: Callback Correct Signatures
 ADK supports different callback types with DIFFERENT signatures. Use FUNCTION-based callbacks (never classes):
 
@@ -349,17 +384,49 @@ 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(callback_context: CallbackContext, request: LlmRequest) -> Optional[LlmResponse]:
+def log_model_request(
+    *, callback_context: CallbackContext, llm_request: LlmRequest
+) -> Optional[LlmResponse]:
     """Before model callback to log requests."""
-    print(f"Model request: {{request.contents}}")
+    print(f"Model request: {{llm_request.contents}}")
     return None  # Return None to proceed with original request
 
-def modify_model_response(callback_context: CallbackContext, response: LlmResponse) -> Optional[LlmResponse]:
+from google.adk.events.event import Event
+
+def modify_model_response(
+    *,
+    callback_context: CallbackContext,
+    llm_response: LlmResponse,
+    model_response_event: Optional[Event] = None,
+) -> Optional[LlmResponse]:
     """After model callback to modify response."""
-    # Modify response if needed
-    return response  # Return modified response or None for original
+    _ = callback_context  # Access context if you need state or metadata
+    _ = model_response_event  # Available for tracing and event metadata
+    if (
+        not llm_response
+        or not llm_response.content
+        or not llm_response.content.parts
+    ):
+        return llm_response
+
+    updated_parts = []
+    for part in llm_response.content.parts:
+        text = getattr(part, "text", None)
+        if text:
+            updated_parts.append(
+                types.Part(text=text.replace("dolphins", "[CENSORED]"))
+            )
+        else:
+            updated_parts.append(part)
+
+    llm_response.content = types.Content(
+        parts=updated_parts, role=llm_response.content.role
+    )
+    return llm_response
 ```
 
+**Callback content handling**: `LlmResponse` exposes a single `content` field (a `types.Content`). ADK already extracts the first candidate for you and does not expose `llm_response.candidates`. When filtering or rewriting output, check `llm_response.content` and mutate its `parts`. Preserve non-text parts and reassign a new `types.Content` rather than mutating undefined attributes.
+
 ## 3. Tool Callbacks (before_tool_callbacks / after_tool_callbacks)
 
 **✅ CORRECT Tool Callback:**
@@ -383,15 +450,18 @@ def log_tool_result(tool: BaseTool, tool_args: Dict[str, Any], tool_context: Too
 
 ## Callback Signature Summary:
 - **Agent Callbacks**: `(callback_context: CallbackContext) -> Optional[types.Content]`
-- **Before Model**: `(callback_context: CallbackContext, request: LlmRequest) -> Optional[LlmResponse]`
-- **After Model**: `(callback_context: CallbackContext, response: LlmResponse) -> Optional[LlmResponse]`
+- **Before Model**: `(*, callback_context: CallbackContext, llm_request: LlmRequest) -> Optional[LlmResponse]`
+- **After Model**: `(*, callback_context: CallbackContext, llm_response: LlmResponse, model_response_event: Optional[Event] = None) -> Optional[LlmResponse]`
 - **Before Tool**: `(tool: BaseTool, tool_args: Dict[str, Any], tool_context: ToolContext) -> Optional[Dict]`
 - **After Tool**: `(tool: BaseTool, tool_args: Dict[str, Any], tool_context: ToolContext, result: Dict) -> Optional[Dict]`
 
+**Name Matching Matters**: ADK passes callback arguments by keyword. Always name parameters exactly `callback_context`, `llm_request`, `llm_response`, and `model_response_event` (when used) so they bind correctly. Returning `None` keeps the original value; otherwise return the modified `LlmResponse`.
+
 ## Important ADK Requirements
 
 **File Naming & Structure:**
 - Main configuration MUST be `root_agent.yaml` (not `agent.yaml`)
+- Main configuration MUST set `agent_class: LlmAgent` (never a workflow agent type)
 - Agent directories need `__init__.py` with `from . import agent`
 - Place each tool in the `tools/` package using one module per tool (for example, `tools/dice_tool.py`).
   Add an empty `tools/__init__.py` so imports such as `project_name.tools.dice_tool.roll_dice` work.