ADK changes

PiperOrigin-RevId: 988228337
copybara-service · Sep 25, 2026 · Sep 29, 2026 · bd1b9e194d55f0b1b6c2f08a8d8a1f0def4dac6f
commit bd1b9e194d55f0b1b6c2f08a8d8a1f0def4dac6f
diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md
@@ -0,0 +1,4 @@
+# Gemini Code Assist Customization
+
+_Placeholder - customization for Gemini Code Assist in this repository is coming
+soon._
diff --git a/.github/workflows/analyze-releases-for-adk-docs-updates.yml b/.github/workflows/analyze-releases-for-adk-docs-updates.yml
@@ -23,7 +23,7 @@
 
 jobs:
   analyze-new-release-for-adk-docs-updates:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     # Dry-run reads only (this repo + the public docs repo) and skips writes, so
     # the built-in GITHUB_TOKEN suffices. For --no-dry-run, use a PAT with write
     # access to the docs repo.
@@ -32,16 +32,16 @@

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Set up Java
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'

      - name: Cache Maven packages
        uses: actions/cache@v5
        with:
          path: ~/.m2/repository
          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}

diff --git a/.github/workflows/pr-commit-check.yml b/.github/workflows/pr-commit-check.yml
@@ -12,16 +12,16 @@

 # Defines the jobs that will run as part of the workflow.
 jobs:
   check-commit-count:
-    # The type of runner that the job will run on. 'ubuntu-latest' is a good default.
-    runs-on: ubuntu-latest
+    # The type of runner that the job will run on, pinned to a fixed Ubuntu release.
+    runs-on: ubuntu-24.04
 
     # The steps that will be executed as part of the job.
     steps:
      # Step 1: Check out the code
      # This action checks out your repository under $GITHUB_WORKSPACE, so your workflow can access it.
      - name: Checkout Code
        uses: actions/checkout@v6
        with:
          # We need to fetch all commits to accurately count them.
          # '0' means fetch all history for all branches and tags.
@@ -47,7 +47,7 @@
        if: steps.count_commits.outputs.commit_count > 1
        # If the condition is met, the workflow will exit with a failure status.
        run: |
          echo "This pull request has ${{ steps.count_commits.outputs.commit_count }} commits."
          echo "Please squash them into a single commit before merging."
          echo "You can use git rebase -i HEAD~N"
          echo "...where N is the number of commits you want to squash together. The PR check conveniently tells you this number! For example, if the check says you have 3 commits, you would run: git rebase -i HEAD~3."

diff --git a/.github/workflows/pr-title-check.yml b/.github/workflows/pr-title-check.yml
@@ -13,7 +13,7 @@ permissions:
 
 jobs:
   check-pr-title:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Validate Conventional Commit title
         env:

diff --git a/.github/workflows/pr-triage-adk-java.yml b/.github/workflows/pr-triage-adk-java.yml
@@ -20,7 +20,7 @@
 # this repository (see the sample's README for the full threat model).
 name: ADK PR Triaging Agent

 on:
  pull_request_target:
    types: [opened, reopened, edited]
  workflow_dispatch:
@@ -44,7 +44,7 @@
 
 jobs:
   agent-triage-pull-request:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     # Only run on the upstream repo, for newly-opened/reopened/edited PRs or a
     # manual dispatch.
     if: >-
@@ -61,10 +61,10 @@
    steps:
      # Default checkout: the base branch (trusted code), NOT the PR head.
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Set up Java
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'

diff --git a/.github/workflows/release-please.yaml b/.github/workflows/release-please.yaml
@@ -10,8 +10,8 @@
 name: release-please
 jobs:
   release-please:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: googleapis/release-please-action@v4
         with:
          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
diff --git a/.github/workflows/spam-detection-adk-java-issues.yml b/.github/workflows/spam-detection-adk-java-issues.yml
@@ -41,7 +41,7 @@
 
 jobs:
   agent-scan-issues:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     # Only run on the upstream repo, for newly-opened issues, the scheduled
     # sweep, or a manual dispatch.
     if: >-
@@ -56,10 +56,10 @@

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Set up Java
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'

