Merge branch 'google:main' into main

Author: ayam04

.github/workflows/copybara-pr-handler.yml

@@ -0,0 +1,134 @@
+name: Copybara PR Handler
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to close (for testing)'
+        required: true
+        type: string
+      commit_sha:
+        description: 'Commit SHA reference (optional, for testing)'
+        required: false
+        type: string
+
+jobs:
+  close-imported-pr:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      issues: write
+      contents: read
+
+    steps:
+      - name: Check for Copybara commits and close PRs
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.ADK_TRIAGE_AGENT }}
+          script: |
+            // Check if this is a manual test run
+            const isManualRun = context.eventName === 'workflow_dispatch';
+
+            let prsToClose = [];
+
+            if (isManualRun) {
+              // Manual testing mode
+              const prNumber = parseInt(context.payload.inputs.pr_number);
+              const commitSha = context.payload.inputs.commit_sha || context.sha.substring(0, 7);
+
+              console.log('=== MANUAL TEST MODE ===');
+              console.log(`Testing with PR #${prNumber}, commit ${commitSha}`);
+
+              prsToClose.push({ prNumber, commitSha });
+            } else {
+              // Normal mode: process commits from push event
+              const commits = context.payload.commits || [];
+              console.log(`Found ${commits.length} commit(s) in this push`);
+
+              // Process each commit
+              for (const commit of commits) {
+                const sha = commit.id;
+                const committer = commit.committer.name;
+                const message = commit.message;
+
+                console.log(`\n--- Processing commit ${sha.substring(0, 7)} ---`);
+                console.log(`Committer: ${committer}`);
+
+                // Check if this is a Copybara commit
+                if (committer !== 'Copybara-Service') {
+                  console.log('Not a Copybara commit, skipping');
+                  continue;
+                }
+
+                // Extract PR number from commit message
+                // Pattern: "Merge https://github.com/google/adk-python/pull/3333"
+                const prMatch = message.match(/Merge https:\/\/github\.com\/google\/adk-python\/pull\/(\d+)/);
+
+                if (!prMatch) {
+                  console.log('No PR number found in Copybara commit message');
+                  continue;
+                }
+
+                const prNumber = parseInt(prMatch[1]);
+                const commitSha = sha.substring(0, 7);
+
+                prsToClose.push({ prNumber, commitSha });
+              }
+            }
+
+            // Process PRs to close
+            for (const { prNumber, commitSha } of prsToClose) {
+              console.log(`\n--- Processing PR #${prNumber} ---`);
+
+              // Get PR details to check if it's open
+              let pr;
+              try {
+                pr = await github.rest.pulls.get({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: prNumber
+                });
+              } catch (error) {
+                console.log(`PR #${prNumber} not found or inaccessible:`, error.message);
+                continue;
+              }
+
+              // Only close if PR is still open
+              if (pr.data.state !== 'open') {
+                console.log(`PR #${prNumber} is already ${pr.data.state}, skipping`);
+                continue;
+              }
+
+              const author = pr.data.user.login;
+
+              try {
+                // Add comment with commit reference
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: prNumber,
+                  body: `Thank you @${author} for your contribution! 🎉\n\nYour changes have been successfully imported and merged via Copybara in commit ${commitSha}.\n\nClosing this PR as the changes are now in the main branch.`
+                });
+
+                // Close the PR
+                await github.rest.pulls.update({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: prNumber,
+                  state: 'closed'
+                });
+
+                console.log(`Successfully closed PR #${prNumber}`);
+              } catch (error) {
+                console.log(`Error closing PR #${prNumber}:`, error.message);
+              }
+            }
+
+            if (isManualRun) {
+              console.log('\n=== TEST COMPLETED ===');
+            } else {
+              console.log('\n--- Finished processing all commits ---');
+            }

README.md

@@ -11,7 +11,7 @@
       <img src="https://raw.githubusercontent.com/google/adk-python/main/assets/agent-development-kit.png" width="256"/>
     </h2>
     <h3 align="center">
-      An open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
+      An open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
     </h3>
     <h3 align="center">
       Important Links:
@@ -22,7 +22,11 @@
     </h3>
 </html>
 
-Agent Development Kit (ADK) is a flexible and modular framework for developing and deploying AI agents. While optimized for Gemini and the Google ecosystem, ADK is model-agnostic, deployment-agnostic, and is built for compatibility with other frameworks. ADK was designed to make agent development feel more like software development, to make it easier for developers to create, deploy, and orchestrate agentic architectures that range from simple tasks to complex workflows.
+Agent Development Kit (ADK) is a flexible and modular framework that applies
+software development principles to AI agent creation. It is designed to
+simplify building, deploying, and orchestrating agent workflows, from simple
+tasks to complex systems. While optimized for Gemini, ADK is model-agnostic,
+deployment-agnostic, and compatible with other frameworks.
 
 ---
 
@@ -37,7 +41,7 @@ Agent Development Kit (ADK) is a flexible and modular framework for developing a
 ## ✨ Key Features
 
 - **Rich Tool Ecosystem**: Utilize pre-built tools, custom functions,
