feat: Add tools and toolset to use SkillSource in ADK agents

This change introduces a set of tools and a toolset to enable ADK agents
to interact with and use skills loaded via `SkillSource`.

Key changes:
- ListSkillsTool: Lists available skills.
- LoadSkillTool: Loads skill instructions.
- LoadSkillResourceTool: Loads skill resources.
- SkillToolset: Groups the above tools.
- Integrates SkillSource into LlmAgent and BaseLlmFlow.
- Tests for all new tools.

PiperOrigin-RevId: 919952737

Author: google-genai-bot

core/src/main/java/com/google/adk/flows/llmflows/BaseLlmFlow.java

@@ -38,10 +38,7 @@
 import com.google.adk.models.LlmRequest;
 import com.google.adk.models.LlmResponse;
 import com.google.adk.telemetry.Tracing;
-import com.google.adk.tools.BaseTool;
-import com.google.adk.tools.BaseToolset;
 import com.google.adk.tools.ToolContext;
-import com.google.common.annotations.VisibleForTesting;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Iterables;
 import com.google.genai.types.FunctionResponse;
@@ -61,7 +58,6 @@
 import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.BiFunction;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -100,8 +96,20 @@ private Flowable<Event> preprocess(
     Context currentContext = Context.current();
     LlmAgent agent = (LlmAgent) context.agent();
 
+    RequestProcessor toolsProcessor =
+        (ctx, req) -> {
+          LlmRequest.Builder builder = req.toBuilder();
+          return agent
+              .canonicalTools(new ReadonlyContext(ctx))
+              .concatMapCompletable(
+                  tool -> tool.processLlmRequest(builder, ToolContext.builder(ctx).build()))
+              .andThen(
+                  Single.fromCallable(
+                      () -> RequestProcessingResult.create(builder.build(), ImmutableList.of())));
+        };
+
     Iterable<RequestProcessor> allProcessors =
-        Iterables.concat(requestProcessors, ImmutableList.of(getRequestProcessorFromTools(agent)));
+        Iterables.concat(requestProcessors, ImmutableList.of(toolsProcessor));
 
     return Flowable.fromIterable(allProcessors)
         .concatMap(
@@ -113,48 +121,6 @@ private Flowable<Event> preprocess(
                         result -> result.events() != null ? result.events() : ImmutableList.of()));
   }
 