diff --git a/.github/workflows/stale-adk-java-issues.yml b/.github/workflows/stale-adk-java-issues.yml
@@ -34,7 +34,7 @@ concurrency:
 
 jobs:
   agent-audit-stale-issues:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     # Only run on the upstream repo, on the daily schedule or a manual dispatch.
     if: >-
       github.repository == 'google/adk-java' && (

diff --git a/.github/workflows/triage-adk-java-issues.yml b/.github/workflows/triage-adk-java-issues.yml
@@ -32,7 +32,7 @@ concurrency:
 
 jobs:
   agent-triage-issues:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     # Only run on the upstream repo, for newly-opened issues, the scheduled
     # batch sweep, or a manual dispatch.
     if: >-

diff --git a/.github/workflows/validation.yml b/.github/workflows/validation.yml
@@ -11,8 +11,8 @@
  cancel-in-progress: true
 
 jobs:
   build-modules:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 30
     strategy:
       matrix:

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,4 @@
+# AGENTS.md
+
+_Placeholder - guidance for AI coding agents working in this repository is coming
+soon._
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+See [AGENTS.md](./AGENTS.md) for project context, commands, and contribution guidelines for AI coding agents.
diff --git a/a2a/src/main/java/com/google/adk/a2a/agent/RemoteA2AAgent.java b/a2a/src/main/java/com/google/adk/a2a/agent/RemoteA2AAgent.java
@@ -317,8 +317,6 @@ synchronized void handleError(String message, Throwable e) {
       emitter.tryOnError(new A2AClientError(message, e));
     }
 
-    // TODO: b/483038527 - The synchronized block might block the thread, we should optimize for
-    // performance in the future.
     synchronized void handleEvent(ClientEvent clientEvent, AgentCard unused) {
       // Mark the flow as done if it is already cancelled.
       if (!done) {

diff --git a/...estore-session-service/src/main/java/com/google/adk/sessions/FirestoreSessionService.java b/...estore-session-service/src/main/java/com/google/adk/sessions/FirestoreSessionService.java
@@ -21,7 +21,9 @@
 import com.google.adk.utils.Constants;
 import com.google.api.core.ApiFuture;
 import com.google.api.core.ApiFutures;
+import com.google.api.gax.rpc.AlreadyExistsException;
 import com.google.cloud.firestore.CollectionReference;
+import com.google.cloud.firestore.DocumentReference;
 import com.google.cloud.firestore.DocumentSnapshot;
 import com.google.cloud.firestore.Firestore;
 import com.google.cloud.firestore.Query;
@@ -48,9 +50,10 @@
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.ExecutionException;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.regex.Matcher;
-import javax.annotation.Nullable;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -73,6 +76,9 @@ public class FirestoreSessionService implements BaseSessionService {
   private static final String UPDATE_TIME_KEY = Constants.KEY_UPDATE_TIME;
   private static final String TIMESTAMP_KEY = Constants.KEY_TIMESTAMP;
 
+  /** Random token each create stores, so a retried create can detect its own write. */
+  static final String CREATE_TOKEN_KEY = "createToken";
+
   /** Constructor for FirestoreSessionService. */
   public FirestoreSessionService(Firestore firestore) {
     this.firestore = firestore;
@@ -96,7 +102,10 @@ public Single<Session> createSession(
     return createSession(appName, userId, (Map<String, Object>) state, sessionId);
   }
 
-  /** Creates a new session in Firestore. */
+  /**
+   * Creates a new session in Firestore. Session IDs are unique per user across apps, so creating
+   * one the user already has under any app fails with {@link SessionException}.
+   */
   @Override
   public Single<Session> createSession(
       String appName,
@@ -139,11 +148,22 @@ public Single<Session> createSession(
           sessionData.put(USER_ID_KEY, newSession.userId());
           sessionData.put(UPDATE_TIME_KEY, newSession.lastUpdateTime().toString());
           sessionData.put(STATE_KEY, newSession.state());
-
-          // Asynchronously write to Firestore and wait for the result
-          ApiFuture<WriteResult> future =
-              getSessionsCollection(userId).document(resolvedSessionId).set(sessionData);
-          future.get(); // Block until the write is complete
+          String createToken = UUID.randomUUID().toString();
+          sessionData.put(CREATE_TOKEN_KEY, createToken);
+
+          // Unlike set(), create() fails if the session already exists instead of replacing it.
+          DocumentReference sessionDoc = getSessionsCollection(userId).document(resolvedSessionId);
+          try {
+            sessionDoc.create(sessionData).get();
+          } catch (ExecutionException e) {
+            if (!(e.getCause() instanceof AlreadyExistsException)) {
+              throw e;
+            }
+            // A retry after a lost reply fails on this call's own write; its token means success.
+            if (!createToken.equals(sessionDoc.get().get().getString(CREATE_TOKEN_KEY))) {
+              throw new SessionException(SessionException.SESSION_ALREADY_EXISTS, e.getCause());
+            }
+          }
 
           return newSession;
         });

diff --git a/...tore-session-service/src/test/java/com/google/adk/runner/FirestoreDatabaseRunnerTest.java b/...tore-session-service/src/test/java/com/google/adk/runner/FirestoreDatabaseRunnerTest.java
@@ -175,7 +175,8 @@ void run_withUserInput_createsSessionAndExecutesAgent() throws Exception {
     when(mockUserDocRef.collection(anyString())).thenReturn(mockSessionsCollection);
     when(mockSessionsCollection.document(anyString())).thenReturn(mockSessionDocRef);
 
-    when(mockSessionDocRef.set(anyMap())).thenReturn(ApiFutures.immediateFuture(mockWriteResult));
+    when(mockSessionDocRef.create(anyMap()))
+        .thenReturn(ApiFutures.immediateFuture(mockWriteResult));
     when(mockSessionDocRef.update(anyMap()))
         .thenReturn(ApiFutures.immediateFuture(mockWriteResult));
     // Mock the event sub-collection chain

diff --git a/...re-session-service/src/test/java/com/google/adk/sessions/FirestoreSessionServiceTest.java b/...re-session-service/src/test/java/com/google/adk/sessions/FirestoreSessionServiceTest.java
@@ -31,6 +31,10 @@
 import com.google.adk.events.EventActions;
 import com.google.adk.utils.Constants;
 import com.google.api.core.ApiFutures;
+import com.google.api.gax.grpc.GrpcStatusCode;
+import com.google.api.gax.rpc.AlreadyExistsException;
+import com.google.api.gax.rpc.PermissionDeniedException;
+import com.google.api.gax.rpc.UnavailableException;
 import com.google.cloud.firestore.CollectionReference;
 import com.google.cloud.firestore.DocumentReference;
 import com.google.cloud.firestore.DocumentSnapshot;
@@ -45,17 +49,20 @@
 import com.google.common.collect.ImmutableMap;
 import com.google.genai.types.Content;
 import com.google.genai.types.Part;
+import io.grpc.Status;
 import io.reactivex.rxjava3.observers.TestObserver;
 import java.time.Instant;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutionException;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.ArgumentCaptor;
+import org.mockito.Captor;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 
@@ -89,6 +96,7 @@ public class FirestoreSessionServiceTest {
   @Mock private QuerySnapshot mockQuerySnapshot;
   @Mock private WriteResult mockWriteResult;
   @Mock private WriteBatch mockWriteBatch;
+  @Captor private ArgumentCaptor<Map<String, Object>> sessionDataCaptor;
 
   private FirestoreSessionService sessionService;
 
@@ -130,7 +138,7 @@ public void setup() {
 
     // Default mock for writes
     lenient()
-        .when(mockSessionDocRef.set(anyMap()))
+        .when(mockSessionDocRef.create(anyMap()))
         .thenReturn(ApiFutures.immediateFuture(mockWriteResult));
     lenient()
         .when(mockSessionDocRef.update(anyMap()))
@@ -307,7 +315,7 @@ void createSession_withSessionId_returnsNewSession() {
           assertThat(session.id()).isEqualTo(SESSION_ID);
           return true;
         });
-    verify(mockSessionDocRef).set(anyMap());
+    verify(mockSessionDocRef).create(anyMap());
   }
 
   /** Tests that createSession creates a new session with a generated session ID. */
@@ -334,7 +342,7 @@ void createSession_withNullSessionId_generatesNewId() {
           assertThat(session.id()).isNotEmpty();
           return true;
         });
-    verify(mockSessionDocRef).set(anyMap());
+    verify(mockSessionDocRef).create(anyMap());
   }
 
   /** Tests that createSession creates a new session with an empty session ID. */
@@ -358,7 +366,7 @@ void createSession_withEmptySessionId_generatesNewId() {
           assertThat(session.id()).isNotEqualTo("  ");
           return true;
         });
-    verify(mockSessionDocRef).set(anyMap());
+    verify(mockSessionDocRef).create(anyMap());
   }
 
   /** Tests that createSession creates a new session with an empty state when null state is */
@@ -391,6 +399,114 @@ void createSession_withNullAppName_throwsNullPointerException() {
         .assertError(NullPointerException.class);
   }
 
+  /** Tests that createSession rejects a session ID that is already taken. */
+  @Test
+  void createSession_withSessionIdAlreadyTaken_failsWithSessionException() {
+    // Arrange
+    when(mockSessionsCollection.document(SESSION_ID)).thenReturn(mockSessionDocRef);
+    when(mockSessionDocRef.create(anyMap()))
+        .thenReturn(ApiFutures.immediateFailedFuture(alreadyExists()));
+    when(mockSessionDocRef.get()).thenReturn(ApiFutures.immediateFuture(mockSessionSnapshot));
+    // Another caller's session, or one written before sessions carried a token.
+    when(mockSessionSnapshot.getString(FirestoreSessionService.CREATE_TOKEN_KEY)).thenReturn(null);
+
+    // Act
+    TestObserver<Session> testObserver =
+        sessionService.createSession(APP_NAME, USER_ID, null, SESSION_ID).test();
+
+    // Assert
+    testObserver.assertError(
+        e -> {
+          assertThat(e).isInstanceOf(SessionException.class);
+          assertThat(e).hasMessageThat().isEqualTo(SessionException.SESSION_ALREADY_EXISTS);
+          assertThat(e).hasCauseThat().isInstanceOf(AlreadyExistsException.class);
+          return true;
+        });
+  }
+
+  /** Tests that createSession succeeds when a client retry fails on the session's own write. */
+  @Test
+  void createSession_whenRetryHitsItsOwnWrite_returnsSession() {
+    // Arrange
+    when(mockSessionsCollection.document(SESSION_ID)).thenReturn(mockSessionDocRef);
+    when(mockSessionDocRef.create(sessionDataCaptor.capture()))
+        .thenReturn(ApiFutures.immediateFailedFuture(alreadyExists()));
+    when(mockSessionDocRef.get()).thenReturn(ApiFutures.immediateFuture(mockSessionSnapshot));
+    when(mockSessionSnapshot.getString(FirestoreSessionService.CREATE_TOKEN_KEY))
+        .thenAnswer(
+            unused -> sessionDataCaptor.getValue().get(FirestoreSessionService.CREATE_TOKEN_KEY));
+
+    // Act
+    TestObserver<Session> testObserver =
+        sessionService.createSession(APP_NAME, USER_ID, null, SESSION_ID).test();
+
+    // Assert
+    testObserver.assertComplete();
+    testObserver.assertValue(session -> session.id().equals(SESSION_ID));
+  }
+
+  /**
+   * Tests that a failed read-back after a duplicate is propagated, since it cannot tell whose
+   * session exists.
+   */
+  @Test
+  void createSession_whenReadBackFails_propagatesFailure() {
+    // Arrange
+    when(mockSessionsCollection.document(SESSION_ID)).thenReturn(mockSessionDocRef);
+    when(mockSessionDocRef.create(anyMap()))
+        .thenReturn(ApiFutures.immediateFailedFuture(alreadyExists()));
+    when(mockSessionDocRef.get())
+        .thenReturn(
+            ApiFutures.immediateFailedFuture(
+                new UnavailableException(
+                    "Service unavailable",
+                    /* cause= */ null,
+                    GrpcStatusCode.of(Status.Code.UNAVAILABLE),
+                    /* retryable= */ true)));
+
+    // Act
+    TestObserver<Session> testObserver =
+        sessionService.createSession(APP_NAME, USER_ID, null, SESSION_ID).test();
+
+    // Assert
+    testObserver.assertError(
+        e -> {
+          assertThat(e).isInstanceOf(ExecutionException.class);
+          assertThat(e).hasCauseThat().isInstanceOf(UnavailableException.class);
+          return true;
+        });
+  }
+
+  /**
+   * Tests that a write failure unrelated to a duplicate session ID is propagated rather than
+   * reported as one.
+   */
+  @Test
+  void createSession_whenWriteFailsForAnotherReason_propagatesFailure() {
+    // Arrange
+    when(mockSessionsCollection.document(SESSION_ID)).thenReturn(mockSessionDocRef);
+    when(mockSessionDocRef.create(anyMap()))
+        .thenReturn(
+            ApiFutures.immediateFailedFuture(
+                new PermissionDeniedException(
+                    "Missing or insufficient permissions",
+                    /* cause= */ null,
+                    GrpcStatusCode.of(Status.Code.PERMISSION_DENIED),
+                    /* retryable= */ false)));
+
+    // Act
+    TestObserver<Session> testObserver =
+        sessionService.createSession(APP_NAME, USER_ID, null, SESSION_ID).test();
+
+    // Assert
+    testObserver.assertError(
+        e -> {
+          assertThat(e).isInstanceOf(ExecutionException.class);
+          assertThat(e).hasCauseThat().isInstanceOf(PermissionDeniedException.class);
+          return true;
+        });
+  }
+
   // --- appendEvent Tests ---
   /** Tests that appendEvent persists the event and updates the session's updateTime. */
   @Test
@@ -978,4 +1094,12 @@ void deleteSession_appNameMismatch_doesNotDelete() {
     verify(mockSessionDocRef, never()).delete();
     verify(mockWriteBatch, never()).commit();
   }
+
+  private static AlreadyExistsException alreadyExists() {
+    return new AlreadyExistsException(
+        "Document already exists",
+        /* cause= */ null,
+        GrpcStatusCode.of(Status.Code.ALREADY_EXISTS),
+        /* retryable= */ false);
+  }
 }
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		See [AGENTS.md](./AGENTS.md) for project context, commands, and contribution guidelines for AI coding agents.