Class ComponentRegistry

java.lang.Object
com.google.adk.utils.ComponentRegistry
Direct Known Subclasses:
CustomDemoRegistry
public class ComponentRegistry extends Object
A registry for storing and retrieving ADK instances by name.

This class provides a base registry with common ADK components and is designed to be extended by users who want to add their own pre-wired entries. The registry is fully thread-safe and supports storing any type of object.

Thread Safety:

  • All instance methods are thread-safe due to the underlying ConcurrentHashMap
  • The singleton instance access is thread-safe using volatile semantics
  • The setInstance() method is synchronized to ensure atomic singleton replacement

Base pre-wired entries include:

  • "google_search" - GoogleSearchTool instance
  • "code_execution" - BuiltInCodeExecutionTool instance
  • "exit_loop" - ExitLoopTool instance
  • "url_context" - UrlContextTool instance
  • "google_maps_grounding" - GoogleMapsTool instance

Example usage: 

// Use the singleton instance
ComponentRegistry registry = ComponentRegistry.getInstance();
Optional<GoogleSearchTool> searchTool = registry.get("google_search", GoogleSearchTool.class);

// Extend ComponentRegistry to add custom pre-wired entries
public class MyComponentRegistry extends ComponentRegistry {
  public MyComponentRegistry() {
    super(); // Initialize base pre-wired entries
    register("my_custom_tool", new MyCustomTool());
    register("my_agent", new MyCustomAgent());
  }
}

// Replace the singleton with custom registry when server starts
ComponentRegistry.setInstance(new MyComponentRegistry());

  • Constructor Details

    • ComponentRegistry

      protected ComponentRegistry()

  • Method Details

    • register

      public void register(String name, Object value)
      Registers an object with the given name. This can override pre-wired entries.

      This method is thread-safe due to the underlying ConcurrentHashMap.

      Parameters:
      name - the name to associate with the object
      value - the object to register (can be an instance, class, function, etc.)
      Throws:
      IllegalArgumentException - if name is null or empty, or if value is null

    • get

      public <T> Optional<T> get(String name, Class<T> type)
      Retrieves an object by name and attempts to cast it to the specified type.
      Type Parameters:
      T - the type parameter
      Parameters:
      name - the name of the object to retrieve
      type - the expected type of the object
      Returns:
      an Optional containing the object if found and castable to the specified type, or an empty Optional otherwise

    • get

      public Optional<Object> get(String name)
      Retrieves an object by name without type checking.
      Parameters:
      name - the name of the object to retrieve
      Returns:
      an Optional containing the object if found, or an empty Optional otherwise

    • getInstance

      public static ComponentRegistry getInstance()
      Returns the global singleton instance of ComponentRegistry.
      Returns:
      the singleton ComponentRegistry instance

    • setInstance

      public static void setInstance(ComponentRegistry newInstance)
      Updates the global singleton instance with a new ComponentRegistry. This is useful for replacing the default registry with a custom one when the server starts.

      This method is thread-safe and ensures that all threads see the updated instance atomically.

      Parameters:
      newInstance - the new ComponentRegistry instance to use as the singleton
      Throws:
      IllegalArgumentException - if newInstance is null

    • resolveAgentInstance

      public static Optional<BaseAgent> resolveAgentInstance(String name)
      Resolves an agent instance from the registry.

      This method looks up an agent in the ComponentRegistry by the given key. The registry should have been pre-populated with all available agents during initialization.

      The key can be any string that was used to register the agent, such as:

      • A class name: "com.example.LifeAgent"
      • A static field reference: "com.example.LifeAgent.INSTANCE"
      • A simple name: "life_agent"
      • Any custom key: "sub_agents_config.life_agent.agent"
      Parameters:
      name - the registry key to look up
      Returns:
      an Optional containing the BaseAgent if found, or empty if not found

    • resolveAgentClass

      public static Class<? extends BaseAgent> resolveAgentClass(String agentClassName)
      Resolves the agent class based on the agent class name from the configuration.
      Parameters:
      agentClassName - the name of the agent class from the config
      Returns:
      the corresponding agent class
      Throws:
      IllegalArgumentException - if the agent class is not supported

    • resolveToolsetInstance

      public static Optional<BaseToolset> resolveToolsetInstance(String name)
      Resolves a toolset instance by name from the registry.
      Parameters:
      name - The name of the toolset instance to resolve.
      Returns:
      An Optional containing the toolset instance if found, empty otherwise.

    • resolveToolInstance

      public static Optional<BaseTool> resolveToolInstance(String name)

    • resolveToolClass

      public static Optional<Class<? extends BaseTool>> resolveToolClass(String toolClassName)
      Resolves the tool class based on the tool class name from the configuration.
      Parameters:
      toolClassName - the name of the tool class from the config
      Returns:
      an Optional containing the tool class if found, empty otherwise

    • resolveToolsetClass

      public static Optional<Class<? extends BaseToolset>> resolveToolsetClass(String toolsetClassName)
      Resolves a toolset class by name from the registry or by attempting to load it.

      This method follows the same pattern as resolveToolClass but for BaseToolset implementations. It first checks the registry, then attempts direct class loading if the name contains a dot (indicating a fully qualified class name).

      Parameters:
      toolsetClassName - the name of the toolset class from the config
      Returns:
      an Optional containing the toolset class if found, empty otherwise

    • getToolNamesWithPrefix

      public Set<String> getToolNamesWithPrefix(String prefix)

    • resolveBeforeAgentCallback

      public static Optional<Callbacks.BeforeAgentCallback> resolveBeforeAgentCallback(String name)

    • resolveAfterAgentCallback

      public static Optional<Callbacks.AfterAgentCallback> resolveAfterAgentCallback(String name)

    • resolveBeforeModelCallback

      public static Optional<Callbacks.BeforeModelCallback> resolveBeforeModelCallback(String name)

    • resolveAfterModelCallback

      public static Optional<Callbacks.AfterModelCallback> resolveAfterModelCallback(String name)

    • resolveBeforeToolCallback

      public static Optional<Callbacks.BeforeToolCallback> resolveBeforeToolCallback(String name)

    • resolveAfterToolCallback

      public static Optional<Callbacks.AfterToolCallback> resolveAfterToolCallback(String name)