Package com.tnsai.agents.groups

Interface AgentGroup

public interface AgentGroup
AgentGroup - Core abstraction for collections of cooperating agents.

An AgentGroup provides a structured way to organize multiple agents that work together toward common goals. It manages membership, lifecycle, communication, and coordination patterns.

Key Concepts

  • Membership: Dynamic agent join/leave with policy enforcement
  • Lifecycle: Formation → Active → Dissolving → Dissolved
  • Communication: Intra-group messaging via GroupEventBus
  • Coordination: Scatter/gather, leader election, task assignment

Usage Example


 AgentGroup group = DefaultAgentGroup.builder()
     .name("Research Team")
     .policy(GroupPolicy.builder()
         .maxMembers(5)
         .memberTimeout(Duration.ofMinutes(30))
         .build())
     .build();

 group.addMember(agent1);
 group.addMember(agent2);
 group.start();

 // Scatter a message to all members
 Map<String, String> responses = group.scatter("Analyze this data");
See Also:
  • invalid reference 
    for mission-oriented groups
  • invalid reference 
    for emergent behavior groups
  • invalid reference 
    for contribution-based groups

  • Method Details

    • getId

      String getId()
      Returns the unique identifier of this group.
      Returns:
      group ID (UUID format)

    • getName

      String getName()
      Returns the human-readable name of this group.
      Returns:
      group name

    • getDescription

      Optional<String> getDescription()
      Returns optional description of this group's purpose.
      Returns:
      description or empty if not set

    • getPolicy

      GroupPolicy getPolicy()
      Returns the policy governing this group's behavior.
      Returns:
      group policy

    • setPolicy

      void setPolicy(GroupPolicy policy)
      Updates the group policy. Some policy changes may not take effect until the group is restarted.
      Parameters:
      policy - new policy
      Throws:
      IllegalStateException - if group is dissolved

    • getMembers

      List<Agent> getMembers()
      Returns the current members of this group.
      Returns:
      unmodifiable list of member agents

    • getMemberCount

      default int getMemberCount()
      Returns the number of current members.
      Returns:
      member count

    • addMember

      boolean addMember(Agent agent)
      Adds an agent to this group.
      Parameters:
      agent - agent to add
      Returns:
      true if added, false if already a member or policy rejected
      Throws:
      IllegalStateException - if group is dissolved
      GroupPolicyViolationException - if policy constraints are violated

    • removeMember

      boolean removeMember(String agentId)
      Removes an agent from this group.
      Parameters:
      agentId - ID of agent to remove
      Returns:
      true if removed, false if not a member
      Throws:
      IllegalStateException - if group is dissolved

    • hasMember

      boolean hasMember(String agentId)
      Checks if an agent is a member of this group.
      Parameters:
      agentId - agent ID to check
      Returns:
      true if member

    • getMember

      Optional<Agent> getMember(String agentId)
      Gets a member by ID.
      Parameters:
      agentId - agent ID
      Returns:
      agent if found

    • findMembers

      List<Agent> findMembers(Predicate<Agent> predicate)
      Finds members matching a predicate.
      Parameters:
      predicate - filter condition
      Returns:
      matching members

    • getLifecycle

      GroupLifecycle getLifecycle()
      Returns the current lifecycle state of this group.
      Returns:
      lifecycle state

    • start

      void start()
      Starts the group, transitioning from FORMED to ACTIVE.
      Throws:
      IllegalStateException - if not in FORMED state
      GroupPolicyViolationException - if minimum members not met

    • stop

      void stop()
      Stops the group gracefully, allowing in-flight operations to complete.

    • stopNow

      void stopNow()
      Stops the group immediately, canceling in-flight operations.

    • dissolve

      void dissolve()
      Dissolves the group permanently. Members are removed and the group cannot be restarted.

    • isActive

      default boolean isActive()
      Checks if the group is active and accepting work.
      Returns:
      true if active

    • isDissolved

      default boolean isDissolved()
      Checks if the group is dissolved and cannot be used.
      Returns:
      true if dissolved

    • getEventBus

      GroupEventBus getEventBus()
      Returns the event bus for intra-group communication.
      Returns:
      group event bus

    • broadcast

      void broadcast(AgentMessage message)
      Broadcasts a message to all members.
      Parameters:
      message - message to broadcast

    • broadcast

      default void broadcast(String content)
      Broadcasts a simple text message to all members.
      Parameters:
      content - message content

    • scatter

      Map<String,String> scatter(String prompt)
      Scatters a prompt to all members and gathers responses. Uses default timeout from policy.
      Parameters:
      prompt - prompt to scatter
      Returns:
      map of agent ID to response

    • scatter

      Map<String,String> scatter(String prompt, Duration timeout)
      Scatters a prompt to all members with custom timeout.
      Parameters:
      prompt - prompt to scatter
      timeout - timeout for responses
      Returns:
      map of agent ID to response

    • scatterAsync

      CompletableFuture<Map<String,String>> scatterAsync(String prompt)
      Async version of scatter.
      Parameters:
      prompt - prompt to scatter
      Returns:
      future completing with responses

    • getMembershipManager

      MembershipManager getMembershipManager()
      Returns the membership manager for advanced membership operations.
      Returns:
      membership manager

    • electLeader

      Optional<Agent> electLeader()
      Elects a leader among members using the configured strategy.
      Returns:
      elected leader, or empty if election failed

    • electLeader

      Optional<Agent> electLeader(LeaderElectionStrategy strategy)
      Elects a leader using a specific strategy.
      Parameters:
      strategy - election strategy
      Returns:
      elected leader, or empty if election failed

    • getLeader

      Optional<Agent> getLeader()
      Returns the current leader if one has been elected.
      Returns:
      current leader

    • assignTask

      Optional<Agent> assignTask(GroupTask task)
      Assigns a task to a member based on the configured assignment strategy.
      Parameters:
      task - task to assign
      Returns:
      assigned agent, or empty if no suitable agent found

    • getMetrics

      GroupMetrics getMetrics()
      Returns group metrics snapshot.
      Returns:
      metrics

    • addLifecycleListener

      void addLifecycleListener(GroupLifecycleListener listener)
      Adds a lifecycle listener.
      Parameters:
      listener - listener to add

    • removeLifecycleListener

      void removeLifecycleListener(GroupLifecycleListener listener)
      Removes a lifecycle listener.
      Parameters:
      listener - listener to remove

    • addMembershipListener

      void addMembershipListener(MembershipListener listener)
      Adds a membership listener.
      Parameters:
      listener - listener to add

    • removeMembershipListener

      void removeMembershipListener(MembershipListener listener)
      Removes a membership listener.
      Parameters:
      listener - listener to remove

    • builder

      static AgentGroupBuilder builder()
      Creates a new builder for AgentGroup.
      Returns:
      new builder instance