-  /**
-   * Constructs a {@link RequestProcessor} that sequentially applies the {@code processLlmRequest}
-   * methods of all tools and toolsets associated with this agent to the incoming {@link
-   * LlmRequest}.
-   *
-   * @return A {@link RequestProcessor} that applies tool-specific modifications to LLM requests.
-   */
-  @VisibleForTesting
-  RequestProcessor getRequestProcessorFromTools(LlmAgent agent) {
-    return (context, request) -> {
-      ReadonlyContext readonlyContext = new ReadonlyContext(context);
-      List<BiFunction<LlmRequest.Builder, ToolContext, Completable>> processors = new ArrayList<>();
-
-      for (Object toolOrToolset : agent.toolsUnion()) {
-        if (toolOrToolset instanceof BaseTool baseTool) {
-          processors.add(baseTool::processLlmRequest);
-        } else if (toolOrToolset instanceof BaseToolset baseToolset) {
-          // First apply the toolset's own request processor, then unwrap all tools from the toolset
-          // and apply each individual tool's request processor sequentially.
-          processors.add(
-              (builder, ctx) ->
-                  baseToolset
-                      .processLlmRequest(builder, ctx)
-                      .andThen(baseToolset.getTools(readonlyContext))
-                      .concatMapCompletable(b -> b.processLlmRequest(builder, ctx)));
-        } else {
-          throw new IllegalArgumentException(
-              "Object in tools list is not of a supported type: "
-                  + toolOrToolset.getClass().getName());
-        }
-      }
-
-      LlmRequest.Builder builder = request.toBuilder();
-      ToolContext toolContext = ToolContext.builder(context).build();
-      return Flowable.fromIterable(processors)
-          .concatMapCompletable(f -> f.apply(builder, toolContext))
-          .andThen(
-              Single.fromCallable(
-                  () -> RequestProcessingResult.create(builder.build(), ImmutableList.of())));
-    };
-  }
-
   /**
    * Post-processes the LLM response after receiving it from the LLM. Executes all registered {@link
    * ResponseProcessor} instances. Emits events for the model response and any subsequent function

core/src/main/java/com/google/adk/skills/AbstractSkillSource.java

@@ -16,8 +16,6 @@
 
 package com.google.adk.skills;
 
-import static com.google.adk.skills.SkillSourceException.SKILL_FORMAT_ERROR;
-import static com.google.adk.skills.SkillSourceException.SKILL_LOAD_ERROR;
 import static java.nio.channels.Channels.newReader;
 import static java.nio.charset.StandardCharsets.UTF_8;
 
@@ -84,14 +82,12 @@ private Frontmatter loadFrontmatter(String skillName, PathT skillMdPath)
       Frontmatter frontmatter = yamlMapper.readValue(yaml, Frontmatter.class);
       if (!frontmatter.name().equals(skillName)) {
         throw new SkillSourceException(
-            "Skill name in the frontmatter '%s' does not match skill name '%s'."
-                .formatted(frontmatter.name(), skillName),
-            SKILL_LOAD_ERROR);
+            "Skill name '%s' does not match directory name '%s'."
+                .formatted(frontmatter.name(), skillName));
       }
       return frontmatter;
     } catch (IOException e) {
-      throw new SkillSourceException(
-          "Cannot load frontmatter for skill '" + skillName + "'", SKILL_LOAD_ERROR, e);
+      throw new SkillSourceException("Cannot load frontmatter for skill '" + skillName + "'", e);
     }
   }
 
@@ -104,9 +100,7 @@ public Single<String> loadInstructions(String skillName) {
                 return readInstructions(reader);
               } catch (IOException e) {
                 throw new SkillSourceException(
-                    "Failed to load instruction for skill '" + skillName + "'",
-                    SKILL_LOAD_ERROR,
-                    e);
+                    "Failed to load instruction for skill '" + skillName + "'", e);
               }
             });
   }
@@ -146,8 +140,7 @@ private String readFrontmatterYaml(BufferedReader reader)
       throws IOException, SkillSourceException {
     String line = reader.readLine();
     if (line == null || !line.trim().equals(THREE_DASHES)) {
-      throw new SkillSourceException(
-          "Skill file must start with " + THREE_DASHES, SKILL_FORMAT_ERROR);
+      throw new SkillSourceException("Skill file must start with " + THREE_DASHES);
     }
 
     StringBuilder sb = new StringBuilder();
@@ -158,15 +151,14 @@ private String readFrontmatterYaml(BufferedReader reader)
       sb.append(line).append("\n");
     }
     throw new SkillSourceException(
-        "Skill file frontmatter not properly closed with " + THREE_DASHES, SKILL_FORMAT_ERROR);
+        "Skill file frontmatter not properly closed with " + THREE_DASHES);
   }
 
   private String readInstructions(BufferedReader reader) throws IOException, SkillSourceException {
     // Skip the frontmatter block
     String line = reader.readLine();
     if (line == null || !line.trim().equals(THREE_DASHES)) {
-      throw new SkillSourceException(
-          "Skill file must start with " + THREE_DASHES, SKILL_FORMAT_ERROR);
+      throw new SkillSourceException("Skill file must start with " + THREE_DASHES);
     }
     boolean dashClosed = false;
     while ((line = reader.readLine()) != null) {
@@ -177,7 +169,7 @@ private String readInstructions(BufferedReader reader) throws IOException, Skill
     }
     if (!dashClosed) {
       throw new SkillSourceException(
-          "Skill file frontmatter not properly closed with " + THREE_DASHES, SKILL_FORMAT_ERROR);
+          "Skill file frontmatter not properly closed with " + THREE_DASHES);
     }
     // Read the instructions till the end of the file
     StringBuilder sb = new StringBuilder();

core/src/main/java/com/google/adk/skills/InMemorySkillSource.java

@@ -16,8 +16,6 @@
 
 package com.google.adk.skills;
 
-import static com.google.adk.skills.SkillSourceException.RESOURCE_NOT_FOUND;
-import static com.google.adk.skills.SkillSourceException.SKILL_NOT_FOUND;
 import static com.google.common.base.Preconditions.checkState;
 import static com.google.common.collect.ImmutableList.toImmutableList;
 import static java.nio.charset.StandardCharsets.UTF_8;
@@ -58,8 +56,7 @@ public Single<ImmutableMap<String, Frontmatter>> listFrontmatters() {
   public Single<ImmutableList<String>> listResources(String skillName, String resourceDirectory) {
     SkillData data = skills.get(skillName);
     if (data == null) {
-      return Single.error(
-          new SkillSourceException("Skill not found: " + skillName, SKILL_NOT_FOUND));
+      return Single.error(new SkillSourceException("Skill not found: " + skillName));
     }
     String prefix =
         resourceDirectory.isEmpty()
@@ -70,8 +67,7 @@ public Single<ImmutableList<String>> listResources(String skillName, String reso
         && data.resources().keySet().stream().noneMatch(path -> path.startsWith(prefix))) {
       return Single.error(
           new SkillSourceException(
-              "Resource directory not found: " + resourceDirectory + " for skill: " + skillName,
-              RESOURCE_NOT_FOUND));
+              "Resource directory not found: " + resourceDirectory + " for skill: " + skillName));
     }
 
     return Single.just(
@@ -96,16 +92,13 @@ public Single<ByteSource> loadResource(String skillName, String resourcePath) {
         .map(SkillData::resources)
         .mapOptional(m -> Optional.ofNullable(m.get(resourcePath)))
         .switchIfEmpty(
-            Single.error(
-                new SkillSourceException(
-                    "Resource not found: " + resourcePath, RESOURCE_NOT_FOUND)));
+            Single.error(new SkillSourceException("Resource not found: " + resourcePath)));
   }
 
   private Single<SkillData> getSkillData(String skillName) {
     SkillData data = skills.get(skillName);
     if (data == null) {
-      return Single.error(
-          new SkillSourceException("Skill not found: " + skillName, SKILL_NOT_FOUND));
+      return Single.error(new SkillSourceException("Skill not found: " + skillName));
     }
     return Single.just(data);
   }

core/src/main/java/com/google/adk/skills/LocalSkillSource.java

@@ -16,10 +16,6 @@
 
 package com.google.adk.skills;
 
-import static com.google.adk.skills.SkillSourceException.RESOURCE_LOAD_ERROR;
-import static com.google.adk.skills.SkillSourceException.RESOURCE_NOT_FOUND;
-import static com.google.adk.skills.SkillSourceException.SKILL_LOAD_ERROR;
-import static com.google.adk.skills.SkillSourceException.SKILL_NOT_FOUND;
 import static com.google.common.collect.ImmutableList.toImmutableList;
 import static java.nio.file.Files.isDirectory;
 
@@ -47,16 +43,14 @@ public LocalSkillSource(Path skillsBasePath) {
   public Single<ImmutableList<String>> listResources(String skillName, String resourceDirectory) {
     Path skillDir = skillsBasePath.resolve(skillName);
     if (!isDirectory(skillDir)) {
-      return Single.error(
-          new SkillSourceException("Skill not found: " + skillName, SKILL_NOT_FOUND));
+      return Single.error(new SkillSourceException("Skill not found: " + skillName));
     }
     Path resourceDir = skillDir.resolve(resourceDirectory);
     if (!isDirectory(resourceDir)) {
       return Single.error(
           new SkillSourceException(
               "Resource directory '%s' not found for skill '%s'"
-                  .formatted(resourceDirectory, skillName),
-              RESOURCE_NOT_FOUND));
+                  .formatted(resourceDirectory, skillName)));
     }
 
     return Single.fromCallable(
@@ -73,9 +67,7 @@ public Single<ImmutableList<String>> listResources(String skillName, String reso
             t ->
                 Single.error(
                     new SkillSourceException(
-                        "Failed to traverse resource directory: " + resourceDirectory,
-                        RESOURCE_LOAD_ERROR,
-                        t)));
+                        "Failed to traverse resource directory: " + resourceDirectory, t)));
   }
 
   @Override
@@ -86,9 +78,7 @@ protected Flowable<SkillMdPath> listSkills() {
             t ->
                 Flowable.error(
                     new SkillSourceException(
-                        "Failed to list skills in directory: " + skillsBasePath,
-                        SKILL_LOAD_ERROR,
-                        t)))
+                        "Failed to list skills in directory: " + skillsBasePath, t)))
         .filter(Files::isDirectory)
         .mapOptional(this::findSkillMd)
         .map(skillMd -> new SkillMdPath(skillMd.getParent().getFileName().toString(), skillMd));
@@ -98,8 +88,7 @@ protected Flowable<SkillMdPath> listSkills() {
   protected Single<Path> findResourcePath(String skillName, String resourcePath) {
     Path file = skillsBasePath.resolve(skillName).resolve(resourcePath);
     if (!Files.exists(file)) {
-      return Single.error(
-          new SkillSourceException("Resource not found: " + file, RESOURCE_NOT_FOUND));
+      return Single.error(new SkillSourceException("Resource not found: " + file));
     }
     return Single.just(file);
   }
@@ -108,13 +97,11 @@ protected Single<Path> findResourcePath(String skillName, String resourcePath) {
   protected Single<Path> findSkillMdPath(String skillName) {
     Path skillDir = skillsBasePath.resolve(skillName);
     if (!isDirectory(skillDir)) {
-      return Single.error(
-          new SkillSourceException("Skill directory not found: " + skillName, SKILL_NOT_FOUND));
+      return Single.error(new SkillSourceException("Skill directory not found: " + skillName));
     }
     return Maybe.fromOptional(findSkillMd(skillDir))
         .switchIfEmpty(
-            Single.error(
-                new SkillSourceException("SKILL.md not found in " + skillName, SKILL_NOT_FOUND)));
+            Single.error(new SkillSourceException("SKILL.md not found in " + skillName)));
   }
 
   @Override

core/src/main/java/com/google/adk/skills/SkillSourceException.java

@@ -22,43 +22,11 @@
  */
 public final class SkillSourceException extends Exception {
 
-  public static final String SKILL_LOAD_ERROR = "SKILL_LOAD_ERROR";
-  public static final String SKILL_NOT_FOUND = "SKILL_NOT_FOUND";
-  public static final String SKILL_FORMAT_ERROR = "SKILL_FORMAT_ERROR";
-  public static final String RESOURCE_LOAD_ERROR = "RESOURCE_LOAD_ERROR";
-  public static final String RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND";
-
-  private final String errorCode;
-
-  /**
-   * Constructs a new exception with the specified detail message and error code.
-   *
-   * @param message The detail message.
-   * @param errorCode The specific error code categorizing the failure.
-   */
-  public SkillSourceException(String message, String errorCode) {
+  public SkillSourceException(String message) {
     super(message);
-    this.errorCode = errorCode;
   }
 
-  /**
-   * Constructs a new exception with the specified detail message, error code, and cause.
-   *
-   * @param message The detail message.
-   * @param errorCode The specific error code categorizing the failure.
-   * @param cause The cause.
-   */
-  public SkillSourceException(String message, String errorCode, Throwable cause) {
+  public SkillSourceException(String message, Throwable cause) {
     super(message, cause);
-    this.errorCode = errorCode;
-  }
-
-  /**
-   * Returns the error code categorizing the failure.
-   *
-   * @return The error code string.
-   */
-  public String getErrorCode() {
-    return errorCode;
   }
 }

core/src/main/java/com/google/adk/tools/BaseToolset.java

@@ -17,26 +17,18 @@
 package com.google.adk.tools;
 
 import com.google.adk.agents.ReadonlyContext;
-import com.google.adk.models.LlmRequest;
-import io.reactivex.rxjava3.core.Completable;
 import io.reactivex.rxjava3.core.Flowable;
 import java.util.List;
 import org.jspecify.annotations.Nullable;
 
 /** Base interface for toolsets. */
 public interface BaseToolset extends AutoCloseable {
 
-  /** Processes the outgoing {@link LlmRequest.Builder}. */
-  default Completable processLlmRequest(
-      LlmRequest.Builder llmRequestBuilder, ToolContext toolContext) {
-    return Completable.complete();
-  }
-
   /**
    * Return all tools in the toolset based on the provided context.
    *
    * @param readonlyContext Context used to filter tools available to the agent.
-   * @return A Flowable emitting tools available under the specified context.
+   * @return A Single emitting a list of tools available under the specified context.
    */
   Flowable<BaseTool> getTools(ReadonlyContext readonlyContext);