-  OpenAPI specs, or integrate existing tools to give agents diverse
+  OpenAPI specs, MCP tools or integrate existing tools to give agents diverse
   capabilities, all for tight integration with the Google ecosystem.
 
 - **Code-First Development**: Define agent logic, tools, and orchestration
@@ -54,13 +58,6 @@ Agent Development Kit (ADK) is a flexible and modular framework for developing a
 - **Deploy Anywhere**: Easily containerize and deploy agents on Cloud Run or
   scale seamlessly with Vertex AI Agent Engine.
 
-## 🤖 Agent2Agent (A2A) Protocol and ADK Integration
-
-For remote agent-to-agent communication, ADK integrates with the
-[A2A protocol](https://github.com/google-a2a/A2A/).
-See this [example](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents)
-for how they can work together.
-
 ## 🚀 Installation
 
 ### Stable Release (Recommended)
@@ -84,6 +81,13 @@ pip install git+https://github.com/google/adk-python.git@main
 
 Note: The development version is built directly from the latest code commits. While it includes the newest fixes and features, it may also contain experimental changes or bugs not present in the stable release. Use it primarily for testing upcoming changes or accessing critical fixes before they are officially released.
 
+## 🤖 Agent2Agent (A2A) Protocol and ADK Integration
+
+For remote agent-to-agent communication, ADK integrates with the
+[A2A protocol](https://github.com/google-a2a/A2A/).
+See this [example](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents)
+for how they can work together.
+
 ## 📚 Documentation
 
 Explore the full documentation for detailed guides on building, evaluating, and

contributing/samples/mcp_server_side_sampling/README.md

@@ -0,0 +1,51 @@
+# FastMCP Server-Side Sampling with ADK
+
+This project demonstrates how to use server-side sampling with a `fastmcp` server connected to an ADK `MCPToolset`.
+
+## Description
+
+The setup consists of two main components:
+
+1.  **ADK Agent (`agent.py`):** An `LlmAgent` is configured with an `MCPToolset`. This toolset connects to a local `fastmcp` server.
+2.  **FastMCP Server (`mcp_server.py`):** A `fastmcp` server that exposes a single tool, `analyze_sentiment`. This server is configured to use its own LLM for sampling, independent of the ADK agent's LLM.
+
+The flow is as follows:
+1.  The user provides a text prompt to the ADK agent.
+2.  The agent decides to use the `analyze_sentiment` tool from the `MCPToolset`.
+3.  The tool call is sent to the `mcp_server.py`.
+4.  Inside the `analyze_sentiment` tool, `ctx.sample()` is called. This delegates an LLM call to the `fastmcp` server's own sampling handler.
+5.  The `mcp_server`'s LLM processes the prompt from `ctx.sample()` and returns the result to the server.
+6.  The server processes the LLM response and returns the final sentiment to the agent.
+7.  The agent displays the result to the user.
+
+## Steps to Run
+
+### Prerequisites
+
+- Python 3.10+
+- `google-adk` library installed.
+- A configured OpenAI API key.
+
+### 1. Set up the Environment
+
+Clone the project and navigate to the directory. Make sure your `OPENAI_API_KEY` is available as an environment variable.
+
+### 2. Install Dependencies
+
+Install the required Python libraries:
+
+```bash
+pip install fastmcp openai litellm
+```
+
+### 3. Run the Example
+
+Navigate to the `samples` directory and choose this ADK agent:
+
+```bash
+adk web .
+```
+
+The agent will automatically start the FastMCP server in the background.
+
+- **Sample user prompt:** "What is the sentiment of 'I love building things with Python'?"

contributing/samples/mcp_server_side_sampling/__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/mcp_server_side_sampling/agent.py

@@ -0,0 +1,56 @@
+# 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 os
+
+from google.adk.agents import LlmAgent
+from google.adk.models.lite_llm import LiteLlm
+from google.adk.tools.mcp_tool import MCPToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
+from mcp import StdioServerParameters
+
+# This example uses the OpenAI API for both the agent and the server.
+# Ensure your OPENAI_API_KEY is available as an environment variable.
+api_key = os.getenv('OPENAI_API_KEY')
+if not api_key:
+  raise ValueError('The OPENAI_API_KEY environment variable must be set.')
+
+# Configure the StdioServerParameters to start the mcp_server.py script
+# as a subprocess. The OPENAI_API_KEY is passed to the server's environment.
+server_params = StdioServerParameters(
+    command='python',
+    args=['mcp_server.py'],
+    env={'OPENAI_API_KEY': api_key},
+)
+
+# Create the ADK MCPToolset, which connects to the FastMCP server.
+# The `tool_filter` ensures that only the 'analyze_sentiment' tool is exposed
+# to the agent.
+mcp_toolset = MCPToolset(
+    connection_params=StdioConnectionParams(
+        server_params=server_params,
+    ),
+    tool_filter=['analyze_sentiment'],
+)
+
+# Define the ADK agent that uses the MCP toolset.
+root_agent = LlmAgent(
+    model=LiteLlm(model='openai/gpt-4o'),
+    name='SentimentAgent',
+    instruction=(
+        'You are an expert at analyzing text sentiment. Use the'
+        ' analyze_sentiment tool to classify user input.'
+    ),
+    tools=[mcp_toolset],
+)