Merge branch 'main' into spelling

Author: hangfei

README.md

@@ -155,6 +155,12 @@ We welcome contributions from the community! Whether it's bug reports, feature r
 - [General contribution guideline and flow](https://google.github.io/adk-docs/contributing-guide/).
 - Then if you want to contribute code, please read [Code Contributing Guidelines](./CONTRIBUTING.md) to get started.
 
+## Community Repo
+
+We have [adk-python-community repo](https://github.com/google/adk-python-community)that is home to a growing ecosystem of community-contributed tools, third-party
+service integrations, and deployment scripts that extend the core capabilities
+of the ADK.
+
 ## Vibe Coding
 
 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.

contributing/samples/adk_agent_builder_assistant/instruction_embedded.template

@@ -202,6 +202,19 @@ tools:
 ```
 **DO NOT create Python files like `tools/google_search_tool.py` for built-in tools!**
 
+- **🚫 Tool Hallucination Ban**
+- Use only the built-in tool names enumerated in the **ADK Built-in Tools**
+  list above; never invent additional built-in labels.
+- If you cannot confirm that a tool already exists in this project or in the
+  built-in list, ask the user for confirmation instead of guessing or fabricating
+  the implementation.
+- Do not generate custom helper tools whose only purpose is transferring control
+  to another agent; ADK injects the official `transfer_to_agent` tool
+  automatically when sub-agents are configured. Avoid creating look-alikes such
+  as `transfer_to_agent_tool`.
+- `tool_code` is reserved by some runtimes for code execution. Do not reuse that
+  name for ADK tools or dotted paths.
+
 **Custom Tools** (require Python implementation):
 - **Naming**: Use dotted path: `{{project_folder_name}}.tools.{{module_name}}.{{function_name}}`
 - **Require Python file**: Must create actual Python file in `tools/` directory

contributing/samples/adk_triaging_agent/agent.py

@@ -41,6 +41,33 @@
     "a2a": "seanzhou1023",
 }
 
+LABEL_GUIDELINES = """
+      Label rubric and disambiguation rules:
+      - "documentation": Tutorials, README content, reference docs, or samples.
+      - "services": Session and memory services, persistence layers, or storage
+        integrations.
+      - "web": ADK web UI, FastAPI server, dashboards, or browser-based flows.
+      - "question": Usage questions without a reproducible problem.
+      - "tools": Built-in tools (e.g., SQL utils, code execution) or tool APIs.
+      - "mcp": Model Context Protocol features. Apply both "mcp" and "tools".
+      - "eval": Evaluation framework, test harnesses, scoring, or datasets.
+      - "live": Streaming, bidi, audio, or Gemini Live configuration.
+      - "models": Non-Gemini model adapters (LiteLLM, Ollama, OpenAI, etc.).
+      - "tracing": Telemetry, observability, structured logs, or spans.
+      - "core": Core ADK runtime (Agent definitions, Runner, planners,
+        thinking config, CLI commands, GlobalInstructionPlugin, CPU usage, or
+        general orchestration). Default to "core" when the topic is about ADK
+        behavior and no other label is a better fit.
+      - "agent engine": Vertex AI Agent Engine deployment or sandbox topics
+        only (e.g., `.agent_engine_config.json`, `ae_ignore`, Agent Engine
+        sandbox, `agent_engine_id`). If the issue does not explicitly mention
+        Agent Engine concepts, do not use this label—choose "core" instead.
+      - "a2a": Agent-to-agent workflows, coordination logic, or A2A protocol.
+
+      When unsure between labels, prefer the most specific match. If a label
+      cannot be assigned confidently, do not call the labeling tool.
+"""
+
 APPROVAL_INSTRUCTION = (
     "Do not ask for user approval for labeling! If you can't find appropriate"
     " labels for the issue, do not label it."
@@ -171,18 +198,20 @@ def change_issue_type(issue_number: int, issue_type: str) -> dict[str, Any]:
       You are a triaging bot for the GitHub {REPO} repo with the owner {OWNER}. You will help get issues, and recommend a label.
       IMPORTANT: {APPROVAL_INSTRUCTION}
 
+      {LABEL_GUIDELINES}
+
       Here are the rules for labeling:
       - If the user is asking about documentation-related questions, label it with "documentation".
-      - If it's about session, memory services, label it with "services"
-      - If it's about UI/web, label it with "web"
-      - If the user is asking about a question, label it with "question"
-      - If it's related to tools, label it with "tools"
+      - If it's about session, memory services, label it with "services".
+      - If it's about UI/web, label it with "web".
+      - If the user is asking about a question, label it with "question".
+      - If it's related to tools, label it with "tools".
       - If it's about agent evaluation, then label it with "eval".
       - If it's about streaming/live, label it with "live".
-      - If it's about model support(non-Gemini, like Litellm, Ollama, OpenAI models), label it with "models".
+      - If it's about model support (non-Gemini, like Litellm, Ollama, OpenAI models), label it with "models".
       - If it's about tracing, label it with "tracing".
-      - If it's agent orchestration, agent definition, label it with "core".
-      - If it's about agent engine, label it with "agent engine".
+      - If it's agent orchestration, agent definition, Runner behavior, planners, or performance, label it with "core".
+      - Use "agent engine" only when the issue clearly references Vertex AI Agent Engine deployment artifacts (for example `.agent_engine_config.json`, `ae_ignore`, `agent_engine_id`, or Agent Engine sandbox errors).
       - If it's about Model Context Protocol (e.g. MCP tool, MCP toolset, MCP session management etc.), label it with both "mcp" and "tools".
       - If it's about A2A integrations or workflows, label it with "a2a".
       - If you can't find an appropriate labels for the issue, follow the previous instruction that starts with "IMPORTANT:".
@@ -194,6 +223,14 @@ def change_issue_type(issue_number: int, issue_type: str) -> dict[str, Any]:
       - If the issue is a feature request, change the issue type to "Feature".
       - Otherwise, **do not change the issue type**.
 
+      Response quality requirements:
+      - Summarize the issue in your own words without leaving template
+        placeholders (never output text like "[fill in later]").
+      - Justify the chosen label with a short explanation referencing the issue
+        details.
+      - Mention the assigned owner when a label maps to one.
+      - If no label is applied, clearly state why.
+
       Present the followings in an easy to read format highlighting issue number and your label.
       - the issue summary in a few sentence
       - your label recommendation and justification

contributing/samples/litellm_with_fallback_models/README.md

@@ -0,0 +1,10 @@
+# LiteLLM with Fallback Models
+
+This agent is built for resilience using LiteLLM's built-in fallback mechanism. It automatically switches models to guard against common disruptions like token limit errors and connection failures, while ensuring full conversational context is preserved across all model changes.
+
+To run this example, ensure your .env file includes the following variables:
+```
+GOOGLE_API_KEY=
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+```

contributing/samples/litellm_with_fallback_models/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+from . import agent

contributing/samples/litellm_with_fallback_models/agent.py

@@ -0,0 +1,88 @@
+# 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.
+
+import random
+
+from google.adk import Agent
+from google.adk.models.lite_llm import LiteLlm
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+
+
+def roll_die(sides: int, tool_context: ToolContext) -> int:
+  """Roll a die and return the rolled result.
+
+  Args:
+    sides: The integer number of sides the die has.
+    tool_context: The tool context to use for the die roll.
+
+  Returns:
+    An integer of the result of rolling the die.
+    The result is also stored in the tool context for future use.
+  """
+  result = random.randint(1, sides)
+  if 'rolls' not in tool_context.state:
+    tool_context.state['rolls'] = []
+
+  tool_context.state['rolls'] = tool_context.state['rolls'] + [result]
+  return result
+
+
+async def before_model_callback(callback_context, llm_request):
+  print('@before_model_callback')
+  print(f'Beginning model choice: {llm_request.model}')
+  callback_context.state['beginning_model_choice'] = llm_request.model
+  return None
+
+
+async def after_model_callback(callback_context, llm_response):
+  print('@after_model_callback')
+  print(f'Final model choice: {llm_response.model_version}')
+  callback_context.state['final_model_choice'] = llm_response.model_version
+  return None
+
+
+root_agent = Agent(
+    model=LiteLlm(
+        model='gemini/gemini-2.5-pro',
+        fallbacks=[
+            'anthropic/claude-sonnet-4-5-20250929',
+            'openai/gpt-4o',
+        ],
+    ),
+    name='resilient_agent',
+    description=(
+        'hello world agent that can roll a dice of given number of sides.'
+    ),
+    instruction="""
+      You roll dice and answer questions about the outcome of the dice rolls.
+      You can roll dice of different sizes.
+      It is ok to discuss previous dice roles, and comment on the dice rolls.
+      When you are asked to roll a die, you must call the roll_die tool with the number of sides. Be sure to pass in an integer. Do not pass in a string.
+      You should never roll a die on your own.
+    """,
+    tools=[
+        roll_die,
+    ],
+    generate_content_config=types.GenerateContentConfig(
+        safety_settings=[
+            types.SafetySetting(  # avoid false alarm about rolling dice.
+                category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+                threshold=types.HarmBlockThreshold.OFF,
+            ),
+        ]
+    ),
+    before_model_callback=before_model_callback,
+    after_model_callback=after_model_callback,
+)

contributing/samples/mcp_sse_agent/agent.py

@@ -16,25 +16,27 @@
 import os
 
 from google.adk.agents.llm_agent import LlmAgent
+from google.adk.agents.mcp_instruction_provider import McpInstructionProvider
 from google.adk.tools.mcp_tool.mcp_session_manager import SseConnectionParams
 from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
 
 _allowed_path = os.path.dirname(os.path.abspath(__file__))
 
+connection_params = SseConnectionParams(
+    url='http://localhost:3000/sse',
+    headers={'Accept': 'text/event-stream'},
+)
+
 root_agent = LlmAgent(
     model='gemini-2.0-flash',
     name='enterprise_assistant',
-    instruction=f"""\
-Help user accessing their file systems.
-
-Allowed directory: {_allowed_path}
-    """,
+    instruction=McpInstructionProvider(
+        connection_params=connection_params,
+        prompt_name='file_system_prompt',
+    ),
     tools=[
         MCPToolset(
-            connection_params=SseConnectionParams(
-                url='http://localhost:3000/sse',
-                headers={'Accept': 'text/event-stream'},
-            ),
+            connection_params=connection_params,
             # don't want agent to do write operation
             # you can also do below
             # tool_filter=lambda tool, ctx=None: tool.name

contributing/samples/mcp_sse_agent/filesystem_server.py

@@ -45,6 +45,13 @@ def get_cwd() -> str:
   return str(Path.cwd())
 
 
+# Add a prompt for accessing file systems
+@mcp.prompt(name="file_system_prompt")
+def file_system_prompt() -> str:
+  return f"""\
+Help the user access their file systems."""
+
+
 # Graceful shutdown handler
 async def shutdown(signal, loop):
   """Cleanup tasks tied to the service's shutdown."""

pyproject.toml

@@ -26,13 +26,12 @@ classifiers = [ # List of https://pypi.org/classifiers/
 dependencies = [
   # go/keep-sorted start
   "PyYAML>=6.0.2, <7.0.0",                                   # For APIHubToolset.
-  "absolufy-imports>=0.3.1, <1.0.0",                         # For Agent Engine deployment.
   "anyio>=4.9.0, <5.0.0;python_version>='3.10'",             # For MCP Session Manager
   "authlib>=1.5.1, <2.0.0",                                  # For RestAPI Tool
   "click>=8.1.8, <9.0.0",                                    # For CLI tools
   "fastapi>=0.115.0, <1.119.0",                              # FastAPI framework
   "google-api-python-client>=2.157.0, <3.0.0",               # Google API client discovery
-  "google-cloud-aiplatform[agent_engines]>=1.121.0, <2.0.0", # For VertexAI integrations, e.g. example store.
+  "google-cloud-aiplatform[agent_engines] @ git+https://github.com/googleapis/python-aiplatform.git@bf1851e59cb34e63b509a2a610e72691e1c4ca28", # For VertexAI integrations, e.g. example store.
   "google-cloud-bigtable>=2.32.0",                           # For Bigtable database
   "google-cloud-discoveryengine>=0.13.12, <0.14.0",          # For Discovery Engine Search Tool
   "google-cloud-secret-manager>=2.22.0, <3.0.0",             # Fetching secrets in RestAPI Tool

src/google/adk/agents/__init__.py

@@ -12,6 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import logging
+import sys
+
 from .base_agent import BaseAgent
 from .invocation_context import InvocationContext
 from .live_request_queue import LiveRequest
@@ -35,3 +38,16 @@
     'LiveRequestQueue',
     'RunConfig',
 ]
+
+if sys.version_info < (3, 10):
+  logger = logging.getLogger('google_adk.' + __name__)
+  logger.warning(
+      'MCP requires Python 3.10 or above. Please upgrade your Python'
+      ' version in order to use it.'
+  )
+else:
+  from .mcp_instruction_provider import McpInstructionProvider
+
+  __all__.extend([
+      'McpInstructionProvider',
+  ])