Class ToolManager

java.lang.Object
uno.anahata.asi.agi.event.BasicPropertyChangeSource
uno.anahata.asi.agi.tool.ToolManager
All Implemented Interfaces:
ContextProvider, PropertyChangeSource, Rebindable
public class ToolManager extends BasicPropertyChangeSource implements ContextProvider, Rebindable
Manages the lifecycle of all AI tools, including registration, configuration, and lookup. It stores toolkits and generates the full list of tools on demand.

This class also implements ContextProvider, acting as the root provider for all toolkits and injecting metadata about available tools into the AI's context.

Author:
anahata-gemini-pro-2.5

  • Field Details

    • providing

      private boolean providing
      Whether this manager is currently providing context augmentation.

    • wrapResponseSchemas

      private boolean wrapResponseSchemas
      Flag to control whether the tool response schemas are wrapped in the standard JavaMethodToolResponse structure. If false, only the raw result type is used in the tool definition, and the wrapper is explained globally.

    • agi

      private final Agi agi
      The parent agi session.

    • toolkits

      private final Map<String, AbstractToolkit<?>> toolkits
      A map of registered toolkits, keyed by their simple name.

    • executingCalls

      private transient List<AbstractToolCall<?,?>> executingCalls
      A thread-safe list of currently executing tool calls.

    • sessionAttributes

      public final Map<Object,Object> sessionAttributes
      A session-scoped map for tools to store state across turns. Access is manually synchronized to avoid Kryo serialization issues with JDK synchronized wrappers.

  • Constructor Details

    • ToolManager

      public ToolManager(@NonNull @NonNull Agi agi)
      Primary constructor for use in a live agi session. This constructor is self-initializing, registering all tools defined in the AgiConfig.
      Parameters:
      agi - The parent agi orchestrator.

  • Method Details

    • reset

      public void reset()
      Resets the static tool call ID counter to zero.

    • resetTokenCounts

      public void resetTokenCounts()
      Resets the cached token counts on all registered and enabled tools within this manager, forcing a lazy recalculation on the next query.

    • registerClasses

      public final void registerClasses(Class<?>... classes)
      Scans the given classes for methods annotated with AgiTool, creates the corresponding toolkits, and applies any application-wide preferences.

      Implementation details: Uses a two-pass registration flow. The first pass instantiates and registers all toolkits in the map. The second pass triggers initialize() on each toolkit. This eliminates race conditions where one toolkit needs to look up another during setup.

      Parameters:
      classes - The classes to scan for tools.

    • createToolCall

      public AbstractToolCall createToolCall(AbstractModelMessage amm, String id, String name, Map<String,Object> jsonArgs)
      The primary factory method for creating a model-agnostic tool call from provider-specific data. This method orchestrates the creation and pre-rejection logic.
      Parameters:
      amm - The model message that initiated the call.
      id - The unique ID of the tool call (can be null).
      name - The name of the tool to call.
      jsonArgs - The raw arguments from the model.
      Returns:
      An AbstractToolCall with its corresponding, possibly pre-rejected, response.

    • findToolByName

      public Optional<? extends AbstractTool> findToolByName(String name)
      Finds a tool by its fully qualified name.
      Parameters:
      name - The tool name.
      Returns:
      An Optional containing the tool if found.

    • getAllToolNames

      public List<String> getAllToolNames()
      Gets a list of all fully qualified tool names registered in this manager.
      Returns:
      A list of registered tool names.

    • getEnabledToolkits

      public List<AbstractToolkit<?>> getEnabledToolkits()
      Gets a list of all toolkits that are currently enabled.
      Returns:
      The list of enabled toolkits.

    • getDisabledToolkits

      public List<AbstractToolkit<?>> getDisabledToolkits()
      Gets a list of all toolkits that are currently disabled.
      Returns:
      The list of disabled toolkits.

    • getAllTools

      public List<? extends AbstractTool> getAllTools()
      Gets a dynamically aggregated list of all tools from all registered toolkits. This is a view and is generated on each call.
      Returns:
      A list of all tools.

    • getEnabledTools

      public List<? extends AbstractTool> getEnabledTools()
      Gets a list of all tools that are currently enabled and allowed to be sent to the model.
      Returns:
      A filtered list of enabled tools.

    • applyPreferences

      private void applyPreferences()
      Applies application-wide tool preferences to all registered tools.

    • getAllContextProviders

      public List<ContextProvider> getAllContextProviders()
      Returns all context providers from enabled toolkits.
      Returns:
      A list of context providers.

    • getDisabledContextProviders

      public List<ContextProvider> getDisabledContextProviders()
      Returns all context providers from enabled toolkits that are currently disabled.
      Returns:
      A list of disabled context providers.

    • registerExecutingCall

      public void registerExecutingCall(AbstractToolCall<?,?> call)
      Registers a tool call as currently executing and fires a property change event.
      Parameters:
      call - The tool call to register.

    • unregisterExecutingCall

      public void unregisterExecutingCall(AbstractToolCall<?,?> call)
      Unregisters a tool call from the executing list and fires a property change event.
      Parameters:
      call - The tool call to unregister.

    • getExecutingCalls

      public List<AbstractToolCall<?,?>> getExecutingCalls()
      Gets an unmodifiable view of the currently executing tool calls.
      Returns:
      The list of executing calls.

    • getToolkitInstance

      public <T> Optional<T> getToolkitInstance(Class<T> toolkitClass)
      Retrieves the singleton instance of a registered toolkit class.
      Type Parameters:
      T - The type of the toolkit.
      Parameters:
      toolkitClass - The class of the toolkit to find.
      Returns:
      An Optional containing the toolkit instance if found.

    • updateToolkits

      public void updateToolkits(boolean enabled, List<String> toolkitNames)
      Enables or disables multiple toolkits by their names (IDs).
      Parameters:
      enabled - Whether to enable or disable.
      toolkitNames - The names of the toolkits to update.

    • rebind

      public void rebind()
      Description copied from class: BasicPropertyChangeSource
      Re-initializes the transient PropertyChangeSupport after deserialization.
      Specified by:
      rebind in interface Rebindable
      Overrides:
      rebind in class BasicPropertyChangeSource

    • getId

      public String getId()
      Gets the unique identifier for this context provider.
      Specified by:
      getId in interface ContextProvider
      Returns:
      The provider's ID.

    • getName

      public String getName()
      Gets the human-readable name of this context provider.
      Specified by:
      getName in interface ContextProvider
      Returns:
      The provider's name.

    • getDescription

      public String getDescription()
      Gets a detailed description of what this context provider does.
      Specified by:
      getDescription in interface ContextProvider
      Returns:
      The provider's description.

    • isProviding

      public boolean isProviding()
      Checks if this context provider is currently active and providing context.
      Specified by:
      isProviding in interface ContextProvider
      Returns:
      true if providing, false otherwise.

    • getSystemInstructions

      public List<String> getSystemInstructions() throws Exception
      Gets a list of system instruction strings provided by this context provider. These are typically prepended to the conversation as high-level guidance.
      Specified by:
      getSystemInstructions in interface ContextProvider
      Returns:
      A list of system instruction strings.
      Throws:
      Exception - if an error occurs during instruction generation.

    • populateMessage

      public void populateMessage(RagMessage ragMessage) throws Exception
      Populates the given RagMessage with dynamic, just-in-time context parts. These parts are appended to the end of the user's prompt (RAG).
      Specified by:
      populateMessage in interface ContextProvider
      Parameters:
      ragMessage - The message to be augmented with context.
      Throws:
      Exception - if an error occurs during context generation.

    • getChildrenProviders

      public List<ContextProvider> getChildrenProviders()
      Gets the list of immediate child context providers.
      Specified by:
      getChildrenProviders in interface ContextProvider
      Returns:
      The list of children, or an empty list if none.

    • postActivate

      public void postActivate()
      Propagates the post-activation signal to all registered toolkits.