Skip to content

Build and run agents you can see, understand and trust.

fix(formatter): preserve HintBlock in multi-agent requests (#3321)

zhengguangzhuo3aa1bc0518b8
diff --git a/src/agentscope/formatter/_anthropic_formatter.py b/src/agentscope/formatter/_anthropic_formatter.py
index 3bb09d69c..fd2790716 100644
--- a/src/agentscope/formatter/_anthropic_formatter.py
+++ b/src/agentscope/formatter/_anthropic_formatter.py
@@ -460,16 +460,38 @@ class AnthropicMultiAgentFormatter(_AnthropicFormatterBase):
await self._format_messages(group),
)
case "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the Anthropic chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The Anthropic user-message representation.
+ """
+ return await AnthropicChatFormatter(
+ input_types=self.input_types,
+ ).format(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
@@ -519,20 +541,18 @@ class AnthropicMultiAgentFormatter(_AnthropicFormatterBase):
},
)
- if conversation_blocks and is_first:
+ if conversation_blocks:
+ prompt = self.conversation_history_prompt if is_first else ""
if conversation_blocks[0].get("text"):
conversation_blocks[0]["text"] = (
- self.conversation_history_prompt
- + "<history>\n"
- + conversation_blocks[0]["text"]
+ prompt + "<history>\n" + conversation_blocks[0]["text"]
)
else:
conversation_blocks.insert(
0,
{
"type": "text",
- "text": self.conversation_history_prompt
- + "<history>\n",
+ "text": prompt + "<history>\n",
},
)
@@ -543,7 +563,6 @@ class AnthropicMultiAgentFormatter(_AnthropicFormatterBase):
{"type": "text", "text": "</history>"},
)
- if conversation_blocks:
return [
{
"role": "user",
diff --git a/src/agentscope/formatter/_dashscope_formatter.py b/src/agentscope/formatter/_dashscope_formatter.py
index d7c866f9f..c714fe6fe 100644
--- a/src/agentscope/formatter/_dashscope_formatter.py
+++ b/src/agentscope/formatter/_dashscope_formatter.py
@@ -523,12 +523,17 @@ class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):
await self._format_tool_sequence(group),
)
case "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
+ prompt_requires_text=True,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
@@ -543,6 +548,22 @@ class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):
input_types=self.input_types,
).format(msgs)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the DashScope chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The DashScope user-message representation.
+ """
+ return await self._format_tool_sequence(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
diff --git a/src/agentscope/formatter/_deepseek_formatter.py b/src/agentscope/formatter/_deepseek_formatter.py
index 845b97292..e955f30b3 100644
--- a/src/agentscope/formatter/_deepseek_formatter.py
+++ b/src/agentscope/formatter/_deepseek_formatter.py
@@ -291,12 +291,16 @@ class DeepSeekMultiAgentFormatter(_OpenAIFormatterBase):
await self._format_tool_sequence(group),
)
case "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
@@ -311,6 +315,22 @@ class DeepSeekMultiAgentFormatter(_OpenAIFormatterBase):
input_types=self.input_types,
).format(msgs)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the DeepSeek chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The DeepSeek user-message representation.
+ """
+ return await self._format_tool_sequence(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
diff --git a/src/agentscope/formatter/_formatter_base.py b/src/agentscope/formatter/_formatter_base.py
index ff34e331a..5a57db733 100644
--- a/src/agentscope/formatter/_formatter_base.py
+++ b/src/agentscope/formatter/_formatter_base.py
@@ -5,13 +5,14 @@ import mimetypes
import tempfile
from abc import abstractmethod
from fnmatch import fnmatch
-from typing import Any, List, AsyncGenerator
+from typing import Any, AsyncGenerator, Awaitable, Callable, List
from pydantic import BaseModel, Field
from ..message import (
Msg,
DataBlock,
+ HintBlock,
TextBlock,
URLSource,
)
@@ -229,3 +230,131 @@ class FormatterBase(BaseModel):
if group_type:
yield group_type, group
+
+ @staticmethod
+ def _split_agent_messages_at_hints(
+ msgs: list[Msg],
+ ) -> list[tuple[bool, list[Msg]]]:
+ """Split agent messages around hints while preserving message order.
+
+ Args:
+ msgs (`list[Msg]`):
+ The non-tool messages in one agent-message group.
+
+ Returns:
+ `list[tuple[bool, list[Msg]]]`:
+ Ordered segments. The boolean is ``True`` for a segment that
+ contains a single ``HintBlock`` and ``False`` for history
+ segments. Messages without hints are returned unchanged as a
+ single history segment.
+ """
+ if not any(
+ isinstance(block, HintBlock)
+ for msg in msgs
+ for block in msg.get_content_blocks()
+ ):
+ return [(False, msgs)] if msgs else []
+
+ segments: list[tuple[bool, list[Msg]]] = []
+ history_messages: list[Msg] = []
+
+ for msg in msgs:
+ history_blocks = []
+ for block in msg.get_content_blocks():
+ if isinstance(block, HintBlock):
+ if history_blocks:
+ history_messages.append(
+ msg.model_copy(update={"content": history_blocks}),
+ )
+ history_blocks = []
+
+ if history_messages:
+ segments.append((False, history_messages))
+ history_messages = []
+
+ segments.append(
+ (
+ True,
+ [msg.model_copy(update={"content": [block]})],
+ ),
+ )
+ else:
+ history_blocks.append(block)
+
+ if history_blocks:
+ history_messages.append(
+ msg.model_copy(update={"content": history_blocks}),
+ )
+
+ if history_messages:
+ segments.append((False, history_messages))
+
+ return segments
+
+ async def _format_agent_message_with_hints(
+ self,
+ msgs: list[Msg],
+ is_first: bool,
+ format_agent_message: Callable[
+ [list[Msg], bool],
+ Awaitable[list[Any]],
+ ],
+ *,
+ prompt_requires_text: bool = False,
+ ) -> tuple[list[Any], bool]:
+ """Format history and route each hint through its chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ The non-tool messages in one agent-message group.
+ is_first (`bool`):
+ Whether the first history segment should include its prompt.
+ format_agent_message (`Callable`):
+ The provider-specific history formatter.
+ prompt_requires_text (`bool`):
+ Whether media-only history omits the history prompt.
+
+ Returns:
+ `tuple[list[Any], bool]`:
+ The formatted messages and whether a history segment was
+ eligible for the prompt.
+ """
+ formatted_messages: list[Any] = []
+ has_prompt_segment = False
+
+ for is_hint, segment in self._split_agent_messages_at_hints(msgs):
+ if is_hint:
+ formatted_messages.extend(
+ await self._format_hint_message(segment),
+ )
+ continue
+
+ formatted_history = await format_agent_message(segment, is_first)
+ formatted_messages.extend(formatted_history)
+ if formatted_history and (
+ not prompt_requires_text
+ or any(msg.has_content_blocks("text") for msg in segment)
+ ):
+ is_first = False
+ has_prompt_segment = True
+
+ return formatted_messages, has_prompt_segment
+
+ async def _format_hint_message(self, msgs: list[Msg]) -> list[Any]:
+ """Format a HintBlock message through the provider's chat formatter.
+
+ Multi-agent formatters that delegate tool sequences to a chat
+ formatter can reuse that path. Providers with a different delegation
+ override this method.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[Any]`:
+ The provider-specific user-message representation.
+ """
+ raise RuntimeError(
+ "A provider chat formatter is required for HintBlock messages.",
+ )
diff --git a/src/agentscope/formatter/_gemini_formatter.py b/src/agentscope/formatter/_gemini_formatter.py
index 5529468c3..7aaac8d6a 100644
--- a/src/agentscope/formatter/_gemini_formatter.py
+++ b/src/agentscope/formatter/_gemini_formatter.py
@@ -393,12 +393,16 @@ class GeminiMultiAgentFormatter(_GeminiFormatterBase):
await self._format_tool_sequence(group),
)
case "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
@@ -413,6 +417,22 @@ class GeminiMultiAgentFormatter(_GeminiFormatterBase):
input_types=self.input_types,
).format(msgs)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the Gemini chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The Gemini user-message representation.
+ """
+ return await self._format_tool_sequence(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
diff --git a/src/agentscope/formatter/_minimax_formatter.py b/src/agentscope/formatter/_minimax_formatter.py
index 944b3f776..7857bf173 100644
--- a/src/agentscope/formatter/_minimax_formatter.py
+++ b/src/agentscope/formatter/_minimax_formatter.py
@@ -9,7 +9,7 @@ from ._anthropic_formatter import (
AnthropicChatFormatter,
AnthropicMultiAgentFormatter,
)
-from ..message import DataBlock
+from ..message import DataBlock, Msg
class MiniMaxChatFormatter(AnthropicChatFormatter):
@@ -48,6 +48,24 @@ class MiniMaxMultiAgentFormatter(AnthropicMultiAgentFormatter):
),
)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the MiniMax chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The MiniMax user-message representation.
+ """
+ return await MiniMaxChatFormatter(
+ input_types=self.input_types,
+ ).format(msgs)
+
def _format_anthropic_data_block(
self,
block: DataBlock,
diff --git a/src/agentscope/formatter/_moonshot_formatter.py b/src/agentscope/formatter/_moonshot_formatter.py
index 4d2098dba..172a589e3 100644
--- a/src/agentscope/formatter/_moonshot_formatter.py
+++ b/src/agentscope/formatter/_moonshot_formatter.py
@@ -422,12 +422,17 @@ class MoonshotMultiAgentFormatter(_OpenAIFormatterBase):
await self._format_tool_sequence(group),
)
case "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
+ prompt_requires_text=True,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
@@ -442,6 +447,22 @@ class MoonshotMultiAgentFormatter(_OpenAIFormatterBase):
input_types=self.input_types,
).format(msgs)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the Moonshot chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The Moonshot user-message representation.
+ """
+ return await self._format_tool_sequence(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
diff --git a/src/agentscope/formatter/_ollama_formatter.py b/src/agentscope/formatter/_ollama_formatter.py
index 3d7eb9a59..403d12ef0 100644
--- a/src/agentscope/formatter/_ollama_formatter.py
+++ b/src/agentscope/formatter/_ollama_formatter.py
@@ -383,12 +383,16 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):
await self._format_tool_sequence(group),
)
case "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
@@ -402,6 +406,22 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):
input_types=self.input_types,
).format(msgs)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the Ollama chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The Ollama user-message representation.
+ """
+ return await self._format_tool_sequence(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
@@ -440,20 +460,18 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):
{"text": "\n".join(accumulated_text)},
)
- if conversation_blocks and is_first:
+ if conversation_blocks:
+ prompt = self.conversation_history_prompt if is_first else ""
if conversation_blocks[0].get("text"):
conversation_blocks[0]["text"] = (
- self.conversation_history_prompt
- + "<history>\n"
- + conversation_blocks[0]["text"]
+ prompt + "<history>\n" + conversation_blocks[0]["text"]
)
else:
conversation_blocks.insert(
0,
{
- "text": self.conversation_history_prompt
- + "<history>\n",
+ "text": prompt + "<history>\n",
},
)
diff --git a/src/agentscope/formatter/_openai_formatter.py b/src/agentscope/formatter/_openai_formatter.py
index ea8e1fe9f..7d0bb4efd 100644
--- a/src/agentscope/formatter/_openai_formatter.py
+++ b/src/agentscope/formatter/_openai_formatter.py
@@ -528,12 +528,17 @@ class OpenAIMultiAgentFormatter(_OpenAIFormatterBase):
await self._format_tool_sequence(group),
)
case "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
+ prompt_requires_text=True,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
@@ -548,6 +553,22 @@ class OpenAIMultiAgentFormatter(_OpenAIFormatterBase):
input_types=self.input_types,
).format(msgs)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the OpenAI chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The OpenAI user-message representation.
+ """
+ return await self._format_tool_sequence(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
diff --git a/src/agentscope/formatter/_openai_response_formatter.py b/src/agentscope/formatter/_openai_response_formatter.py
index 914c01fac..473f5c78c 100644
--- a/src/agentscope/formatter/_openai_response_formatter.py
+++ b/src/agentscope/formatter/_openai_response_formatter.py
@@ -463,12 +463,16 @@ class OpenAIResponseMultiAgentFormatter(_OpenAIResponseFormatterBase):
await self._format_tool_sequence(group),
)
elif typ == "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
@@ -492,6 +496,22 @@ class OpenAIResponseMultiAgentFormatter(_OpenAIResponseFormatterBase):
input_types=self.input_types,
).format(msgs)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the OpenAI Responses formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The Responses API user-message representation.
+ """
+ return await self._format_tool_sequence(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
diff --git a/src/agentscope/formatter/_volcengine_formatter.py b/src/agentscope/formatter/_volcengine_formatter.py
index 9d0e9ba1f..3349ad540 100644
--- a/src/agentscope/formatter/_volcengine_formatter.py
+++ b/src/agentscope/formatter/_volcengine_formatter.py
@@ -339,12 +339,17 @@ class VolcengineMultiAgentFormatter(_VolcengineFormatterBase):
await self._format_tool_sequence(group),
)
case "agent_message":
- formatted_group = await self._format_agent_message(
+ (
+ formatted_group,
+ has_history,
+ ) = await self._format_agent_message_with_hints(
group,
is_first_agent_message,
+ self._format_agent_message,
+ prompt_requires_text=True,
)
formatted_msgs.extend(formatted_group)
- if formatted_group:
+ if has_history:
is_first_agent_message = False
return formatted_msgs
@@ -359,6 +364,22 @@ class VolcengineMultiAgentFormatter(_VolcengineFormatterBase):
input_types=self.input_types,
).format(msgs)
+ async def _format_hint_message(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format hint messages with the Volcengine chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The Volcengine user-message representation.
+ """
+ return await self._format_tool_sequence(msgs)
+
async def _format_agent_message(
self,
msgs: list[Msg],
diff --git a/src/agentscope/formatter/_xai_formatter.py b/src/agentscope/formatter/_xai_formatter.py
index 0032e43c3..9e158cec5 100644
--- a/src/agentscope/formatter/_xai_formatter.py
+++ b/src/agentscope/formatter/_xai_formatter.py
@@ -369,8 +369,9 @@ class XAIMultiAgentFormatter(FormatterBase):
Produces ``xai_sdk`` protobuf ``Message`` objects (same as
:class:`XAIChatFormatter`). Prior agent-to-agent messages are collapsed
into a single ``user`` message with ``<history></history>`` tags; the
- images of those messages are appended to the same ``user`` message, and
- tool call / result sequences are delegated to :class:`XAIChatFormatter`.
+ images of those messages are appended to the same ``user`` message.
+ Hint blocks and tool call / result sequences are delegated to
+ :class:`XAIChatFormatter`.
.. note:: ``format()`` returns ``list[Any]`` (protobuf messages), not
``list[dict]``.
@@ -436,29 +437,53 @@ class XAIMultiAgentFormatter(FormatterBase):
).format(group),
)
elif typ == "agent_message":
- history_text = self._build_history_text(
+ for is_hint, segment in self._split_agent_messages_at_hints(
group,
- is_first=is_first_agent_message,
- )
- user_args = _xai_user_args_from_blocks(
- [
- block
- for msg in group
- for block in msg.get_content_blocks()
- if isinstance(block, DataBlock)
- ],
- image,
- self.supported_input_media_types,
- )
- if history_text:
- user_args.insert(0, history_text)
- if user_args:
- xai_messages.append(user(*user_args))
+ ):
+ if is_hint:
+ xai_messages.extend(
+ await self._format_hint_message(segment),
+ )
+ continue
+
+ history_text = self._build_history_text(
+ segment,
+ is_first=is_first_agent_message,
+ )
+ user_args = _xai_user_args_from_blocks(
+ [
+ block
+ for msg in segment
+ for block in msg.get_content_blocks()
+ if isinstance(block, DataBlock)
+ ],
+ image,
+ self.supported_input_media_types,
+ )
if history_text:
- is_first_agent_message = False
+ user_args.insert(0, history_text)
+ if user_args:
+ xai_messages.append(user(*user_args))
+ if history_text:
+ is_first_agent_message = False
return xai_messages
+ async def _format_hint_message(self, msgs: list[Msg]) -> list[Any]:
+ """Format hint messages with the xAI chat formatter.
+
+ Args:
+ msgs (`list[Msg]`):
+ One message containing a single ``HintBlock``.
+
+ Returns:
+ `list[Any]`:
+ The xAI user-message representation.
+ """
+ return await XAIChatFormatter(
+ input_types=self.input_types,
+ ).format(msgs)
+
def _build_history_text(self, msgs: list[Msg], *, is_first: bool) -> str:
"""Build a ``<history>…</history>`` text block from agent messages.
diff --git a/tests/formatter_multi_agent_hint_test.py b/tests/formatter_multi_agent_hint_test.py
new file mode 100644
index 000000000..f8e1ff739
--- /dev/null
+++ b/tests/formatter_multi_agent_hint_test.py
@@ -0,0 +1,184 @@
+# -*- coding: utf-8 -*-
+"""Regression tests for HintBlock handling in multi-agent formatters."""
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+ AnthropicChatFormatter,
+ AnthropicMultiAgentFormatter,
+ DashScopeChatFormatter,
+ DashScopeMultiAgentFormatter,
+ DeepSeekChatFormatter,
+ DeepSeekMultiAgentFormatter,
+ GeminiChatFormatter,
+ GeminiMultiAgentFormatter,
+ MiniMaxChatFormatter,
+ MiniMaxMultiAgentFormatter,
+ MoonshotChatFormatter,
+ MoonshotMultiAgentFormatter,
+ OllamaChatFormatter,
+ OllamaMultiAgentFormatter,
+ OpenAIChatFormatter,
+ OpenAIMultiAgentFormatter,
+ OpenAIResponseFormatter,
+ OpenAIResponseMultiAgentFormatter,
+ VolcengineChatFormatter,
+ VolcengineMultiAgentFormatter,
+)
+from agentscope.message import (
+ AssistantMsg,
+ Base64Source,
+ DataBlock,
+ HintBlock,
+ TextBlock,
+ UserMsg,
+)
+
+
+FORMATTER_PAIRS = (
+ (AnthropicMultiAgentFormatter, AnthropicChatFormatter),
+ (DashScopeMultiAgentFormatter, DashScopeChatFormatter),
+ (DeepSeekMultiAgentFormatter, DeepSeekChatFormatter),
+ (GeminiMultiAgentFormatter, GeminiChatFormatter),
+ (MiniMaxMultiAgentFormatter, MiniMaxChatFormatter),
+ (MoonshotMultiAgentFormatter, MoonshotChatFormatter),
+ (OllamaMultiAgentFormatter, OllamaChatFormatter),
+ (OpenAIMultiAgentFormatter, OpenAIChatFormatter),
+ (OpenAIResponseMultiAgentFormatter, OpenAIResponseFormatter),
+ (VolcengineMultiAgentFormatter, VolcengineChatFormatter),
+)
+
+
+class TestMultiAgentHintFormatting(IsolatedAsyncioTestCase):
+ """Check the complete provider payload produced for HintBlock messages."""
+
+ async def test_hint_only_message_matches_chat_formatter(self) -> None:
+ """A memory-only hint is emitted instead of disappearing."""
+ hint_msg = AssistantMsg(
+ name="memory",
+ content=[HintBlock(hint="Remember the user's preference.")],
+ )
+ question_msg = UserMsg(
+ name="alice",
+ content="What should I remember?",
+ )
+
+ for multi_agent_cls, chat_cls in FORMATTER_PAIRS:
+ with self.subTest(formatter=multi_agent_cls.__name__):
+ multi_agent_formatter = multi_agent_cls()
+ chat_formatter = chat_cls()
+ actual = await multi_agent_formatter.format(
+ [hint_msg, question_msg],
+ )
+ expected = await chat_formatter.format([hint_msg])
+ expected.extend(
+ await multi_agent_formatter.format([question_msg]),
+ )
+
+ self.assertListEqual(expected, actual)
+
+ async def test_history_after_hint_keeps_its_tags(self) -> None:
+ """Each text segment is history, with the prompt on the first."""
+ messages = [
+ UserMsg("user", "first"),
+ AssistantMsg("Alice", [HintBlock(hint="note")]),
+ UserMsg("user", "second"),
+ ]
+ for cls in (
+ AnthropicMultiAgentFormatter,
+ MiniMaxMultiAgentFormatter,
+ OllamaMultiAgentFormatter,
+ ):
+ with self.subTest(formatter=cls.__name__):
+ formatter = cls(conversation_history_prompt="Custom\n")
+ separator = "\n" if cls is OllamaMultiAgentFormatter else " "
+ texts = [
+ f"Custom\n<history>\nuser:{separator}first\n</history>",
+ "note",
+ f"<history>\nuser:{separator}second\n</history>",
+ ]
+ expected = [
+ {
+ "role": "user",
+ "content": (
+ text
+ if cls is OllamaMultiAgentFormatter
+ else [{"type": "text", "text": text}]
+ ),
+ }
+ for text in texts
+ ]
+ self.assertEqual(await formatter.format(messages), expected)
+
+ async def test_image_before_hint_preserves_history_prompt(self) -> None:
+ """An image-only segment leaves the prompt for the first text."""
+ source = Base64Source(media_type="image/png", data="YQ==")
+ messages = [
+ UserMsg("user", [DataBlock(source=source)]),
+ AssistantMsg("Alice", [HintBlock(hint="note")]),
+ UserMsg("user", "second"),
+ ]
+ image = {
+ "type": "image_url",
+ "image_url": {"url": "data:image/png;base64,YQ=="},
+ }
+ hint = {"type": "text", "text": "note"}
+ history = {
+ "type": "text",
+ "text": "Custom\n<history>\nuser: second\n</history>",
+ }
+ expected = [
+ {"role": "user", "content": [part]}
+ for part in (image, hint, history)
+ ]
+ for cls in (
+ OpenAIMultiAgentFormatter,
+ DashScopeMultiAgentFormatter,
+ MoonshotMultiAgentFormatter,
+ VolcengineMultiAgentFormatter,
+ ):
+ with self.subTest(formatter=cls.__name__):
+ formatter = cls(conversation_history_prompt="Custom\n")
+ self.assertEqual(await formatter.format(messages), expected)
+
+ async def test_hint_inside_message_preserves_history_order(self) -> None:
+ """A standalone hint separates two tagged history messages."""
+ mixed_msg = AssistantMsg(
+ name="memory",
+ content=[
+ TextBlock(text="Before"),
+ HintBlock(hint="Keep this instruction."),
+ TextBlock(text="After"),
+ ],
+ )
+ for cls, _ in FORMATTER_PAIRS:
+ with self.subTest(formatter=cls.__name__):
+ formatter = cls(conversation_history_prompt="Custom\n")
+ separator = "\n" if cls is OllamaMultiAgentFormatter else " "
+ texts = [
+ f"Custom\n<history>\nmemory:{separator}Before\n</history>",
+ "Keep this instruction.",
+ f"<history>\nmemory:{separator}After\n</history>",
+ ]
+ if cls is GeminiMultiAgentFormatter:
+ expected = [
+ {"role": "user", "parts": [{"text": t}]} for t in texts
+ ]
+ elif cls in (
+ DeepSeekMultiAgentFormatter,
+ OllamaMultiAgentFormatter,
+ ):
+ expected = [{"role": "user", "content": t} for t in texts]
+ else:
+ kind = (
+ "input_text"
+ if cls is OpenAIResponseMultiAgentFormatter
+ else "text"
+ )
+ expected = [
+ {
+ "role": "user",
+ "content": [{"type": kind, "text": t}],
+ }
+ for t in texts
+ ]
+ self.assertEqual(await formatter.format([mixed_msg]), expected)
diff --git a/tests/formatter_xai_test.py b/tests/formatter_xai_test.py
index d2ab7a9ba..027c81ff5 100644
--- a/tests/formatter_xai_test.py
+++ b/tests/formatter_xai_test.py
@@ -704,6 +704,59 @@ class TestXAIFormatter( # pylint: disable=too-many-public-methods
res,
)
+ async def test_multiagent_hint_only_message_precedes_history(self) -> None:
+ """A hint-only message is emitted before following history."""
+ fmt = XAIMultiAgentFormatter()
+ msgs = [
+ AssistantMsg(
+ name="memory",
+ content=[HintBlock(hint="Remember the user's preference.")],
+ ),
+ UserMsg(name="alice", content="What should I remember?"),
+ ]
+
+ res = await fmt.format(msgs)
+
+ self.assertListEqual(
+ [
+ user("Remember the user's preference."),
+ user(
+ fmt.conversation_history_prompt
+ + "<history>\nalice: What should I remember?\n</history>",
+ ),
+ ],
+ res,
+ )
+
+ async def test_multiagent_hint_splits_mixed_history_in_order(self) -> None:
+ """A hint embedded in a message separates ordered history segments."""
+ fmt = XAIMultiAgentFormatter()
+ msg = AssistantMsg(
+ name="memory",
+ content=[
+ TextBlock(text="Context before the hint."),
+ HintBlock(hint="Keep this instruction."),
+ TextBlock(text="Context after the hint."),
+ ],
+ )
+
+ res = await fmt.format([msg])
+
+ self.assertListEqual(
+ [
+ user(
+ fmt.conversation_history_prompt
+ + "<history>\nmemory: Context before the hint.\n"
+ + "</history>",
+ ),
+ user("Keep this instruction."),
+ user(
+ "<history>\nmemory: Context after the hint.\n</history>",
+ ),
+ ],
+ res,
+ )
+
async def test_multiagent_formatter_first_group_has_hist_prompt(
self,
) -> None: