Package com.tnsai.protocols

Class ProtocolManager

java.lang.Object
com.tnsai.protocols.ProtocolManager
All Implemented Interfaces:
com.tnsai.protocols.ProtocolManagerHandle
public final class ProtocolManager extends Object implements com.tnsai.protocols.ProtocolManagerHandle
Protocol Manager - Orchestrates all communication paradigms for an agent.

ProtocolManager is the central hub for inter-agent communication in TnsAI. It automatically discovers and configures protocol handlers based on annotations on the agent class, providing a unified API for messaging.

Supported Communication Paradigms

ParadigmAnnotationUse Case
Direct MessageDirectMessagePoint-to-point, action execution
BroadcastBroadcastOne-to-many on single topic
Pub/SubPubSubMulti-topic subscribe/publish
Request/ReplyRequestReplySynchronous with timeout
DebateDebateMulti-agent deliberation

Quick Start


 // 1. Define agent with protocol annotations
 @DirectMessage
 @PubSub(topics = {"alerts", "updates"})
 public class NotificationAgent extends Agent {
     // Passes an ActionExecutor wired with a principal and an authority scope through the
     // four-argument Agent constructor, so the actions it is asked to run are not refused.
     // ...
 }

 // 2. Protocol manager auto-starts via Agent constructor
 Agent agent = new NotificationAgent(principal, scope);

 // 3. Use protocols via agent's protocol manager
 ProtocolManager pm = agent.getProtocolManager();

 // Direct message to another agent
 Message response = pm.executeAction("receiver-id", "processOrder", Map.of(
     "orderId", "12345"
 ));

 // Publish to topic
 pm.publish("alerts", Map.of("level", "HIGH", "message", "System alert"));

Transport Modes

Each protocol supports multiple transports:

  • TransportMode.INTERNAL - In-memory, same JVM (fastest)
  • TransportMode.HTTP - HTTP/REST for remote agents
  • TransportMode.AUTO - Automatic selection based on config

Message Flow

 Sender Agent                    Receiver Agent
      |                               |
      | executeAction(...)            |
      |---> ProtocolManager           |
      |       |                       |
      |       | DirectMessageHandler  |
      |       |---> Transport ------->|---> ProtocolManager
      |       |                       |       |
      |       |                       |       | Message received
      |       |                       |       | Execute action
      |       |                       |       |
      |invalid input: '<'------| Response invalid input: '<'------------|invalid input: '<'------| Reply

Natural Language Messaging

Agents can send natural language messages that the receiver's LLM parses: 


 // LLM-powered messaging (receiver's LLM processes and responds)
 pm.sendMessage("receiver-id", "Please summarize the quarterly report");

Debate Protocol

For multi-agent deliberation and consensus building: 


 // Start a debate
 DebateSession session = pm.startDebate(
     "Should we deploy to production?",
     List.of("dev-agent", "qa-agent", "ops-agent")
 );

 // Submit position
 pm.submitDebatePosition(session.getId(), "YES", 8, "All tests pass");

 // Vote on another's position
 pm.voteInDebate(session.getId(), "NO", false);

Thread Safety

This class is thread-safe. Handlers are stored in a ConcurrentHashMap and all public methods are safe to call from multiple threads.

Lifecycle

  1. Created during Agent initialization
  2. Auto-configures handlers from annotations
  3. Started automatically if annotations present
  4. Stopped when stop() is called or agent terminates
