Merge branch 'main' into fix/transcript_finish

Author: hangfei

.github/ISSUE_TEMPLATE/bug_report.md

@@ -19,7 +19,7 @@ Steps to reproduce the behavior:
 1. Install '...'
 2. Run '....'
 3. Open '....'
-4. Provie error or stacktrace
+4. Provide error or stacktrace
 
 **Expected behavior**
 A clear and concise description of what you expected to happen.

CHANGELOG.md

@@ -79,6 +79,8 @@
 * Fix issue with MCP tools throwing an error ([1a4261a](https://github.com/google/adk-python/commit/1a4261ad4b66cdeb39d39110a086bd6112b17516))
 * Remove redundant `format` field from LiteLLM content objects ([489c39d](https://github.com/google/adk-python/commit/489c39db01465e38ecbc2c7f32781c349b8cddc9))
 * Update the contribution analysis tool to use original write mode ([54db3d4](https://github.com/google/adk-python/commit/54db3d4434e0706b83a589fa2499d11d439a6e4e))
+* Fix agent evaluations detailed output rows wrapping issue([4284c61](https://github.com/google/adk-python/commit/4284c619010b8246c1ecaa011f14b6cc9de512dd))
+* Update dependency version constraints to be based on PyPI versions([0b1784e](https://github.com/google/adk-python/commit/0b1784e0e493a0e2df1edfe37e5ed5f4247e7d9d))
 
 ### Improvements
 
@@ -97,6 +99,7 @@
 * Add sample agent for VertexAiCodeExecutor ([edfe553](https://github.com/google/adk-python/commit/edfe5539421d196ca4da14d3a37fac7b598f8c8d))
 * Adds a new sample agent that demonstrates how to integrate PostgreSQL databases using the Model Context Protocol (MCP) ([45a2168](https://github.com/google/adk-python/commit/45a2168e0e6773e595ecfb825d7e4ab0a38c3a38))
 * Add example for using ADK with Fast MCP sampling ([d3796f9](https://github.com/google/adk-python/commit/d3796f9b33251d28d05e6701f11e80f02a2a49e1))
+* Refactor gepa sample code and clean-up user demo colab([63353b2](https://github.com/google/adk-python/commit/63353b2b74e23e97385892415c5a3f2a59c3504f))
 
 ## [1.17.0](https://github.com/google/adk-python/compare/v1.16.0...v1.17.0) (2025-10-22)
 

contributing/samples/adk_agent_builder_assistant/agent_builder_assistant.py

@@ -15,6 +15,8 @@
 """Agent factory for creating Agent Builder Assistant with embedded schema."""
 
 from pathlib import Path
+import textwrap
+from typing import Any
 from typing import Callable
 from typing import Optional
 from typing import Union
@@ -128,25 +130,175 @@ def _load_schema() -> str:
     # CENTRALIZED ADK AGENTCONFIG SCHEMA LOADING: Use common utility function
     # This avoids duplication across multiple files and provides consistent
     # ADK AgentConfig schema loading with caching and error handling.
-    schema_content = load_agent_config_schema(
-        raw_format=True,  # Get as JSON string
+    schema_dict = load_agent_config_schema()
+    return AgentBuilderAssistant._build_schema_reference(schema_dict)
+
+  @staticmethod
+  def _build_schema_reference(schema: dict[str, Any]) -> str:
+    """Create compact AgentConfig reference text for prompt embedding."""
+
+    defs: dict[str, Any] = schema.get("$defs", {})
+    top_level_fields: dict[str, Any] = schema.get("properties", {})
+    wrapper = textwrap.TextWrapper(width=78)
+    lines: list[str] = []
+
+    def add(text: str = "", indent: int = 0) -> None:
+      """Append wrapped text with indentation."""
+      if not text:
+        lines.append("")
+        return
+      indent_str = " " * indent
+      wrapper.initial_indent = indent_str
+      wrapper.subsequent_indent = indent_str
+      lines.extend(wrapper.fill(text).split("\n"))
+
+    add("ADK AgentConfig quick reference")
+    add("--------------------------------")
+
+    add()
+    add("LlmAgent (agent_class: LlmAgent)")
+    add(
+        "Required fields: name, instruction. ADK best practice is to always set"
+        " model explicitly.",
+        indent=2,
+    )
+    add("Optional fields:", indent=2)
+    add("agent_class: defaults to LlmAgent; keep for clarity.", indent=4)
+    add("description: short summary string.", indent=4)
+    add("sub_agents: list of AgentRef entries (see below).", indent=4)
+    add(
+        "before_agent_callbacks / after_agent_callbacks: list of CodeConfig "
+        "entries that run before or after the agent loop.",
+        indent=4,
+    )
+    add("model: string model id (required in practice).", indent=4)
+    add(
+        "disallow_transfer_to_parent / disallow_transfer_to_peers: booleans to "
+        "restrict automatic transfer.",
+        indent=4,
+    )
+    add(
+        "input_schema / output_schema: JSON schema objects to validate inputs "
+        "and outputs.",
+        indent=4,
+    )
+    add("output_key: name to store agent output in session context.", indent=4)
+    add(
+        "include_contents: bool; include tool/LLM contents in response.",
+        indent=4,
+    )
+    add("tools: list of ToolConfig entries (see below).", indent=4)
+    add(
+        "before_model_callbacks / after_model_callbacks: list of CodeConfig "
+        "entries around LLM calls.",
+        indent=4,
+    )
+    add(
+        "before_tool_callbacks / after_tool_callbacks: list of CodeConfig "
+        "entries around tool calls.",
+        indent=4,
+    )
+    add(
+        "generate_content_config: passes directly to google.genai "
+        "GenerateContentConfig (supporting temperature, topP, topK, "
+        "maxOutputTokens, safetySettings, responseSchema, routingConfig,"
+        " etc.).",
+        indent=4,
     )
 
-    # Format as indented code block for instruction embedding
-    #
-    # Why indentation is needed:
-    # - The ADK AgentConfig schema gets embedded into instruction templates using .format()
-    # - Proper indentation maintains readability in the final instruction
-    # - Code block markers (```) help LLMs recognize this as structured data
-    #
-    # Example final instruction format:
-    #   "Here is the ADK AgentConfig schema:
-    #   ```json
-    #     {"type": "object", "properties": {...}}
-    #   ```"
-    lines = schema_content.split("\n")
-    indented_lines = ["  " + line for line in lines]  # 2-space indent
-    return "```json\n" + "\n".join(indented_lines) + "\n  ```"
+    add()
+    add("Workflow agents (LoopAgent, ParallelAgent, SequentialAgent)")
+    add(
+        "Share BaseAgent fields: agent_class, name, description, sub_agents, "
+        "before/after_agent_callbacks. Never declare model, instruction, or "
+        "tools on workflow orchestrators.",
+        indent=2,
+    )
+    add(
+        "LoopAgent adds max_iterations (int) controlling iteration cap.",
+        indent=2,
+    )
+
+    add()
+    add("AgentRef")
+    add(
+        "Used inside sub_agents lists. Provide either config_path (string path "
+        "to another YAML file) or code (dotted Python reference) to locate the "
+        "sub-agent definition.",
+        indent=2,
+    )
+
+    add()
+    add("ToolConfig")
+    add(
+        "Items inside tools arrays. Required field name (string). For built-in "
+        "tools use the exported short name, for custom tools use the dotted "
+        "module path.",
+        indent=2,
+    )
+    add(
+        "args: optional object of additional keyword arguments. Use simple "
+        "key-value pairs (ToolArgsConfig) or structured ArgumentConfig entries "
+        "when a list is required by callbacks.",
+        indent=2,
+    )
+
+    add()
+    add("ArgumentConfig")
+    add(
+        "Represents a single argument. value is required and may be any JSON "
+        "type. name is optional (null allowed). Often used in callback args.",
+        indent=2,
+    )
+
+    add()
+    add("CodeConfig")
+    add(
+        "References Python code for callbacks or dynamic tool creation."
+        " Requires name (dotted path). args is an optional list of"
+        " ArgumentConfig items executed when invoking the function.",
+        indent=2,
+    )
+
+    add()
+    add("GenerateContentConfig highlights")
+    add(
+        "Controls LLM generation behavior. Common fields: maxOutputTokens, "
+        "temperature, topP, topK, candidateCount, responseMimeType, "
+        "responseSchema/responseJsonSchema, automaticFunctionCalling, "
+        "safetySettings, routingConfig; see Vertex AI GenAI docs for full "
+        "semantics.",
+        indent=2,
+    )
+
+    add()
+    add(
+        "All other schema definitions in AgentConfig.json remain available but "
+        "are rarely needed for typical agent setups. Refer to the source file "
+        "for exhaustive field descriptions when implementing advanced configs.",
+    )
+
+    if top_level_fields:
+      add()
+      add("Top-level AgentConfig fields (from schema)")
+      for field_name in sorted(top_level_fields):
+        description = top_level_fields[field_name].get("description", "")
+        if description:
+          add(f"{field_name}: {description}", indent=2)
+        else:
+          add(field_name, indent=2)
+
+    if defs:
+      add()
+      add("Additional schema definitions")
+      for def_name in sorted(defs):
+        description = defs[def_name].get("description", "")
+        if description:
+          add(f"{def_name}: {description}", indent=2)
+        else:
+          add(def_name, indent=2)
+
+    return "```text\n" + "\n".join(lines) + "\n```"
 
   @staticmethod
   def _load_instruction_with_schema(

contributing/samples/adk_agent_builder_assistant/tools/search_adk_source.py

@@ -46,7 +46,7 @@ async def search_adk_source(
     max_results: Maximum number of results to return (default: 20)
     context_lines: Number of context lines to include around matches (default:
       3)
-    case_sensitive: Whether search should be case sensitive (default: False)
+    case_sensitive: Whether search should be case-sensitive (default: False)
 
   Returns:
     Dict containing search results:

contributing/samples/adk_agent_builder_assistant/tools/write_config_files.py

@@ -66,7 +66,7 @@ async def write_config_files(
 
   Args:
     configs: Dict mapping file_path to config_content (YAML as string)
-    backup_existing: Whether to create timest   amped backup of existing files
+    backup_existing: Whether to create timestamped backup of existing files
       before overwriting (default: False, User should decide)
     create_directories: Whether to create parent directories if they don't exist
       (default: True)

contributing/samples/adk_answering_agent/agent.py

@@ -61,7 +61,7 @@
 
 3. **Decide whether to respond**:
    * If all the following conditions are met, try to add a comment to the
-     discussion, otherwise, do not respond:
+     discussion; otherwise, do not respond:
      - The discussion is not closed.
      - The latest comment is not from you or other agents (marked as
        "Response from XXX Agent").
@@ -102,7 +102,7 @@
     * You **should always** use the `convert_gcs_links_to_https` tool to convert
       GCS links (e.g. "gs://...") to HTTPS links.
     * **Do not** use the `convert_gcs_links_to_https` tool for non-GCS links.
-    * Make sure the citation URL is valid. Otherwise do not list this specific
+    * Make sure the citation URL is valid. Otherwise, do not list this specific
       citation.
   * Do not respond to any other discussion except the one specified by the user.
 

contributing/samples/adk_answering_agent/utils.py

@@ -128,7 +128,7 @@ def convert_gcs_to_https(gcs_uri: str) -> Optional[str]:
 
     base_url = "https://google.github.io/adk-docs/"
     if os.path.basename(path_after_docs) == "index.md":
-      # Use the directory path if it is a index file
+      # Use the directory path if it is an index file
       final_path_segment = os.path.dirname(path_after_docs)
     else:
       # Otherwise, use the file name without extension

contributing/samples/adk_documentation/adk_docs_updater/agent.py

@@ -54,10 +54,10 @@
     ),
     instruction=f"""
       # 1. Identity
-      You are a helper bot that updates ADK docs in Github Repository {DOC_OWNER}/{DOC_REPO}
-      based on the code in the ADK Python codebase in Github Repository {CODE_OWNER}/{CODE_REPO} according to the instructions in the ADK docs issues.
+      You are a helper bot that updates ADK docs in GitHub Repository {DOC_OWNER}/{DOC_REPO}
+      based on the code in the ADK Python codebase in GitHub Repository {CODE_OWNER}/{CODE_REPO} according to the instructions in the ADK docs issues.
 
-      You are very familiar with Github, expecially how to search for files in a Github repository using git grep.
+      You are very familiar with GitHub, especially how to search for files in a GitHub repository using git grep.
 
       # 2. Responsibilities
       Your core responsibility includes:
@@ -69,18 +69,18 @@
       # 3. Workflow
       1. Always call the `clone_or_pull_repo` tool to make sure the ADK docs and codebase repos exist in the local folder {LOCAL_REPOS_DIR_PATH}/repo_name and are the latest version.
       2. Read and analyze the issue specified by user.
-        - If user only specified the issue number, call the `get_issue` tool to get the issue details, otherwise use the issue details provided by user directly.
+        - If user only specified the issue number, call the `get_issue` tool to get the issue details; otherwise, use the issue details provided by user directly.
       3. If the issue contains instructions about how to update the ADK docs, follow the instructions to update the ADK docs.
       4. Understand the doc update instructions.
         - Ignore and skip the instructions about updating API reference docs, since it will be automatically generated by the ADK team.
       5. Read the doc to update using the `read_local_git_repo_file_content` tool from the local ADK docs repo under {LOCAL_REPOS_DIR_PATH}/{DOC_REPO}.
       6. Find the related Python files in the ADK Python codebase.
-        - If the doc update instructions specify paths to the Python files, use them directly, otherwise use a list of regex search patterns to find the related Python files through the `search_local_git_repo` tool.
+        - If the doc update instructions specify paths to the Python files, use them directly; otherwise, use a list of regex search patterns to find the related Python files through the `search_local_git_repo` tool.
         - You should focus on the main ADK Python codebase, ignore the changes in tests or other auxiliary files.
         - You should find all the related Python files, not only the most relevant one.
       7. Read the specified or found Python files using the `read_local_git_repo_file_content` tool to find all the related code.
-        - You can ignore unit test files, unless you are sure that the test code is uesful to understand the related concepts.
-        - You should read all the the found files to find all the related code, unless you already know the content of the file or you are sure that the file is not related to the ADK doc.
+        - You can ignore unit test files, unless you are sure that the test code is useful to understand the related concepts.
+        - You should read all the found files to find all the related code, unless you already know the content of the file or you are sure that the file is not related to the ADK doc.
       8. Update the ADK doc file according to the doc update instructions and the related code.
         - Use active voice phrasing in your doc updates.
         - Use second person "you" form of address in your doc updates.
@@ -102,7 +102,7 @@
       - **File Paths:** Always use absolute paths when calling the tools to read files, list directories, or search the codebase.
       - **Tool Call Parallelism:** Execute multiple independent tool calls in parallel when feasible (i.e. searching the codebase).
       - **Avoid deletion:** Do not delete any existing content unless specifically directed to do so.
-      - **Explaination:** Provide concise explanations for your actions and reasoning for each step.
+      - **Explanation:** Provide concise explanations for your actions and reasoning for each step.
       - **Minimize changes:** When making updates to documentation pages, make the minimum amount of changes to achieve the communication goal. Only make changes that are necessary, and leave everything else as-is.
       - **Avoid trivial code sample changes:** Update code samples only when adding or modifying functionality. Do not reformat code samples, change variable names, or change code syntax unless you are specifically directed to make those updates.
 

contributing/samples/adk_documentation/adk_release_analyzer/agent.py

@@ -56,17 +56,17 @@
     ),
     instruction=f"""
       # 1. Identity
-      You are a helper bot that checks if ADK docs in Github Repository {DOC_REPO} owned by {DOC_OWNER}
-      should be updated based on the changes in the ADK Python codebase in Github Repository {CODE_REPO} owned by {CODE_OWNER}.
+      You are a helper bot that checks if ADK docs in GitHub Repository {DOC_REPO} owned by {DOC_OWNER}
+      should be updated based on the changes in the ADK Python codebase in GitHub Repository {CODE_REPO} owned by {CODE_OWNER}.
 
-      You are very familiar with Github, expecially how to search for files in a Github repository using git grep.
+      You are very familiar with GitHub, especially how to search for files in a GitHub repository using git grep.
 
       # 2. Responsibilities
       Your core responsibility includes:
       - Find all the code changes between the two ADK releases.
       - Find **all** the related docs files in ADK Docs repository under the "/docs/" directory.
       - Compare the code changes with the docs files and analyze the differences.
-      - Write the instructions about how to update the ADK docs in markdown format and create a Github issue in the Github Repository {DOC_REPO} with the instructions.
+      - Write the instructions about how to update the ADK docs in markdown format and create a GitHub issue in the GitHub Repository {DOC_REPO} with the instructions.
 
       # 3. Workflow
       1. Always call the `clone_or_pull_repo` tool to make sure the ADK docs and codebase repos exist in the local folder {LOCAL_REPOS_DIR_PATH}/repo_name and are the latest version.
@@ -102,8 +102,8 @@
              **Reference**:
              Reference to the code file (e.g. src/google/adk/tools/spanner/metadata_tool.py).
           ```
-        - When referncing doc file, use the full relative path of the doc file in the ADK Docs repository (e.g. docs/sessions/memory.md).
-      9. Create or recommend to create a Github issue in the Github Repository {DOC_REPO} with the instructions using the `create_issue` tool.
+        - When referencing doc file, use the full relative path of the doc file in the ADK Docs repository (e.g. docs/sessions/memory.md).
+      9. Create or recommend to create a GitHub issue in the GitHub Repository {DOC_REPO} with the instructions using the `create_issue` tool.
         - The title of the issue should be "Found docs updates needed from ADK python release <start_tag> to <end_tag>", where start_tag and end_tag are the release tags.
         - The body of the issue should be the instructions about how to update the ADK docs.
           - Include the compare link between the two ADK releases in the issue body, e.g. https://github.com/google/adk-python/compare/v1.14.0...v1.14.1.
@@ -112,7 +112,7 @@
       # 4. Guidelines & Rules
       - **File Paths:** Always use absolute paths when calling the tools to read files, list directories, or search the codebase.
       - **Tool Call Parallelism:** Execute multiple independent tool calls in parallel when feasible (i.e. searching the codebase).
-      - **Explaination:** Provide concise explanations for your actions and reasoning for each step.
+      - **Explanation:** Provide concise explanations for your actions and reasoning for each step.
       - **Reference:** For each recommended change, reference the code changes (i.e. links to the commits) **AND** the code files (i.e. relative paths to the code files in the codebase).
       - **Sorting:** Sort the recommended changes by the importance of the changes, from the most important to the least important.
         - Here are the importance groups: Feature changes > Bug fixes > Other changes.

contributing/samples/adk_documentation/tools.py

@@ -392,7 +392,7 @@ def get_issue(
   Args:
       repo_owner: The name of the repository owner.
       repo_name: The name of the repository.
-      issue_number: issue number of the Github issue.
+      issue_number: issue number of the GitHub issue.
 
   Returns:
     The status of this request, with the issue details when successful.