Package com.alibaba.cloud.ai.graph.agent.tool

Class ToolStateCollector

java.lang.Object
com.alibaba.cloud.ai.graph.agent.tool.ToolStateCollector
public class ToolStateCollector extends Object
Collects state updates from parallel tool executions with isolation. Each tool gets its own update map to avoid concurrent write conflicts. Merges are performed in original tool order for deterministic results.

Thread Safety: This class is thread-safe. Each tool receives an isolated ConcurrentHashMap for its updates, allowing safe concurrent writes even if the tool has internal async operations.

Usage Contract: mergeAll() must only be called once, after all tools have completed. Calling it multiple times will throw an exception.

Example usage: 


 ToolStateCollector collector = new ToolStateCollector(3, state.keyStrategies());

 // Each tool gets its own update map
 Map<String, Object> tool0Updates = collector.createToolUpdateMap(0);
 Map<String, Object> tool1Updates = collector.createToolUpdateMap(1);
 Map<String, Object> tool2Updates = collector.createToolUpdateMap(2);

 // Tools can safely write to their maps concurrently
 tool0Updates.put("result", "value0");
 tool1Updates.put("result", "value1");

 // After all tools complete, merge in index order
 Map<String, Object> merged = collector.mergeAll();
Since:
1.0.0
Author:
disaster
See Also:

  • Constructor Details

    • ToolStateCollector

      public ToolStateCollector(int totalTools, Map<String,KeyStrategy> keyStrategies)
      Creates a new state collector.
      Parameters:
      totalTools - the total number of tools to collect state from
      keyStrategies - the key strategies for merging (nullable)

  • Method Details

    • createToolUpdateMap

      public Map<String,Object> createToolUpdateMap(int index)
      Creates an isolated update map for a tool at the given index. The returned map is a ConcurrentHashMap, allowing safe concurrent writes even if the tool implementation has internal async operations.
      Parameters:
      index - the tool index (0-based, in original toolCalls order)
      Returns:
      a new ConcurrentHashMap for the tool to write updates to
      Throws:
      IllegalStateException - if mergeAll() has already been called

    • discardToolUpdateMap

      public void discardToolUpdateMap(int index)
      Discards updates for a tool at the given index.

      This is useful when a tool execution times out and we want to avoid merging partial updates that may still be written after the timeout.

      Parameters:
      index - the tool index (0-based, in original toolCalls order)

    • mergeAll

      public Map<String,Object> mergeAll()
      Merges all tool updates in original index order (0, 1, 2, ...). This ensures deterministic results regardless of completion order.

      Note: This method can only be called once. Subsequent calls will throw an IllegalStateException. This ensures that merging happens only after all tools have completed their execution.

      Returns:
      the merged state updates
      Throws:
      IllegalStateException - if called more than once

    • getCompletedCount

      public int getCompletedCount()
      Gets the number of tools that have submitted updates.
      Returns:
      the count of tools with updates

    • isMerged

      public boolean isMerged()
      Checks if mergeAll() has been called.
      Returns:
      true if merged