Package com.tnsai.protocols.models

Class Message

java.lang.Object

com.tnsai.protocols.models.Message

public final class Message
extends Object

TnsAI Native Message - The fundamental unit of inter-agent communication.

Supports the BDI (Belief-Desire-Intention) cognitive model and works with all communication paradigms (DirectMessage, Broadcast, PubSub, RequestReply, Debate).

Unlike external protocols (A2A, FIPA), this message structure is native to TnsAI and fully integrates with Agent, Role, Action, and BDI concepts.

Message Structure

 Message
 ├── Identity: id, type, timestamp, conversationId, replyTo
 ├── Routing: sender, receiver, topic (for PubSub)
 ├── Content
 │   ├── Natural Language: content (LLM-powered)
 │   └── Action Request: action, parameters, result, success
 ├── BDI Context: beliefs, intentions, roleContext
 └── Spec: extensible key-value pairs
 

Message Types

Type	Paradigm	Description
DIRECT	Point-to-point	Agent-to-agent private message
BROADCAST	One-to-many	Message to all agents
PUBSUB	Topic-based	Publish to topic subscribers
REQUEST	Request-reply	RPC-style request
REPLY	Request-reply	Response to a request
DEBATE_*	Debate	Multi-agent deliberation

Usage Examples

Natural Language Message

 Message message = Message.builder()
     .type(MessageType.DIRECT)
     .sender(AgentEndpoint.of("assistant"))
     .receiver(AgentEndpoint.of("researcher"))
     .content("Please search for papers on quantum computing")
     .build();
 

Action Request

 Message actionRequest = Message.builder()
     .type(MessageType.REQUEST)
     .sender(AgentEndpoint.of("coordinator"))
     .receiver(AgentEndpoint.of("worker"))
     .action("processData")
     .parameters(Map.of("input", "data.csv", "format", "json"))
     .build();
 

Message with BDI Context

 Message bdiMessage = Message.builder()
     .type(MessageType.DIRECT)
     .sender(AgentEndpoint.of("analyst"))
     .receiver(AgentEndpoint.of("manager"))
     .content("The market analysis is complete")
     .beliefs(List.of(
         Belief.of("marketTrend", "bullish"),
         Belief.of("confidence", "0.85")
     ))
     .intentions(List.of(
         Intention.of("generateReport", "comprehensive")
     ))
     .roleContext("MarketAnalyst")
     .build();
 

Reply Creation

 // Receive a request
 Message request = ...;

 // Create success reply
 Message successReply = request.createSuccessReply(resultData);

 // Create error reply
 Message errorReply = request.createErrorReply("Processing failed: timeout");
 

Immutability

Message instances are immutable and thread-safe. All collections (beliefs, intentions, parameters, metadata) are defensively copied on construction and returned as copies from getters.

Use

invalid reference

#toBuilder()

to create a modified copy:

 Message modified = original.toBuilder()
     .content("Updated content")
     .build();
 

See Also:

• Message.MessageType
• AgentEndpoint
• Belief
• Intention

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	Message.MessageType	Message type defines the communication paradigm.

Method Summary

Modifier and Type	Method	Description
Message	createErrorReply(String error)	Creates an error reply to this message.
Message	createSuccessReply(Object result)	Creates a success reply to this message.
List<Belief>	getBeliefs()	Returns immutable copy of beliefs.
List<Intention>	getIntentions()	Returns immutable copy of intentions.
Map<String,Object>	getParameters()	Returns immutable copy of parameters.
Map<String,Object>	getSpec()	Returns immutable copy of metadata.
boolean	hasBDIContext()	Checks if this message has BDI context (beliefs or intentions).
boolean	isActionRequest()	Checks if this message is an action execution request.
boolean	isNaturalLanguageMessage()	Checks if this message is a natural language message (LLM-powered).
boolean	isReply()	Checks if this message is a reply.
boolean	isSuccessReply()	Checks if this is a successful reply.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

createSuccessReply

public Message createSuccessReply(Object result)

Creates a success reply to this message.

Parameters:

result - Result value

Returns:

Reply message

createErrorReply

public Message createErrorReply(String error)

Creates an error reply to this message.

Parameters:

error - Error message

Returns:

Reply message

getParameters

public Map<String,Object> getParameters()

Returns immutable copy of parameters.

getBeliefs

public List<Belief> getBeliefs()

Returns immutable copy of beliefs.

getIntentions

public List<Intention> getIntentions()

Returns immutable copy of intentions.

getSpec

public Map<String,Object> getSpec()

Returns immutable copy of metadata.

isActionRequest

public boolean isActionRequest()

Checks if this message is an action execution request.

Returns:

true if action is specified

isReply

public boolean isReply()

Checks if this message is a reply.

Returns:

true if type is REPLY

isSuccessReply

public boolean isSuccessReply()

Checks if this is a successful reply.

Returns:

true if reply and success

hasBDIContext

public boolean hasBDIContext()

Checks if this message has BDI context (beliefs or intentions).

Returns:

true if beliefs or intentions present

isNaturalLanguageMessage

public boolean isNaturalLanguageMessage()

Checks if this message is a natural language message (LLM-powered).

Returns:

true if content is specified