程序包 io.agentscope.core.message

类 Msg

java.lang.Object
io.agentscope.core.message.Msg
所有已实现的接口:
State
直接已知子类:
AssistantMessage, SystemMessage, ToolResultMessage, UserMessage
public class Msg extends Object implements State
Represents a message in the AgentScope framework.

Messages are the primary communication unit between agents, users, and tools. Each message has a role (user, assistant, system, or tool), content blocks, and optional metadata.

Content blocks can include text, images, audio, video, thinking content, tool use blocks, and tool result blocks. The content is stored as an immutable list for thread safety.

Messages are serialized to JSON using Jackson and include a unique ID for tracking purposes.

  • 字段详细资料

    • METADATA_GENERATE_REASON

      public static final String METADATA_GENERATE_REASON
      Metadata key for storing the generate reason.
      另请参阅:

    • METADATA_CONFIRM_RESULTS

      public static final String METADATA_CONFIRM_RESULTS
      Metadata key for carrying a List<ConfirmResult> when resuming a Permission HITL pause. The receiving ReActAgent.call(msgs) extracts and applies these results to the ASKING tool calls in context.
      另请参阅:

    • METADATA_SYNTHETIC

      public static final String METADATA_SYNTHETIC
      Metadata key (boolean) marking a message as synthetic: framework-injected rather than authored by the user, the model, or a tool. Synthetic messages (e.g. the per-turn todo reminder produced by TaskReminderMiddleware) are appended transiently to the reasoning input and are not persisted into AgentState.context; this flag lets any downstream consumer that does observe such a message recognise and skip it (memory extraction, compaction, RAG recall).
      另请参阅:

    • METADATA_REMINDER_KIND

      public static final String METADATA_REMINDER_KIND
      Metadata key (string) describing the kind of synthetic reminder carried by a message, e.g. "todo_state". Only meaningful when METADATA_SYNTHETIC is true.
      另请参阅:

  • 构造器详细资料

    • Msg

      protected Msg(String id, String name, MsgRole role, List<ContentBlock> content, Map<String,Object> metadata, String timestamp, ChatUsage usage)
      Creates a new message with the specified fields.
      参数:
      id - Unique identifier for the message
      name - Optional name for the message (can be null)
      role - The role of the message sender (user, assistant, system, or tool)
      content - List of content blocks that make up the message content
      metadata - Optional metadata map for additional information
      timestamp - Optional timestamp string (if null, will be generated automatically)

  • 方法详细资料

    • builder

      public static Msg.Builder builder()
      Creates a new message builder with a randomly generated ID.
      返回:
      A new builder instance

    • builderForRole

      public static Msg.Builder builderForRole(MsgRole role)
      Creates a builder for the concrete Msg subtype that matches the given role.

      Unlike builder() (which produces a plain Msg), this factory returns the role-specific builder so the resulting instance is the appropriate subtype: UserMessage for MsgRole.USER, AssistantMessage for MsgRole.ASSISTANT, SystemMessage for MsgRole.SYSTEM, and ToolResultMessage for MsgRole.TOOL. A null role falls back to the base builder().

      The returned builder's build() is overridden covariantly, so the declared Msg.Builder static type still yields the concrete subtype instance at runtime.

      参数:
      role - the role whose concrete message subtype should be built
      返回:
      a role-specific builder, or the base builder when role is null

    • generateId

      protected static String generateId()
      Generates a random UUID string for use as a message ID. Exposed to subclasses so their convenience constructors can mirror the behaviour of Msg.Builder without re-implementing UUID logic.

    • currentTimestamp

      protected static String currentTimestamp()
      Returns the current wall-clock timestamp in this class's canonical format. Exposed to subclasses so their convenience constructors can stamp messages identically to Msg.Builder.

    • getId

      public String getId()
      Gets the unique identifier of this message.
      返回:
      The message ID

    • getName

      public String getName()
      Gets the optional name of this message.
      返回:
      The message name, or null if not set

    • getRole

      public MsgRole getRole()
      Gets the role of the message sender.
      返回:
      The message role (user, assistant, system, or tool)

    • getContent

      public List<ContentBlock> getContent()
      Gets the immutable list of content blocks in this message.
      返回:
      The content blocks list, may be empty but never null

    • getMetadata

      public Map<String,Object> getMetadata()
      Gets the metadata associated with this message.
      返回:
      The metadata map, or null if not set

    • getTimestamp

      public String getTimestamp()
      Gets the timestamp of this message.
      返回:
      The timestamp string in format "yyyy-MM-dd HH:mm:ss.SSS"

    • getUsage

      public ChatUsage getUsage()
      Gets the token usage information associated with this message.

      Aligns with Python Msg.usage (PR #1639). When populated, contains the input/output token counts from the model call that produced this message.

      返回:
      The usage object, or null if not available

    • hasContentBlocks

      public <T extends ContentBlock> boolean hasContentBlocks(Class<T> blockClass)
      Check if this message has content blocks of the specified type (type-safe).
      类型参数:
      T - Content block type
      参数:
      blockClass - Block class to check for
      返回:
      true if at least one block of the type exists

    • getContentBlocks

      public <T extends ContentBlock> List<T> getContentBlocks(Class<T> blockClass)
      Get all content blocks of the specified type (type-safe).
      类型参数:
      T - Content block type
      参数:
      blockClass - Block class to filter for
      返回:
      List of matching blocks

    • getFirstContentBlock

      public ContentBlock getFirstContentBlock()
      Get the first content block, or null if empty.
      返回:
      First content block or null

    • getFirstContentBlock

      public <T extends ContentBlock> T getFirstContentBlock(Class<T> blockClass)
      Get the first content block of the specified type (type-safe).
      类型参数:
      T - Content block type
      参数:
      blockClass - Block class to search for
      返回:
      First matching block or null

    • hasStructuredData

      public boolean hasStructuredData()
      Check if this message contains structured data in metadata.
      返回:
      true if metadata is present and non-empty

    • getStructuredData

      public <T> T getStructuredData(Class<T> targetClass)
      Extract structured data from message metadata and convert it to the specified type.

      This method is useful when the message contains structured input from a user agent or structured output from an LLM. The metadata map is converted to a Java object using Jackson's ObjectMapper.

      Example usage: 

      
 public class TaskPlan {
     public String goal;
     public int priority;
 }

 Msg msg = userAgent.call(null, TaskPlan.class).block();
 TaskPlan plan = msg.getStructuredData(TaskPlan.class);
      类型参数:
      T - Type of the structured data
      参数:
      targetClass - The class to convert metadata into
      返回:
      The structured data object
      抛出:
      IllegalStateException - if no metadata exists
      IllegalArgumentException - if conversion fails

    • getStructuredData

      public Map<String,Object> getStructuredData(boolean mutable)
      Extract structured data from message metadata and convert it to the java.util.Map.

      This method is useful when the message contains structured input from a user agent or structured output from an LLM. support for using dynamic schema processing

      Example usage: 

      
 String json = """
         {
                 						 "type": "object",
                 						 "properties": {
                 						   "productName": {
                 							 "type": "string"
                 						                                              },
                 						   "features": {
                 							 "type": "array",
                 							 "items": {
                 							   "type": "string"                                             *                                           }
                 						   },
                 						   "pricing": {
                 							 "type": "object",
                 							 "properties": {
                 							   "amount": {
                                                  e": "number"
                 							   },
                 							   "currency": {
                                                  e": "string"
                                             }
                                           }
                 						   },
                 						   "ratings": {
                 							 "type": "object",
                 							 "additionalProperties": {
                                                   e": "integer"
                                           }
                                         }
                                       }
                 					   }
         """;
  JsonNode sampleJsonNode = new ObjectMapper().readTree(json);
   Msg msg = agent.call(input, sampleJsonNode).block(TEST_TIMEOUT);
   Map<String, Object> structuredData = msg.getStructuredData(false);
      返回:
      The copied metadata
      抛出:
      IllegalStateException - if no metadata exists

    • getTextContent

      public String getTextContent()
      Extracts plain text content from this message.

      This method concatenates all text blocks in the message, joined by newlines. If the message contains no text blocks, an empty string is returned.

      返回:
      The concatenated text content from all text blocks, or empty string if none

    • getChatUsage

      public ChatUsage getChatUsage()
      Gets the chat usage statistics from this message's metadata.

      This method retrieves the accumulated token usage information that was recorded during model generation. Returns null if no usage information is available.

      Example usage: 

      
 Msg response = agent.call(userMsg).block();
 ChatUsage usage = response.getChatUsage();
 if (usage != null) {
     System.out.println("Input tokens: " + usage.getInputTokens());
     System.out.println("Output tokens: " + usage.getOutputTokens());
     System.out.println("Total tokens: " + usage.getTotalTokens());
     System.out.println("Time: " + usage.getTime() + "s");
 }
      返回:
      The ChatUsage object containing token counts and timing, or null if not available

    • getGenerateReason

      public GenerateReason getGenerateReason()
      Gets the reason why this message was generated.

      This method helps users understand the context of agent execution:

      返回:
      The generate reason, defaults to GenerateReason.MODEL_STOP if not set

    • withGenerateReason

      public Msg withGenerateReason(GenerateReason reason)
      Creates a new message with the specified generate reason.

      This method returns a new Msg instance with the updated generate reason stored in metadata. The original message is not modified (immutable).

      参数:
      reason - The generate reason to set
      返回:
      A new Msg instance with the updated generate reason

    • withContent

      public Msg withContent(List<ContentBlock> newContent)
      Returns a copy of this message with the given content blocks.
      参数:
      newContent - the replacement content blocks
      返回:
      a new Msg with identical metadata but replaced content