Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
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.pyindex 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 = Falsereturn 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.pyindex 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 = Falsereturn 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.pyindex 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 = Falsereturn 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.pyindex ff34e331a..5a57db733 100644--- a/src/agentscope/formatter/_formatter_base.py+++ b/src/agentscope/formatter/_formatter_base.py@@ -5,13 +5,14 @@ import mimetypesimport tempfilefrom abc import abstractmethodfrom fnmatch import fnmatch-from typing import Any, List, AsyncGenerator+from typing import Any, AsyncGenerator, Awaitable, Callable, Listfrom pydantic import BaseModel, Fieldfrom ..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.pyindex 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 = Falsereturn 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.pyindex 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, Msgclass 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.pyindex 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 = Falsereturn 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.pyindex 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 = Falsereturn 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.pyindex 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 = Falsereturn 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.pyindex 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 = Falsereturn 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.pyindex 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 = Falsereturn 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.pyindex 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 collapsedinto 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 = Falsereturn 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.pynew file mode 100644index 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.pyindex 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-methodsres,)+ 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: