ADK changes

Co-authored-by: Xuan Yang <xygoogle@google.com>
COPYBARA_INTEGRATE_REVIEW=google#6187 from vaibhav-patel:fix/5871-a2a-hitl-sample 028cee9
PiperOrigin-RevId: 945223172

Author: 2 people

.github/workflows/pr-triage.yml

@@ -15,8 +15,14 @@
 name: ADK Pull Request Triaging Agent
 
 on:
+  # React within seconds of a PR opening/updating so the owner is assigned
+  # promptly. pull_request_target (not pull_request) is required so the run has
+  # the base-repo token needed to assign on community fork PRs; this workflow
+  # only reads PR metadata via the API and never checks out untrusted PR code.
+  pull_request_target:
+    types: [opened, reopened, synchronize, ready_for_review]
   schedule:
-    # Run every 6 hours
+    # Backfill every 6 hours in case an event was missed.
     - cron: '0 */6 * * *'
   workflow_dispatch:
     inputs:
@@ -30,6 +36,12 @@ on:
         default: '10'
         type: 'string'
 
+# Never let two runs triage the same PR at once (e.g. rapid pushes); the
+# scheduled backfill still runs under its own group.
+concurrency:
+  group: pr-triage-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: false
+
 jobs:
   agent-triage-pull-request:
     if: github.repository == 'google/adk-python'

contributing/samples/a2a/a2a_human_in_loop/README.md

@@ -54,14 +54,14 @@ The A2A Human-in-the-Loop sample consists of:
 
    ```bash
    # Start the remote a2a server that serves the human-in-the-loop approval agent on port 8001
-   adk api_server --a2a --port 8001 contributing/samples/a2a_human_in_loop/remote_a2a
+   adk api_server --a2a --port 8001 contributing/samples/a2a/a2a_human_in_loop/remote_a2a
    ```
 
 1. **Run the Main Agent**:
 
    ```bash
    # In a separate terminal, run the adk web server
-   adk web contributing/samples/
+   adk web contributing/samples/a2a
    ```
 
 ### Example Interactions
@@ -82,10 +82,24 @@ Agent: ✅ Reimbursement approved and processed: $50 for meals
 User: Please reimburse $200 for conference travel
 Agent: I'll process your reimbursement request for $200 for conference travel. Since this amount exceeds $100, I need to get manager approval.
 Agent: 🔄 Request submitted for approval (Ticket: reimbursement-ticket-001). Please wait for manager review.
-[Human manager interacts with root agent to approve the request]
+[Human manager approves the pending request from the ADK Web UI]
 Agent: ✅ Great news! Your reimbursement has been approved by the manager. Processing $200 for conference travel.
 ```
 
+> **Approving from the ADK Web UI:** The approval is a *long-running tool* call
+> that runs on the remote approval agent. The pending call is surfaced in the
+> Web UI as a function call awaiting a response. To approve (or reject), hover
+> over the pending `ask_for_approval` function response in the UI and use
+> **"Send another response"** to send back an updated response such as
+> `{"status": "approved", "ticketId": "reimbursement-ticket-001"}`. Simply
+> typing "I approve" as a chat message will **not** resume the pending request,
+> because the framework needs a `FunctionResponse` that carries the same call
+> `id` to resume the long-running tool.
+>
+> For this resume to be routed back to the remote approval agent (rather than
+> restarting at the root agent), the sample is exposed as an `App` with
+> `ResumabilityConfig(is_resumable=True)` in `agent.py`.
+
 ## Code Structure
 
 ### Main Agent (`agent.py`)

contributing/samples/a2a/a2a_human_in_loop/agent.py

@@ -16,6 +16,8 @@
 from google.adk.agents.llm_agent import Agent
 from google.adk.agents.remote_a2a_agent import AGENT_CARD_WELL_KNOWN_PATH
 from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
+from google.adk.apps import App
+from google.adk.apps import ResumabilityConfig
 from google.genai import types
 
 
@@ -49,3 +51,18 @@ def reimburse(purpose: str, amount: float) -> str:
     sub_agents=[approval_agent],
     generate_content_config=types.GenerateContentConfig(temperature=0.1),
 )
+
+# The human-in-the-loop approval runs as a long-running tool on the remote
+# approval_agent. When the manager approves (or rejects) the request, the ADK
+# Web UI sends back a FunctionResponse for that pending long-running call. For
+# the next turn to be routed back to the (remote) approval_agent so it can
+# resume the paused tool instead of restarting at the root reimbursement_agent,
+# the app must be resumable. Without this, the confirmation is delivered to the
+# root agent, which has no pending call, and nothing happens (see issue #5871).
+app = App(
+    name='a2a_human_in_loop',
+    root_agent=root_agent,
+    resumability_config=ResumabilityConfig(
+        is_resumable=True,
+    ),
+)

contributing/samples/adk_team/adk_pr_triaging_agent/agent.py

@@ -22,6 +22,7 @@
 from adk_pr_triaging_agent.utils import error_response
 from adk_pr_triaging_agent.utils import get_diff
 from adk_pr_triaging_agent.utils import get_request
+from adk_pr_triaging_agent.utils import is_assignable
 from adk_pr_triaging_agent.utils import post_request
 from adk_pr_triaging_agent.utils import read_file
 from adk_pr_triaging_agent.utils import run_graphql_query
@@ -41,17 +42,34 @@
     "web",
 ]
 
+# Component label -> GitHub login of the owner who shepherds that component.
+# The owner becomes the PR's assignee so the contributor can see who is
+# handling their PR. github login != corp ldap, so this is the login form. Keep
+# in sync with the OWNERS file (the authority) and adk_triaging_agent's map.
+LABEL_TO_OWNER = {
+    "documentation": "joefernandez",
+    "services": "DeanChensj",
+    "tools": "xuanyang15",
+    "mcp": "wukath",
+    "eval": "ankursharmas",
+    "live": "wuliang229",
+    "models": "xuanyang15",
+    "tracing": "jawoszek",
+    "core": "DeanChensj",
+    "web": "wyf7107",
+}
+
 CONTRIBUTING_MD = read_file(
     Path(__file__).resolve().parents[4] / "CONTRIBUTING.md"
 )
 
 APPROVAL_INSTRUCTION = (
-    "Do not ask for user approval for labeling or commenting! If you can't find"
-    " appropriate labels for the PR, do not label it."
+    "Do not ask for user approval for labeling, commenting, or assigning!"
+    " If you can't find appropriate labels for the PR, do not label it."
 )
 if IS_INTERACTIVE:
   APPROVAL_INSTRUCTION = (
-      "Only label or comment when the user approves the labeling or commenting!"
+      "Only label, comment, or assign when the user approves the action!"
   )
 
 
@@ -82,6 +100,11 @@ def get_pull_request_details(pr_number: int) -> str:
               name
             }
           }
+          assignees(first: 10) {
+            nodes {
+              login
+            }
+          }
           files(last: 50) {
             nodes {
               path
@@ -194,6 +217,48 @@ def add_label_to_pr(pr_number: int, label: str) -> dict[str, Any]:
   }
 
 
+def assign_owner_to_pr(pr_number: int, label: str) -> dict[str, Any]:
+  """Assign the component owner (the shepherd) to a PR based on its label.
+
+  The owner is looked up from `LABEL_TO_OWNER` so the contributor can see who is
+  shepherding their PR. GitHub only allows assigning users with
+  repo write/triage access, so a non-assignable owner is reported as skipped
+  rather than silently dropped.
+
+  Args:
+    pr_number: the number of the GitHub pull request
+    label: the component label the PR was triaged into
+
+  Returns:
+    The status of this request, with the assigned owner when successful.
+  """
+  owner = LABEL_TO_OWNER.get(label)
+  if not owner:
+    return error_response(f"Error: no owner mapped for label '{label}'.")
+  print(f"Attempting to assign owner '{owner}' to PR #{pr_number}")
+  if not is_assignable(owner):
+    return {
+        "status": "skipped",
+        "reason": f"'{owner}' is not assignable (needs repo access)",
+        "owner": owner,
+    }
+
+  # Pull Request is a special issue in GitHub, so we can use the issue url.
+  assignee_url = (
+      f"{GITHUB_BASE_URL}/repos/{OWNER}/{REPO}/issues/{pr_number}/assignees"
+  )
+  try:
+    response = post_request(assignee_url, {"assignees": [owner]})
+  except requests.exceptions.RequestException as e:
+    return error_response(f"Error: {e}")
+
+  return {
+      "status": "success",
+      "assigned_owner": owner,
+      "response": response,
+  }
+
+
 def add_comment_to_pr(pr_number: int, comment: str) -> dict[str, Any]:
   """Add the specified comment to the given PR number.
 
@@ -282,6 +347,7 @@ def list_untriaged_pull_requests(pr_count: int) -> dict[str, Any]:
       Your core responsibility includes:
       - Get the pull request details.
       - Add a label to the pull request.
+      - Assign the component owner (the shepherd) to the pull request.
       - Check if the pull request is following the contribution guidelines.
       - Add a comment to the pull request if it's not following the guidelines.
 
@@ -337,17 +403,23 @@ def list_untriaged_pull_requests(pr_count: int) -> dict[str, Any]:
         - Check if the PR is following the contribution guidelines.
           - If it's not following the guidelines, recommend or add a comment to the PR that points to the contribution guidelines (https://github.com/google/adk-python/blob/main/CONTRIBUTING.md).
           - If it's following the guidelines, recommend or add a label to the PR.
+        - After you add a component label, assign the component owner (the shepherd) to the PR:
+          - Call `assign_owner_to_pr` with the same label you applied.
+          - Skip assignment if the PR already has an assignee.
+          - If the tool reports the owner is not assignable, just note it; do not comment about it.
 
       # 5. Output
       Present the following in an easy to read format highlighting PR number and your label.
       - The PR summary in a few sentence
       - The label you recommended or added with the justification
+      - The owner you assigned (or why you did not)
       - The comment you recommended or added to the PR with the justification
     """,
     tools=[
         list_untriaged_pull_requests,
         get_pull_request_details,
         add_label_to_pr,
+        assign_owner_to_pr,
         add_comment_to_pr,
     ],
 )

contributing/samples/adk_team/adk_pr_triaging_agent/utils.py

@@ -15,8 +15,11 @@
 import sys
 from typing import Any
 
+from adk_pr_triaging_agent.settings import GITHUB_BASE_URL
 from adk_pr_triaging_agent.settings import GITHUB_GRAPHQL_URL
 from adk_pr_triaging_agent.settings import GITHUB_TOKEN
+from adk_pr_triaging_agent.settings import OWNER
+from adk_pr_triaging_agent.settings import REPO
 from google.adk.agents.run_config import RunConfig
 from google.adk.runners import Runner
 from google.genai import types
@@ -66,6 +69,16 @@ def post_request(url: str, payload: Any) -> dict[str, Any]:
   return response.json()
 
 
+def is_assignable(login: str) -> bool:
+  """Whether a GitHub user can be assigned to an issue/PR in this repo."""
+  # GitHub only allows assignees with repo write/triage access and silently
+  # drops others from an assignee POST; check first so callers can report the
+  # skip instead of a silent no-op.
+  url = f"{GITHUB_BASE_URL}/repos/{OWNER}/{REPO}/assignees/{login}"
+  response = requests.get(url, headers=headers, timeout=60)
+  return response.status_code == 204
+
+
 def error_response(error_message: str) -> dict[str, Any]:
   """Returns an error response."""
   return {"status": "error", "error_message": error_message}

src/google/adk/environment/_local_environment.py

@@ -142,11 +142,16 @@ async def write_file(self, path: str | Path, content: str | bytes) -> None:
     return await asyncio.to_thread(self._sync_write, resolved, content)
 
   def _resolve_path(self, path: str | Path) -> Path:
-    """Resolve a relative path against the working directory."""
-    path_obj = Path(path)
-    if path_obj.is_absolute():
-      return path_obj
-    return self.working_dir / path_obj
+    """Resolve a file path inside the working directory."""
+    candidate = Path(path)
+    working_dir = self.working_dir.resolve()
+    if not candidate.is_absolute():
+      candidate = working_dir / candidate
+
+    resolved = candidate.resolve()
+    if not resolved.is_relative_to(working_dir):
+      raise ValueError(f'Path escapes working directory: {path}')
+    return resolved
 
   @staticmethod
   def _sync_read(path: Path) -> bytes:

src/google/adk/tools/transfer_to_agent_tool.py

@@ -28,10 +28,10 @@
 #   function directly. TransferToAgentTool provides additional enum constraints
 #   that prevent LLMs from hallucinating invalid agent names.
 def transfer_to_agent(agent_name: str, tool_context: ToolContext) -> None:
-  """Transfer the question to another agent.
+  """Transfer the query to another agent.
 
   Use this tool to hand off control to another agent that is more suitable to
-  answer the user's question according to the agent's description.
+  answer the user's query according to the agent's description.
 
   Args:
     agent_name: the agent name to transfer to.

tests/unittests/tools/test_local_environment.py

@@ -76,6 +76,39 @@ async def test_write_creates_parent_dirs(self, env: LocalEnvironment):
     data = await env.read_file("sub/dir/file.txt")
     assert data == b"nested"
 
+  @pytest.mark.asyncio
+  async def test_absolute_path_inside_working_dir(self, env: LocalEnvironment):
+    """Absolute paths are accepted when they stay inside the workspace."""
+    path = env.working_dir / "absolute.txt"
+    await env.write_file(path, "absolute")
+    data = await env.read_file(path)
+    assert data == b"absolute"
+
+  @pytest.mark.asyncio
+  async def test_rejects_relative_path_escape(self, env: LocalEnvironment):
+    """Parent traversal cannot escape the workspace."""
+    outside = env.working_dir.parent / "outside.txt"
+    outside.write_text("secret", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="escapes working directory"):
+      await env.read_file(Path("..") / outside.name)
+
+    with pytest.raises(ValueError, match="escapes working directory"):
+      await env.write_file(Path("..") / "write-outside.txt", "nope")
+
+    assert not (env.working_dir.parent / "write-outside.txt").exists()
+
+  @pytest.mark.asyncio
+  async def test_rejects_absolute_path_outside_working_dir(
+      self, env: LocalEnvironment
+  ):
+    """Absolute paths outside the workspace are rejected."""
+    outside = env.working_dir.parent / "outside-absolute.txt"
+    outside.write_text("secret", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="escapes working directory"):
+      await env.read_file(outside)
+
   @pytest.mark.asyncio
   async def test_read_nonexistent_raises(self, env: LocalEnvironment):
     """Reading a missing file raises FileNotFoundError."""

tests/unittests/tools/test_transfer_to_agent_tool.py

@@ -120,7 +120,7 @@ def test_transfer_to_agent_tool_preserves_description():
 
   assert decl is not None
   assert decl.description is not None
-  assert 'Transfer the question to another agent' in decl.description
+  assert 'Transfer the query to another agent' in decl.description
 
 
 def test_transfer_to_agent_tool_maintains_inheritance():