Since:
0.0.2
Author:
TnsAI Team
See Also:
  • DirectMessage
  • Broadcast
  • PubSub
  • RequestReply
  • Debate
  • Agent.getProtocolManager()

  • Constructor Details

    • ProtocolManager

      public ProtocolManager(com.tnsai.agents.Agent agent)

  • Method Details

    • start

      public void start() throws ProtocolHandler.HandlerException
      Starts all configured handlers.
      Specified by:
      start in interface com.tnsai.protocols.ProtocolManagerHandle
      Throws:
      ProtocolHandler.HandlerException

    • stop

      public void stop()
      Stops all handlers.
      Specified by:
      stop in interface com.tnsai.protocols.ProtocolManagerHandle

    • executeAction

      public com.tnsai.protocols.models.Message executeAction(String receiverId, String actionName, Map<String,Object> parameters) throws ProtocolHandler.HandlerException
      Executes an action on another agent (direct message).
      Parameters:
      receiverId - Target agent ID
      actionName - Action to execute
      parameters - Action parameters
      Returns:
      Response message with result
      Throws:
      ProtocolHandler.HandlerException

    • executeAction

      public com.tnsai.protocols.models.Message executeAction(String receiverId, String roleId, String actionName, Map<String,Object> parameters) throws ProtocolHandler.HandlerException
      Executes an action on another agent's specific role.
      Parameters:
      receiverId - Target agent ID
      roleId - Target role ID (optional)
      actionName - Action to execute
      parameters - Action parameters
      Returns:
      Response message with result
      Throws:
      ProtocolHandler.HandlerException

    • sendMessage

      public com.tnsai.protocols.models.Message sendMessage(String receiverId, String content) throws ProtocolHandler.HandlerException
      Sends a natural language message to another agent (LLM-powered). The receiver's LLM will parse the message and execute appropriate actions via tool calling.
      Parameters:
      receiverId - Target agent ID
      content - Natural language message content
      Returns:
      Response message with result
      Throws:
      ProtocolHandler.HandlerException

    • broadcast

      public void broadcast(Map<String,Object> content) throws ProtocolHandler.HandlerException
      Broadcasts a message on the configured topic.
      Parameters:
      content - Message content (can include action, parameters, beliefs, etc.)
      Throws:
      ProtocolHandler.HandlerException

    • publish

      public void publish(String topic, Map<String,Object> content) throws ProtocolHandler.HandlerException
      Publishes a message on a specific topic.
      Parameters:
      topic - Topic name
      content - Message content
      Throws:
      ProtocolHandler.HandlerException

    • request

      public com.tnsai.protocols.models.Message request(String receiverId, String actionName, Map<String,Object> parameters) throws ProtocolHandler.HandlerException
      Sends a request and waits for reply.
      Parameters:
      receiverId - Target agent ID
      actionName - Action to execute
      parameters - Action parameters
      Returns:
      Reply message with result
      Throws:
      ProtocolHandler.HandlerException

    • startDebate

      public DebateProtocolHandler.DebateSession startDebate(String topic, List<String> participantIds) throws ProtocolHandler.HandlerException
      Starts a new debate with the given participants.
      Parameters:
      topic - Debate topic
      participantIds - IDs of participating agents
      Returns:
      DebateSession for tracking the debate
      Throws:
      ProtocolHandler.HandlerException

    • submitDebatePosition

      public void submitDebatePosition(String debateId, String stance, int confidence, String reasoning) throws ProtocolHandler.HandlerException
      Submits a position in an ongoing debate.
      Parameters:
      debateId - Debate session ID
      stance - Position being taken
      confidence - Confidence level (1-10)
      reasoning - Explanation for the position
      Throws:
      ProtocolHandler.HandlerException

    • voteInDebate

      public void voteInDebate(String debateId, String targetStance, boolean support) throws ProtocolHandler.HandlerException
      Votes on a position in an ongoing debate.
      Parameters:
      debateId - Debate session ID
      targetStance - Stance being voted on
      support - True to support, false to oppose
      Throws:
      ProtocolHandler.HandlerException

    • counterArgument

      public void counterArgument(String debateId, String targetAgent, String counterArgument, String alternative) throws ProtocolHandler.HandlerException
      Submits a counter-argument in an ongoing debate.
      Parameters:
      debateId - Debate session ID
      targetAgent - Agent being countered
      counterArgument - The counter-argument
      alternative - Optional alternative proposal
      Throws:
      ProtocolHandler.HandlerException

    • getDebate

      public DebateProtocolHandler.DebateSession getDebate(String debateId)
      Gets an active debate session.
      Parameters:
      debateId - Debate session ID
      Returns:
      DebateSession or null if not found

    • getAgent

      public com.tnsai.agents.Agent getAgent()
      Gets the agent managed by this protocol manager.
      Specified by:
      getAgent in interface com.tnsai.protocols.ProtocolManagerHandle
      Returns:
      Agent instance

    • isStarted

      public boolean isStarted()
      Checks if manager is started.
      Specified by:
      isStarted in interface com.tnsai.protocols.ProtocolManagerHandle
      Returns:
      true if started

    • hasParadigm

      public boolean hasParadigm(String paradigm)
      Checks if a paradigm is configured.
      Specified by:
      hasParadigm in interface com.tnsai.protocols.ProtocolManagerHandle
      Parameters:
      paradigm - Paradigm name (DIRECT, BROADCAST, PUBSUB, REQUEST_REPLY)
      Returns:
      true if configured

    • getParadigms

      public Set<String> getParadigms()
      Gets all configured paradigms.
      Specified by:
      getParadigms in interface com.tnsai.protocols.ProtocolManagerHandle
      Returns:
      Set of paradigm names