Skip to content

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

refactor(model): refactor the chat model implementation (#1564)

DavdGaoa063cdb8901e
diff --git a/pyproject.toml b/pyproject.toml
index 6a684413a..f7a1a63bc 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -51,9 +51,11 @@ dependencies = [
# ------------ Model APIs ------------
gemini = ["google-genai"]
ollama = ["ollama>=0.5.4"]
+xai = ["xai-sdk"]
models = [
"agentscope[ollama]",
"agentscope[gemini]",
+ "agentscope[xai]",
]
# ------------ Full ------------
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index b582f4d86..40ccd4e0d 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -220,7 +220,7 @@ class Agent:
estimated_tokens = await self.model.count_tokens(**kwargs)
# Skip if no compression is needed
- threshold = cfg.trigger_ratio * self.model.context_length
+ threshold = cfg.trigger_ratio * self.model.context_size
if estimated_tokens < threshold:
return
@@ -251,7 +251,7 @@ class Agent:
msgs_to_compress,
msgs_to_reserve,
) = await self._split_context_for_compression(
- cfg.reserve_ratio * self.model.context_length,
+ cfg.reserve_ratio * self.model.context_size,
tools,
)
@@ -268,7 +268,7 @@ class Agent:
msgs_to_compress,
msgs_to_reserve,
) = await self._split_context_for_compression(
- 0 * self.model.context_length,
+ 0 * self.model.context_size,
tools,
)
@@ -313,12 +313,12 @@ class Agent:
messages,
compression_tool_schema,
)
- if estimated_compression_tokens > self.model.context_length:
+ if estimated_compression_tokens > self.model.context_size:
logger.warning(
"The current context length exceeds the model's context "
"length (%d tokens), the compression maybe failed due to "
"insufficient reserved context for compression.",
- self.model.context_length,
+ self.model.context_size,
)
context_overflow = True
@@ -357,7 +357,7 @@ class Agent:
# tokens for compression response
if (
estimated_compression_tokens
- < self.model.context_length * cfg.trigger_ratio
+ < self.model.context_size * cfg.trigger_ratio
):
break
@@ -636,7 +636,7 @@ class Agent:
yield ModelCallStartEvent(
reply_id=self.state.reply_id,
- model_name=self.model.model_name,
+ model_name=self.model.model,
)
# Get the input arguments for the chat model, including messages and
@@ -1865,7 +1865,7 @@ class Agent:
logger.warning(
"Model %s call failed for agent %s. "
"Retrying (%d/%d)...",
- model.model_name,
+ model.model,
self.name,
_ + 1,
self.model_config.max_retries,
diff --git a/src/agentscope/credential/__init__.py b/src/agentscope/credential/__init__.py
new file mode 100644
index 000000000..1084a4c3e
--- /dev/null
+++ b/src/agentscope/credential/__init__.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""The credential module."""
+
+from ._anthropic import AnthropicCredential
+from ._dashscope import DashScopeCredential
+from ._deepseek import DeepSeekCredential
+from ._gemini import GeminiCredential
+from ._kimi import KimiCredential
+from ._ollama import OllamaCredential
+from ._openai import OpenAICredential
+from ._xai import XAICredential
+
+__all__ = [
+ "AnthropicCredential",
+ "DashScopeCredential",
+ "DeepSeekCredential",
+ "GeminiCredential",
+ "KimiCredential",
+ "OllamaCredential",
+ "OpenAICredential",
+ "XAICredential",
+]
+
+
+def list_credential() -> list[dict]:
+ """List the available credential and their schemas, used for frontend to
+ render the credential form."""
+
+ credentials = [
+ AnthropicCredential,
+ DashScopeCredential,
+ DeepSeekCredential,
+ GeminiCredential,
+ KimiCredential,
+ OllamaCredential,
+ OpenAICredential,
+ XAICredential,
+ ]
+
+ return [_.model_json_schema() for _ in credentials]
diff --git a/src/agentscope/credential/_anthropic.py b/src/agentscope/credential/_anthropic.py
new file mode 100644
index 000000000..8a007a94d
--- /dev/null
+++ b/src/agentscope/credential/_anthropic.py
@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+"""The Anthropic credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field, SecretStr, ConfigDict
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase
+
+
+class AnthropicCredential(CredentialBase):
+ """The Anthropic credential model."""
+
+ model_config = ConfigDict(
+ title="Anthropic Credential",
+ )
+
+ type: Literal["anthropic_credential"] = "anthropic_credential"
+ """The credential type."""
+
+ api_key: SecretStr = Field(
+ description="The Anthropic API key",
+ )
+ """The API key."""
+
+ base_url: str | None = Field(
+ description="The base URL for the Anthropic API.",
+ default=None,
+ )
+ """The base URL for the Anthropic API."""
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the AnthropicChatModel class."""
+ from ..model import AnthropicChatModel
+
+ return AnthropicChatModel
diff --git a/src/agentscope/credential/_base.py b/src/agentscope/credential/_base.py
new file mode 100644
index 000000000..a4db8ccfb
--- /dev/null
+++ b/src/agentscope/credential/_base.py
@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""The credential base class."""
+import uuid
+from typing import TYPE_CHECKING, Type
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase, ModelCard
+
+
+class CredentialBase(BaseModel):
+ """The credential base class."""
+
+ id: str = Field(
+ default_factory=lambda: uuid.uuid4().hex,
+ description="The credential id",
+ )
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the :class:`ChatModelBase` subclass that consumes this
+ credential. Subclasses must override this method to return the
+ corresponding chat model class.
+
+ Returns:
+ `Type[ChatModelBase]`:
+ The chat model class that uses this credential.
+ """
+ raise NotImplementedError(
+ f"{cls.__name__} must implement ``get_chat_model_class``.",
+ )
+
+ def list_models(self) -> list["ModelCard"]:
+ """List the candidate chat models that are available under this
+ credential. The default implementation delegates to the
+ :meth:`ChatModelBase.list_models` of the class returned by
+ :meth:`get_chat_model_class`.
+
+ Returns:
+ `list[ModelCard]`:
+ A list of candidate models described by their model cards.
+ """
+ return self.get_chat_model_class().list_models()
diff --git a/src/agentscope/credential/_dashscope.py b/src/agentscope/credential/_dashscope.py
new file mode 100644
index 000000000..bdcc62762
--- /dev/null
+++ b/src/agentscope/credential/_dashscope.py
@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""The DashScope credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase
+
+
+class DashScopeCredential(CredentialBase):
+ """The credential for DashScope API."""
+
+ type: Literal["dashscope_credential"] = "dashscope_credential"
+ """The type of the credential."""
+
+ api_key: SecretStr = Field(
+ description="The DashScope API key.",
+ title="API Key",
+ )
+
+ base_http_api_url: str | None = Field(
+ default=None,
+ title="API Base URL",
+ description="The base URL of the DashScope API.",
+ )
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the DashScopeChatModel class."""
+ from ..model import DashScopeChatModel
+
+ return DashScopeChatModel
diff --git a/src/agentscope/credential/_deepseek.py b/src/agentscope/credential/_deepseek.py
new file mode 100644
index 000000000..e337621a8
--- /dev/null
+++ b/src/agentscope/credential/_deepseek.py
@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+"""The DeepSeek credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase
+
+_DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+
+
+class DeepSeekCredential(CredentialBase):
+ """The DeepSeek credential model."""
+
+ type: Literal["deepseek_credential"] = "deepseek_credential"
+ """The credential type."""
+
+ api_key: SecretStr = Field(
+ description="The DeepSeek API key.",
+ )
+ """The API key."""
+
+ base_url: str = Field(
+ default=_DEEPSEEK_BASE_URL,
+ description="The base URL for the DeepSeek API.",
+ )
+ """The base URL for the DeepSeek API."""
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the DeepSeekChatModel class."""
+ from ..model import DeepSeekChatModel
+
+ return DeepSeekChatModel
diff --git a/src/agentscope/credential/_gemini.py b/src/agentscope/credential/_gemini.py
new file mode 100644
index 000000000..6b281e443
--- /dev/null
+++ b/src/agentscope/credential/_gemini.py
@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""The Google Gemini credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase
+
+
+class GeminiCredential(CredentialBase):
+ """The Google Gemini credential model."""
+
+ type: Literal["gemini_credential"] = "gemini_credential"
+ """The credential type."""
+
+ api_key: SecretStr = Field(
+ description="The Google Gemini API key.",
+ )
+ """The API key."""
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the GeminiChatModel class."""
+ from ..model import GeminiChatModel
+
+ return GeminiChatModel
diff --git a/src/agentscope/credential/_kimi.py b/src/agentscope/credential/_kimi.py
new file mode 100644
index 000000000..3f8369053
--- /dev/null
+++ b/src/agentscope/credential/_kimi.py
@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+"""The Kimi (Moonshot AI) credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase
+
+_KIMI_BASE_URL = "https://api.moonshot.cn/v1"
+
+
+class KimiCredential(CredentialBase):
+ """The Kimi (Moonshot AI) credential model."""
+
+ type: Literal["kimi_credential"] = "kimi_credential"
+ """The credential type."""
+
+ api_key: SecretStr = Field(
+ description="The Kimi (Moonshot AI) API key.",
+ )
+ """The API key."""
+
+ base_url: str = Field(
+ default=_KIMI_BASE_URL,
+ description="The base URL for the Kimi API.",
+ )
+ """The base URL for the Kimi API."""
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the KimiChatModel class."""
+ from ..model import KimiChatModel
+
+ return KimiChatModel
diff --git a/src/agentscope/credential/_ollama.py b/src/agentscope/credential/_ollama.py
new file mode 100644
index 000000000..43154095e
--- /dev/null
+++ b/src/agentscope/credential/_ollama.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""The Ollama credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase
+
+
+class OllamaCredential(CredentialBase):
+ """The Ollama credential model (connection settings)."""
+
+ type: Literal["ollama_credential"] = "ollama_credential"
+ """The credential type."""
+
+ host: str | None = Field(
+ default=None,
+ description=(
+ "The Ollama server host URL. "
+ "Defaults to http://localhost:11434 if not specified."
+ ),
+ )
+ """The Ollama server host URL."""
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the OllamaChatModel class."""
+ from ..model import OllamaChatModel
+
+ return OllamaChatModel
diff --git a/src/agentscope/credential/_openai.py b/src/agentscope/credential/_openai.py
new file mode 100644
index 000000000..24dcc156c
--- /dev/null
+++ b/src/agentscope/credential/_openai.py
@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase
+
+
+class OpenAICredential(CredentialBase):
+ """The OpenAI credential model."""
+
+ type: Literal["openai_credential"] = "openai_credential"
+ """The credential type."""
+
+ api_key: SecretStr = Field(
+ description="The OpenAI API key.",
+ )
+ """The API key."""
+
+ organization: str | None = Field(
+ default=None,
+ description="The OpenAI organization ID.",
+ )
+ """The OpenAI organization ID."""
+
+ base_url: str | None = Field(
+ default=None,
+ description=(
+ "The base URL for the OpenAI API. "
+ "Can be used for OpenAI-compatible endpoints."
+ ),
+ )
+ """Custom base URL for OpenAI-compatible endpoints."""
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the OpenAIChatModel class."""
+ from ..model import OpenAIChatModel
+
+ return OpenAIChatModel
diff --git a/src/agentscope/credential/_xai.py b/src/agentscope/credential/_xai.py
new file mode 100644
index 000000000..17dbb1d80
--- /dev/null
+++ b/src/agentscope/credential/_xai.py
@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""The xAI credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+ from ..model import ChatModelBase
+
+
+class XAICredential(CredentialBase):
+ """The xAI credential model."""
+
+ type: Literal["xai_credential"] = "xai_credential"
+ """The credential type."""
+
+ api_key: SecretStr = Field(
+ description="The xAI API key.",
+ )
+ """The xAI API key."""
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the XAIChatModel class."""
+ from ..model import XAIChatModel
+
+ return XAIChatModel
diff --git a/src/agentscope/formatter/__init__.py b/src/agentscope/formatter/__init__.py
index 974880ce8..6ccf08be7 100644
--- a/src/agentscope/formatter/__init__.py
+++ b/src/agentscope/formatter/__init__.py
@@ -26,6 +26,15 @@ from ._deepseek_formatter import (
DeepSeekChatFormatter,
DeepSeekMultiAgentFormatter,
)
+from ._openai_response_formatter import (
+ OpenAIResponseFormatter,
+ OpenAIResponseMultiAgentFormatter,
+)
+from ._kimi_formatter import KimiChatFormatter, KimiMultiAgentFormatter
+from ._xai_formatter import (
+ XAIChatFormatter,
+ XAIMultiAgentFormatter,
+)
__all__ = [
"FormatterBase",
@@ -41,4 +50,10 @@ __all__ = [
"OllamaMultiAgentFormatter",
"DeepSeekChatFormatter",
"DeepSeekMultiAgentFormatter",
+ "OpenAIResponseFormatter",
+ "OpenAIResponseMultiAgentFormatter",
+ "KimiChatFormatter",
+ "KimiMultiAgentFormatter",
+ "XAIChatFormatter",
+ "XAIMultiAgentFormatter",
]
diff --git a/src/agentscope/formatter/_anthropic_formatter.py b/src/agentscope/formatter/_anthropic_formatter.py
index 0d2061d29..84a09fc6c 100644
--- a/src/agentscope/formatter/_anthropic_formatter.py
+++ b/src/agentscope/formatter/_anthropic_formatter.py
@@ -2,10 +2,12 @@
"""The Anthropic formatter module."""
import base64
import fnmatch
+import json
from abc import ABC
from typing import Any
import requests
+from pydantic import Field
from ._formatter_base import FormatterBase
from .._logging import logger
@@ -26,8 +28,6 @@ class _AnthropicFormatterBase(FormatterBase, ABC):
"""Mixin for formatting Anthropic formatters to avoid duplication between
AnthropicChatFormatter and AnthropicMultiAgentFormatter."""
- supported_input_media_types: list[str]
-
async def _format_messages(
self,
msgs: list[Msg],
@@ -53,6 +53,7 @@ class _AnthropicFormatterBase(FormatterBase, ABC):
messages: list[dict] = []
for msg in msgs:
content_blocks: list = []
+ has_tool_result = False
for block in msg.get_content_blocks():
if isinstance(block, TextBlock):
@@ -61,8 +62,16 @@ class _AnthropicFormatterBase(FormatterBase, ABC):
)
elif isinstance(block, ThinkingBlock):
+ # Anthropic requires the signature to be passed back in
+ # subsequent requests so the API can verify the thinking
+ # block. signature is stored as an extra field and may be
+ # absent on blocks from other providers.
content_blocks.append(
- {"type": "thinking", "thinking": block.thinking},
+ {
+ "type": "thinking",
+ "thinking": block.thinking,
+ "signature": getattr(block, "signature", "") or "",
+ },
)
elif isinstance(block, HintBlock):
@@ -79,7 +88,9 @@ class _AnthropicFormatterBase(FormatterBase, ABC):
"type": "tool_use",
"id": block.id,
"name": block.name,
- "input": block.input,
+ # Anthropic API expects input as a dict, not a
+ # JSON string.
+ "input": json.loads(block.input or "{}"),
},
)
@@ -96,58 +107,23 @@ class _AnthropicFormatterBase(FormatterBase, ABC):
)
for data_block in multimodal_data:
+ if not isinstance(data_block, DataBlock):
+ continue
formatted_block = self._format_anthropic_data_block(
data_block,
)
if formatted_block:
tool_result_content.append(formatted_block)
- # If there's multimodal data, promote to UserMsg
- if multimodal_data:
- # Add tool result first
- content_blocks.append(
- {
- "type": "tool_result",
- "tool_use_id": block.id,
- "content": tool_result_content,
- },
- )
-
- # Flush current message
- if content_blocks:
- messages.append(
- {
- "role": msg.role,
- "content": content_blocks,
- },
- )
- content_blocks = []
-
- # Insert UserMsg with multimodal data
- user_content = []
- for data_block in multimodal_data:
- formatted_block = (
- self._format_anthropic_data_block(data_block)
- )
- if formatted_block:
- user_content.append(formatted_block)
-
- if user_content:
- messages.append(
- {
- "role": "user",
- "content": user_content,
- },
- )
- else:
- # No multimodal data, just add tool result
- content_blocks.append(
- {
- "type": "tool_result",
- "tool_use_id": block.id,
- "content": tool_result_content,
- },
- )
+ content_blocks.append(
+ {
+ "type": "tool_result",
+ "tool_use_id": block.id,
+ "content": tool_result_content,
+ },
+ )
+ # Anthropic requires tool_result to be in a "user" message.
+ has_tool_result = True
else:
logger.warning(
@@ -156,9 +132,12 @@ class _AnthropicFormatterBase(FormatterBase, ABC):
)
if content_blocks:
+ # Anthropic requires `tool_result` blocks to be in a `user`
+ # message regardless of the containing Msg's role.
+ role = "user" if has_tool_result else msg.role
messages.append(
{
- "role": msg.role,
+ "role": role,
"content": content_blocks,
},
)
@@ -228,7 +207,7 @@ class _AnthropicFormatterBase(FormatterBase, ABC):
},
}
elif isinstance(source, URLSource):
- url = source.url
+ url = str(source.url)
if url.startswith("file://"):
# Local file - read and convert to base64
file_path = url.removeprefix("file://")
@@ -265,21 +244,13 @@ class AnthropicChatFormatter(_AnthropicFormatterBase):
entities in the conversation.
"""
- def __init__(
- self,
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- """Initialize the Anthropic chat formatter.
-
- Args:
- supported_input_media_types (`list[str] | None`, optional):
- The list of supported input media types. Defaults to
- ``["image/*"]``.
- """
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*"],
- )
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*"]``.'
+ ),
+ )
async def format(
self,
@@ -309,29 +280,22 @@ class AnthropicMultiAgentFormatter(_AnthropicFormatterBase):
a user and an agent are involved.
"""
- def __init__(
- self,
- conversation_history_prompt: str = (
+ conversation_history_prompt: str = Field(
+ default=(
"# Conversation History\n"
"The content between <history></history> tags contains "
"your conversation history\n"
),
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- """Initialize the Anthropic multi-agent formatter.
-
- Args:
- conversation_history_prompt (`str`):
- The prompt to use for the conversation history section.
- supported_input_media_types (`list[str] | None`, optional):
- The list of supported input media types. Defaults to
- ``["image/*"]``.
- """
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*"],
- )
- self.conversation_history_prompt = conversation_history_prompt
+ description="The prompt to use for the conversation history section.",
+ )
+
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*"]``.'
+ ),
+ )
async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
"""Format input messages into the structure required by the Anthropic
diff --git a/src/agentscope/formatter/_dashscope_formatter.py b/src/agentscope/formatter/_dashscope_formatter.py
index 56913d23e..56c9fded0 100644
--- a/src/agentscope/formatter/_dashscope_formatter.py
+++ b/src/agentscope/formatter/_dashscope_formatter.py
@@ -1,15 +1,19 @@
# -*- coding: utf-8 -*-
"""The dashscope formatter module."""
+import base64
from typing import Any
from fnmatch import fnmatch
from abc import ABC
-from . import FormatterBase
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
from .._logging import logger
from ..message import (
Msg,
TextBlock,
+ ThinkingBlock,
ToolResultBlock,
URLSource,
DataBlock,
@@ -24,7 +28,38 @@ class _DashScopeFormatterBase(FormatterBase, ABC):
"""Base class for DashScope formatters, providing shared data block
formatting logic."""
- supported_input_media_types: list[str]
+ input_types: list[str] = Field(
+ default_factory=lambda: [
+ "text/plain",
+ "image/*",
+ "audio/*",
+ "video/*",
+ ],
+ description=(
+ "The supported input types, aligned with the model card's "
+ "``input_types`` field. Media types (non ``text/plain`` / "
+ "``application/x-thinking`` entries) are used to filter "
+ "``DataBlock``\\s; ``application/x-thinking`` enables passing "
+ "``reasoning_content`` back to the API."
+ ),
+ )
+
+ @property
+ def supported_input_media_types(self) -> list[str]:
+ """Derive supported media types from :attr:`input_types`, excluding
+ ``text/plain`` and ``application/x-thinking``."""
+ return [
+ t
+ for t in self.input_types
+ if t not in ("text/plain", "application/x-thinking")
+ ]
+
+ @property
+ def supports_thinking_input(self) -> bool:
+ """Return ``True`` if ``application/x-thinking`` is listed in
+ :attr:`input_types`, meaning the model accepts ``reasoning_content``
+ in the conversation history."""
+ return "application/x-thinking" in self.input_types
def _format_dashscope_data_block(
self,
@@ -56,7 +91,17 @@ class _DashScopeFormatterBase(FormatterBase, ABC):
main_type = block.source.media_type.split("/")[0]
if isinstance(block.source, URLSource):
- return {main_type: block.source.url}
+ url_str = str(block.source.url)
+ if url_str.startswith("file://"):
+ # Local file — read and encode as base64 data URI
+ local_path = url_str.removeprefix("file://")
+ with open(local_path, "rb") as f:
+ encoded = base64.b64encode(f.read()).decode("utf-8")
+ return {
+ main_type: f"data:{block.source.media_type};"
+ f"base64,{encoded}",
+ }
+ return {main_type: url_str}
if isinstance(block.source, Base64Source):
return {
@@ -90,22 +135,6 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):
list ``[]`` for messages without valid content blocks.
"""
- def __init__(
- self,
- supported_input_media_type: list[str] | None = None,
- ) -> None:
- """Initialize the DashScope chat formatter.
-
- Args:
- supported_input_media_type (`list[str] | None`, optional):
- The list of supported input media types. Defaults to
- ["image/*", "audio/*", "video/*"].
- """
- super().__init__(
- supported_input_media_types=supported_input_media_type
- or ["image/*", "audio/*", "video/*"],
- )
-
async def format(
self,
msgs: list[Msg],
@@ -128,6 +157,7 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):
msg = msgs[i]
content_blocks: list[dict] = []
tool_calls = []
+ thinking_parts: list[str] = []
for block in msg.get_content_blocks():
if isinstance(block, TextBlock):
@@ -169,6 +199,10 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):
},
)
+ elif isinstance(block, ThinkingBlock):
+ if self.supports_thinking_input:
+ thinking_parts.append(block.thinking)
+
elif isinstance(block, ToolResultBlock):
(
textual_output,
@@ -196,6 +230,12 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):
),
)
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, skipped.",
+ type(block),
+ )
+
msg_dashscope = {
"role": msg.role,
"content": content_blocks,
@@ -204,17 +244,25 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):
if tool_calls:
msg_dashscope["tool_calls"] = tool_calls
+ if thinking_parts:
+ msg_dashscope["reasoning_content"] = "\n".join(thinking_parts)
+
if msg_dashscope["content"] or msg_dashscope.get("tool_calls"):
formatted_msgs.append(msg_dashscope)
# Move to next message
i += 1
- # Merge adjacent text block into one block to avoid API issues
+ # Merge adjacent text blocks into one to avoid API issues.
+ # Tool-result messages have content as a plain string (not a list),
+ # so skip merging for those.
cleaned_msgs: list = []
- for msg in formatted_msgs:
+ for formatted_msg in formatted_msgs:
+ if not isinstance(formatted_msg.get("content"), list):
+ cleaned_msgs.append(formatted_msg)
+ continue
new_content = []
- for block in msg["content"]:
+ for block in formatted_msg["content"]:
if (
block.get("text")
and new_content
@@ -223,8 +271,8 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):
new_content[-1]["text"] += "\n" + block["text"]
else:
new_content.append(block)
- msg["content"] = new_content
- cleaned_msgs.append(msg)
+ formatted_msg["content"] = new_content
+ cleaned_msgs.append(formatted_msg)
return cleaned_msgs
@@ -248,29 +296,14 @@ class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):
"""
- def __init__(
- self,
- conversation_history_prompt: str = (
+ conversation_history_prompt: str = Field(
+ description="The conversation history prompt.",
+ default=(
"# Conversation History\n"
"The content between <history></history> tags contains "
"your conversation history\n"
),
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- """Initialize the DashScope multi-agent formatter.
-
- Args:
- conversation_history_prompt (`str`):
- The prompt to use for the conversation history section.
- supported_input_media_types (`list[str] | None`, optional):
- The list of supported input media types. Defaults to
- ["image/*", "audio/*", "video/*"].
- """
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*", "audio/*", "video/*"],
- )
- self.conversation_history_prompt = conversation_history_prompt
+ )
async def format(self, msgs: list[Msg]) -> list[dict]:
"""Format input messages into the structure required by the DashScope
@@ -333,7 +366,7 @@ class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):
A list of dictionaries formatted for the DashScope API.
"""
return await DashScopeChatFormatter(
- supported_input_media_type=self.supported_input_media_types,
+ input_types=self.input_types,
).format(msgs)
async def _format_agent_message(
@@ -370,7 +403,7 @@ class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):
for msg in msgs:
for block in msg.get_content_blocks():
if isinstance(block, TextBlock):
- accumulated_text.append(f"{msg.name}: {block['text']}")
+ accumulated_text.append(f"{msg.name}: {block.text}")
elif isinstance(block, DataBlock):
# Handle the accumulated text as a single block
diff --git a/src/agentscope/formatter/_deepseek_formatter.py b/src/agentscope/formatter/_deepseek_formatter.py
index 9328961ee..4302eef49 100644
--- a/src/agentscope/formatter/_deepseek_formatter.py
+++ b/src/agentscope/formatter/_deepseek_formatter.py
@@ -2,6 +2,8 @@
"""The DeepSeek formatter module."""
from typing import Any
+from pydantic import Field
+
from ._formatter_base import FormatterBase
from .._logging import logger
from ..message import (
@@ -20,13 +22,13 @@ class DeepSeekChatFormatter(FormatterBase):
entities in the conversation.
"""
- def __init__(
- self,
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- super().__init__(
- supported_input_media_types=supported_input_media_types or [],
- )
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain"],
+ description=(
+ 'The supported input types. Defaults to ``["text/plain"]`` '
+ "(DeepSeek does not support multimodal input)."
+ ),
+ )
async def format(
self,
@@ -95,12 +97,19 @@ class DeepSeekChatFormatter(FormatterBase):
msg_deepseek: dict[str, Any] = {
"role": msg.role,
- "content": content_msg or None,
+ "content": content_msg or (None if tool_calls else ""),
}
- if reasoning_content_blocks:
- msg_deepseek["reasoning_content"] = "\n".join(
- reasoning_content_blocks,
+ # DeepSeek requires `reasoning_content` to be present on ALL
+ # assistant messages in multi-turn conversations that use thinking
+ # mode. When switching from a non-thinking model, historical
+ # messages will have no ThinkingBlock, so we always include the
+ # field (as None) for assistant messages to keep the context valid.
+ if msg.role == "assistant":
+ msg_deepseek["reasoning_content"] = (
+ "\n".join(reasoning_content_blocks)
+ if reasoning_content_blocks
+ else ""
)
if tool_calls:
@@ -118,28 +127,22 @@ class DeepSeekMultiAgentFormatter(FormatterBase):
a user and an agent are involved.
"""
- def __init__(
- self,
- conversation_history_prompt: str = (
+ conversation_history_prompt: str = Field(
+ default=(
"# Conversation History\n"
"The content between <history></history> tags contains "
"your conversation history\n"
),
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- """Initialize the DeepSeek multi-agent formatter.
-
- Args:
- conversation_history_prompt (`str`):
- The prompt to use for the conversation history section.
- supported_input_media_types (`list[str] | None`, optional):
- The list of supported input media types. Defaults to ``[]``
- (DeepSeek does not support multimodal input).
- """
- super().__init__(
- supported_input_media_types=supported_input_media_types or [],
- )
- self.conversation_history_prompt = conversation_history_prompt
+ description="The prompt to use for the conversation history section.",
+ )
+
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain"],
+ description=(
+ 'The supported input types. Defaults to ``["text/plain"]`` '
+ "(DeepSeek does not support multimodal input)."
+ ),
+ )
async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
"""Format input messages into the structure required by the DeepSeek
@@ -179,7 +182,7 @@ class DeepSeekMultiAgentFormatter(FormatterBase):
"""Given a sequence of tool call/result messages, format them into
the required format for the DeepSeek API."""
return await DeepSeekChatFormatter(
- supported_input_media_types=self.supported_input_media_types,
+ input_types=self.input_types,
).format(msgs)
async def _format_agent_message(
diff --git a/src/agentscope/formatter/_formatter_base.py b/src/agentscope/formatter/_formatter_base.py
index 3ac02590e..102451c02 100644
--- a/src/agentscope/formatter/_formatter_base.py
+++ b/src/agentscope/formatter/_formatter_base.py
@@ -8,6 +8,7 @@ from fnmatch import fnmatch
from typing import Any, List, AsyncGenerator
import shortuuid
+from pydantic import BaseModel, Field
from ..message import (
Msg,
@@ -18,24 +19,31 @@ from ..message import (
)
-class FormatterBase:
+class FormatterBase(BaseModel):
"""The base class for formatters."""
- supported_input_media_types: list[str]
- """The supported media types for multimodal data in the input messages,
- supporting mime types like "image/*", "image/png", "audio/*", "video/*",
- etc."""
-
- def __init__(self, supported_input_media_types: list[str]) -> None:
- """Initialize the formatter base class.
-
- Args:
- supported_input_media_types (`list[str]`):
- The supported media types for multimodal data in the input
- messages, supporting mime types like "image/*", "image/png",
- "audio/*", "video/*", etc.
- """
- self.supported_input_media_types = supported_input_media_types
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain"],
+ description=(
+ "The supported input types, aligned with the model card's "
+ "``input_types`` field. Entries other than ``text/plain`` and "
+ "``application/x-thinking`` are treated as media-type patterns "
+ "(glob-style, e.g. ``image/*``, ``audio/mp3``) that control which "
+ "``DataBlock``\\s are forwarded to the API."
+ ),
+ )
+ """The supported input types for this formatter, aligned with the model
+ card's ``input_types`` field."""
+
+ @property
+ def supported_input_media_types(self) -> list[str]:
+ """Derive the accepted media-type patterns from :attr:`input_types` by
+ excluding ``text/plain`` and ``application/x-thinking``."""
+ return [
+ t
+ for t in self.input_types
+ if t not in ("text/plain", "application/x-thinking")
+ ]
@abstractmethod
async def format(self, *args: Any, **kwargs: Any) -> list[dict[str, Any]]:
@@ -118,7 +126,6 @@ class FormatterBase:
block,
],
)
- multimodal_data.append(block)
# For unsupported media types, if it's a URL, include it in
# the textual output; if it's base64 data, save it locally
diff --git a/src/agentscope/formatter/_gemini_formatter.py b/src/agentscope/formatter/_gemini_formatter.py
index d31b2f17c..16a34d70d 100644
--- a/src/agentscope/formatter/_gemini_formatter.py
+++ b/src/agentscope/formatter/_gemini_formatter.py
@@ -2,10 +2,12 @@
"""Google Gemini API formatter in agentscope."""
import base64
import fnmatch
+import json
from abc import ABC
from typing import Any
import requests
+from pydantic import Field
from ._formatter_base import FormatterBase
from .._logging import logger
@@ -27,8 +29,6 @@ class _GeminiFormatterBase(FormatterBase, ABC):
"""Base class for Gemini formatters, providing shared data block
formatting logic."""
- supported_input_media_types: list[str]
-
def _format_gemini_data_block(
self,
block: DataBlock,
@@ -82,7 +82,7 @@ class _GeminiFormatterBase(FormatterBase, ABC):
},
}
elif isinstance(source, URLSource):
- url = source.url
+ url = str(source.url)
if url.startswith("file://"):
# Local file - read and convert to base64
file_path = url.removeprefix("file://")
@@ -115,14 +115,18 @@ class GeminiChatFormatter(_GeminiFormatterBase):
entities in the conversation.
"""
- def __init__(
- self,
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*", "audio/*", "video/*"],
- )
+ input_types: list[str] = Field(
+ default_factory=lambda: [
+ "text/plain",
+ "image/*",
+ "audio/*",
+ "video/*",
+ ],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*", "audio/*", "video/*"]``.'
+ ),
+ )
async def format(
self,
@@ -151,7 +155,10 @@ class GeminiChatFormatter(_GeminiFormatterBase):
parts.append({"text": block.text})
elif isinstance(block, ThinkingBlock):
- parts.append({"text": block.thinking})
+ # Gemini API requires `thought: true` to mark a part as a
+ # thinking/reasoning block so the model can distinguish it
+ # from normal text and maintain reasoning continuity.
+ parts.append({"thought": True, "text": block.thinking})
elif isinstance(block, HintBlock):
pass # Gemini does not support hint blocks
@@ -165,11 +172,10 @@ class GeminiChatFormatter(_GeminiFormatterBase):
parts.append(
{
"function_call": {
- "id": None,
+ "id": block.id,
"name": block.name,
- "args": block.input,
+ "args": json.loads(block.input or "{}"),
},
- "thought_signature": block.id,
},
)
@@ -246,29 +252,27 @@ class GeminiMultiAgentFormatter(_GeminiFormatterBase):
"""
- def __init__(
- self,
- conversation_history_prompt: str = (
+ conversation_history_prompt: str = Field(
+ default=(
"# Conversation History\n"
"The content between <history></history> tags contains "
"your conversation history\n"
),
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- """Initialize the Gemini multi-agent formatter.
-
- Args:
- conversation_history_prompt (`str`):
- The prompt to be used for the conversation history section.
- supported_input_media_types (`list[str] | None`, optional):
- The list of supported input media types. Defaults to
- ``["image/*", "audio/*", "video/*"]``.
- """
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*", "audio/*", "video/*"],
- )
- self.conversation_history_prompt = conversation_history_prompt
+ description="The prompt to use for the conversation history section.",
+ )
+
+ input_types: list[str] = Field(
+ default_factory=lambda: [
+ "text/plain",
+ "image/*",
+ "audio/*",
+ "video/*",
+ ],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*", "audio/*", "video/*"]``.'
+ ),
+ )
async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
"""Format input messages into the structure required by the Gemini
@@ -308,7 +312,7 @@ class GeminiMultiAgentFormatter(_GeminiFormatterBase):
"""Given a sequence of tool call/result messages, format them into
the required format for the Gemini API."""
return await GeminiChatFormatter(
- supported_input_media_types=self.supported_input_media_types,
+ input_types=self.input_types,
).format(msgs)
async def _format_agent_message(
diff --git a/src/agentscope/formatter/_kimi_formatter.py b/src/agentscope/formatter/_kimi_formatter.py
new file mode 100644
index 000000000..fb6862cc2
--- /dev/null
+++ b/src/agentscope/formatter/_kimi_formatter.py
@@ -0,0 +1,307 @@
+# -*- coding: utf-8 -*-
+"""The Kimi (Moonshot AI) formatter for agentscope."""
+from typing import Any
+
+from pydantic import Field
+
+from ._openai_formatter import _OpenAIFormatterBase
+from .._logging import logger
+from ..message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ThinkingBlock,
+ HintBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ UserMsg,
+)
+
+
+class KimiChatFormatter(_OpenAIFormatterBase):
+ """The Kimi formatter for chatbot scenario.
+
+ Kimi's API is OpenAI-compatible, but thinking models (``kimi-k2.6``,
+ ``kimi-k2-thinking``) return a ``reasoning_content`` field alongside
+ ``content`` in assistant messages. This formatter preserves that field
+ when re-sending assistant messages back to the API so that Kimi's
+ *Preserved Thinking* feature works correctly in multi-turn conversations.
+ """
+
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+ ),
+ )
+
+ async def format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format messages into the Kimi / OpenAI-compatible API format.
+
+ Behaves identically to :class:`OpenAIChatFormatter` except that
+ :class:`ThinkingBlock` content is placed into the ``reasoning_content``
+ field of the assistant message dict (required for Preserved Thinking).
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of message objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The formatted messages as a list of dictionaries.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ messages: list[dict] = []
+ i = 0
+ while i < len(msgs):
+ msg = msgs[i]
+ content_blocks: list[dict] = []
+ reasoning_parts: list[str] = []
+ tool_calls: list[dict] = []
+
+ for block in msg.get_content_blocks():
+ if isinstance(block, ThinkingBlock):
+ # Preserve reasoning_content for Kimi's multi-turn
+ # Preserved Thinking feature (kimi-k2.6 / kimi-k2-thinking)
+ reasoning_parts.append(block.thinking)
+
+ elif isinstance(block, TextBlock):
+ content_blocks.append({"type": "text", "text": block.text})
+
+ elif isinstance(block, DataBlock):
+ formatted = self._format_openai_data_block(
+ block,
+ role=msg.role,
+ )
+ if formatted is not None:
+ content_blocks.append(formatted)
+
+ elif isinstance(block, HintBlock):
+ if content_blocks or tool_calls:
+ msg_kimi = {
+ "role": msg.role,
+ "name": msg.name,
+ "content": content_blocks or None,
+ }
+ if reasoning_parts:
+ msg_kimi["reasoning_content"] = "\n".join(
+ reasoning_parts,
+ )
+ if tool_calls:
+ msg_kimi["tool_calls"] = tool_calls
+ messages.append(msg_kimi)
+ content_blocks = []
+ reasoning_parts = []
+ tool_calls = []
+
+ elif isinstance(block, ToolCallBlock):
+ tool_calls.append(
+ {
+ "id": block.id,
+ "type": "function",
+ "function": {
+ "name": block.name,
+ "arguments": block.input,
+ },
+ },
+ )
+
+ elif isinstance(block, ToolResultBlock):
+ (
+ textual_output,
+ multimodal_data,
+ ) = self.convert_tool_result_to_string(block.output)
+
+ messages.append(
+ {
+ "role": "tool",
+ "tool_call_id": block.id,
+ "content": textual_output,
+ "name": block.name,
+ },
+ )
+
+ if multimodal_data:
+ msgs.insert(
+ i + 1,
+ UserMsg(
+ name="system-reminder",
+ content=multimodal_data,
+ ),
+ )
+
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, skipped.",
+ type(block),
+ )
+
+ msg_kimi = {
+ "role": msg.role,
+ "name": msg.name,
+ "content": content_blocks or None,
+ }
+
+ # Kimi's Preserved Thinking requires `reasoning_content` on ALL
+ # assistant messages in multi-turn conversations (None when no
+ # thinking took place), so that the model can continue its chain
+ # of thought correctly.
+ if msg.role == "assistant":
+ msg_kimi["reasoning_content"] = (
+ "\n".join(reasoning_parts) if reasoning_parts else ""
+ )
+
+ if tool_calls:
+ msg_kimi["tool_calls"] = tool_calls
+
+ if msg_kimi["content"] or msg_kimi.get("tool_calls"):
+ messages.append(msg_kimi)
+
+ i += 1
+
+ return messages
+
+
+class KimiMultiAgentFormatter(_OpenAIFormatterBase):
+ """Formatter for the Kimi (Moonshot AI) API in multi-agent conversations.
+
+ Kimi's API is OpenAI-compatible, so the multi-agent history collapsing
+ strategy is the same as :class:`OpenAIMultiAgentFormatter`. Tool
+ sequences are delegated to :class:`KimiChatFormatter` so that
+ ``reasoning_content`` is preserved correctly for multi-turn
+ *Preserved Thinking* conversations.
+
+ .. note:: Telling the assistant's name in the system prompt is important
+ in multi-agent conversations so that the model knows which role it
+ is playing.
+ """
+
+ conversation_history_prompt: str = Field(
+ default=(
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ description="The prompt to use for the conversation history section.",
+ )
+
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+ ),
+ )
+
+ async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
+ """Format input messages into the Kimi API format for multi-agent
+ conversations.
+
+ Non-tool messages from all agents are collapsed into a single user
+ message with ``<history></history>`` tags. Tool call / result
+ sequences are delegated to :class:`KimiChatFormatter`.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of message objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The formatted messages as a list of dictionaries.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ formatted_msgs: list[dict] = []
+ start_index = 0
+ if msgs and msgs[0].role == "system":
+ formatted_msgs.append(
+ await self._format_system_message(msgs[0]),
+ )
+ start_index = 1
+
+ is_first_agent_message = True
+ async for typ, group in self._group_messages(msgs[start_index:]):
+ if typ == "tool_sequence":
+ formatted_msgs.extend(
+ await KimiChatFormatter(
+ input_types=self.input_types,
+ ).format(group),
+ )
+ elif typ == "agent_message":
+ formatted_msgs.extend(
+ await self._format_agent_message(
+ group,
+ is_first_agent_message,
+ ),
+ )
+ is_first_agent_message = False
+
+ return formatted_msgs
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format a sequence of tool-related messages using
+ KimiChatFormatter."""
+ return await KimiChatFormatter(
+ input_types=self.input_types,
+ ).format(msgs)
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Collapse agent messages into a ``<history>`` user message."""
+ if is_first:
+ conversation_history_prompt = self.conversation_history_prompt
+ else:
+ conversation_history_prompt = ""
+
+ accumulated_text: list[str] = []
+ media_blocks: list[dict] = []
+
+ for msg in msgs:
+ for block in msg.get_content_blocks():
+ if isinstance(block, TextBlock):
+ accumulated_text.append(f"{msg.name}: {block.text}")
+ elif isinstance(block, DataBlock):
+ formatted = self._format_openai_data_block(
+ block,
+ role=msg.role,
+ )
+ if formatted is not None:
+ media_blocks.append(formatted)
+
+ if not accumulated_text and not media_blocks:
+ return []
+
+ history_text = "\n".join(accumulated_text)
+ if history_text:
+ history_text = (
+ conversation_history_prompt
+ + "<history>\n"
+ + history_text
+ + "\n</history>"
+ )
+
+ content_list: list[dict[str, Any]] = []
+ if history_text:
+ content_list.append({"type": "text", "text": history_text})
+ content_list.extend(media_blocks)
+
+ return [{"role": "user", "content": content_list}]
+
+ @staticmethod
+ async def _format_system_message(msg: Msg) -> dict[str, Any]:
+ """Format a system message for the Kimi API."""
+ return {
+ "role": "system",
+ "content": msg.get_text_content(),
+ }
diff --git a/src/agentscope/formatter/_ollama_formatter.py b/src/agentscope/formatter/_ollama_formatter.py
index 43f51196d..c20196a3c 100644
--- a/src/agentscope/formatter/_ollama_formatter.py
+++ b/src/agentscope/formatter/_ollama_formatter.py
@@ -2,10 +2,12 @@
"""The Ollama formatter module."""
import base64
import fnmatch
+import json
from abc import ABC
from typing import Any
import requests
+from pydantic import Field
from ._formatter_base import FormatterBase
from .._logging import logger
@@ -16,6 +18,7 @@ from ..message import (
DataBlock,
ToolCallBlock,
ToolResultBlock,
+ ThinkingBlock,
URLSource,
Base64Source,
)
@@ -25,8 +28,6 @@ class _OllamaFormatterBase(FormatterBase, ABC):
"""Base class for Ollama formatters, providing shared data block
formatting logic."""
- supported_input_media_types: list[str]
-
def _format_ollama_data_block(
self,
block: DataBlock,
@@ -81,7 +82,7 @@ class _OllamaFormatterBase(FormatterBase, ABC):
if isinstance(source, Base64Source):
return source.data
elif isinstance(source, URLSource):
- url = source.url
+ url = str(source.url)
if url.startswith("file://"):
# Local file - read and convert to base64
file_path = url.removeprefix("file://")
@@ -104,14 +105,13 @@ class OllamaChatFormatter(_OllamaFormatterBase):
participants in the conversation.
"""
- def __init__(
- self,
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*"],
- )
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*"]``.'
+ ),
+ )
async def format(
self,
@@ -146,6 +146,11 @@ class OllamaChatFormatter(_OllamaFormatterBase):
if formatted_image:
images.append(formatted_image)
+ elif isinstance(block, ThinkingBlock):
+ # Ollama does not use reasoning content in the context
+ # — skip thinking blocks silently.
+ pass
+
elif isinstance(block, ToolCallBlock):
messages.append(
{
@@ -157,7 +162,11 @@ class OllamaChatFormatter(_OllamaFormatterBase):
{
"function": {
"name": block.name,
- "arguments": block.input,
+ # Ollama SDK expects a dict, not a
+ # JSON string.
+ "arguments": json.loads(
+ block.input or "{}",
+ ),
},
},
],
@@ -172,7 +181,16 @@ class OllamaChatFormatter(_OllamaFormatterBase):
multimodal_data,
) = self.convert_tool_result_to_string(block.output)
- # If there's multimodal data, insert a user message
+ # Ollama expects tool results as a separate "tool" role
+ # message, regardless of the containing Msg's role.
+ messages.append(
+ {
+ "role": "tool",
+ "content": textual_output,
+ },
+ )
+
+ # If there's multimodal data, append an extra user message.
if multimodal_data:
user_images = []
user_content_parts = []
@@ -197,9 +215,6 @@ class OllamaChatFormatter(_OllamaFormatterBase):
if user_images:
user_msg["images"] = user_images
messages.append(user_msg)
- else:
- # No multimodal data, just add text to content
- content_parts.append(textual_output)
else:
logger.warning(
@@ -228,29 +243,22 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):
a user and an agent are involved.
"""
- def __init__(
- self,
- conversation_history_prompt: str = (
+ conversation_history_prompt: str = Field(
+ default=(
"# Conversation History\n"
"The content between <history></history> tags contains "
"your conversation history\n"
),
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- """Initialize the Ollama multi-agent formatter.
-
- Args:
- conversation_history_prompt (`str`):
- The prompt to use for the conversation history section.
- supported_input_media_types (`list[str] | None`, optional):
- The list of supported input media types. Defaults to
- ``["image/*"]``.
- """
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*"],
- )
- self.conversation_history_prompt = conversation_history_prompt
+ description="The prompt to use for the conversation history section.",
+ )
+
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*"]``.'
+ ),
+ )
async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
"""Format input messages into the structure required by the Ollama
@@ -289,7 +297,7 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):
) -> list[dict[str, Any]]:
"""Format a sequence of tool-related messages."""
return await OllamaChatFormatter(
- supported_input_media_types=self.supported_input_media_types,
+ input_types=self.input_types,
).format(msgs)
async def _format_agent_message(
@@ -314,8 +322,8 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):
formatted_image = self._format_ollama_data_block(block)
if formatted_image:
images.append(formatted_image)
- elif isinstance(block, HintBlock):
- pass # Ollama does not support hint blocks
+ elif isinstance(block, (HintBlock, ThinkingBlock)):
+ pass # Ollama does not use hint/thinking blocks
else:
logger.warning(
"Unsupported block type %s in agent message, skipped.",
diff --git a/src/agentscope/formatter/_openai_formatter.py b/src/agentscope/formatter/_openai_formatter.py
index 490023cab..1cdcb17ef 100644
--- a/src/agentscope/formatter/_openai_formatter.py
+++ b/src/agentscope/formatter/_openai_formatter.py
@@ -7,8 +7,9 @@ from typing import Any
from urllib.parse import urlparse
import requests
+from pydantic import Field
-from . import FormatterBase
+from ._formatter_base import FormatterBase
from .._logging import logger
from ..message import (
Msg,
@@ -19,6 +20,7 @@ from ..message import (
ToolCallBlock,
ToolResultBlock,
HintBlock,
+ ThinkingBlock,
UserMsg,
)
@@ -27,8 +29,6 @@ class _OpenAIFormatterBase(FormatterBase, ABC):
"""Base class for OpenAI formatters, providing shared data block
formatting logic."""
- supported_input_media_types: list[str]
-
def _format_openai_data_block(
self,
block: DataBlock,
@@ -105,15 +105,16 @@ class _OpenAIFormatterBase(FormatterBase, ABC):
url = f"data:{source.media_type};base64,{source.data}"
elif isinstance(source, URLSource):
- if source.url.startswith("file://"):
+ url_str = str(source.url)
+ if url_str.startswith("file://"):
# Local file — read and encode as base64 data URI
- local_path = source.url.removeprefix("file://")
+ local_path = url_str.removeprefix("file://")
with open(local_path, "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
url = f"data:{source.media_type};base64,{encoded}"
else:
# Remote URL — pass through as-is
- url = source.url
+ url = url_str
else:
raise ValueError(f"Unsupported image source type: {type(source)}")
@@ -156,9 +157,10 @@ class _OpenAIFormatterBase(FormatterBase, ABC):
}
if isinstance(source, URLSource):
- if source.url.startswith("file://"):
+ url_str = str(source.url)
+ if url_str.startswith("file://"):
# Local file
- local_path = source.url.removeprefix("file://")
+ local_path = url_str.removeprefix("file://")
extension = local_path.rsplit(".", 1)[-1].lower()
if extension not in ["wav", "mp3"]:
raise TypeError(
@@ -169,14 +171,14 @@ class _OpenAIFormatterBase(FormatterBase, ABC):
data = base64.b64encode(f.read()).decode("utf-8")
else:
# Remote URL — download and encode
- parsed = urlparse(source.url)
+ parsed = urlparse(url_str)
extension = parsed.path.rsplit(".", 1)[-1].lower()
if extension not in ["wav", "mp3"]:
raise TypeError(
f"Unsupported audio file extension: {extension}, "
"wav and mp3 are supported.",
)
- response = requests.get(source.url)
+ response = requests.get(url_str)
response.raise_for_status()
data = base64.b64encode(response.content).decode("utf-8")
@@ -197,22 +199,13 @@ class OpenAIChatFormatter(_OpenAIFormatterBase):
identify different entities in the conversation.
"""
- def __init__(
- self,
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- """Initialize the OpenAI chat formatter.
-
- Args:
- supported_input_media_types (`list[str] | None`, optional):
- The list of supported input media types, using glob-style
- patterns (e.g. ``"image/*"``, ``"audio/mp3"``). Defaults to
- ``["image/*", "audio/*"]``.
- """
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*", "audio/*"],
- )
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+ ),
+ )
async def format(
self,
@@ -302,6 +295,11 @@ class OpenAIChatFormatter(_OpenAIFormatterBase):
),
)
+ elif isinstance(block, ThinkingBlock):
+ # OpenAI API does not accept reasoning/thinking content
+ # in conversation history — skip thinking blocks silently.
+ pass
+
else:
logger.warning(
"Unsupported block type %s in the message, skipped.",
@@ -336,30 +334,22 @@ class OpenAIMultiAgentFormatter(_OpenAIFormatterBase):
OpenAI-compatible services like vLLM, Azure OpenAI, and others.
"""
- def __init__(
- self,
- conversation_history_prompt: str = (
+ conversation_history_prompt: str = Field(
+ default=(
"# Conversation History\n"
"The content between <history></history> tags contains "
"your conversation history\n"
),
- supported_input_media_types: list[str] | None = None,
- ) -> None:
- """Initialize the OpenAI multi-agent formatter.
-
- Args:
- conversation_history_prompt (`str`):
- The prompt to use for the conversation history section.
- supported_input_media_types (`list[str] | None`, optional):
- The list of supported input media types, using glob-style
- patterns (e.g. ``"image/*"``, ``"audio/mp3"``). Defaults to
- ``["image/*", "audio/*"]``.
- """
- super().__init__(
- supported_input_media_types=supported_input_media_types
- or ["image/*", "audio/*"],
- )
- self.conversation_history_prompt = conversation_history_prompt
+ description="The prompt to use for the conversation history section.",
+ )
+
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+ ),
+ )
async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
"""Format input messages into the structure required by the OpenAI API
@@ -399,7 +389,7 @@ class OpenAIMultiAgentFormatter(_OpenAIFormatterBase):
"""Given a sequence of tool call/result messages, format them into
the required format for the OpenAI API."""
return await OpenAIChatFormatter(
- supported_input_media_types=self.supported_input_media_types,
+ input_types=self.input_types,
).format(msgs)
async def _format_agent_message(
diff --git a/src/agentscope/formatter/_openai_response_formatter.py b/src/agentscope/formatter/_openai_response_formatter.py
new file mode 100644
index 000000000..71a19c405
--- /dev/null
+++ b/src/agentscope/formatter/_openai_response_formatter.py
@@ -0,0 +1,391 @@
+# -*- coding: utf-8 -*-
+"""Formatters for the OpenAI Responses API."""
+from abc import ABC
+from typing import Any
+
+from pydantic import Field
+
+from ._openai_formatter import _OpenAIFormatterBase
+from .._logging import logger
+from ..message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ HintBlock,
+ ThinkingBlock,
+ UserMsg,
+)
+
+
+class _OpenAIResponseFormatterBase(_OpenAIFormatterBase, ABC):
+ """Base class for OpenAI Responses API formatters.
+
+ Provides the shared ``_format_response_data_block`` helper used by both
+ :class:`OpenAIResponseFormatter` (chat) and
+ :class:`OpenAIResponseMultiAgentFormatter` (multi-agent).
+ """
+
+ input_types: list[str] = Field(
+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+ ),
+ )
+
+ def _format_response_data_block(
+ self,
+ block: DataBlock,
+ role: str = "user",
+ ) -> dict[str, Any] | None:
+ """Format a DataBlock into the Response API format.
+
+ Args:
+ block (`DataBlock`):
+ The DataBlock to format.
+ role (`str`, defaults to ``"user"``):
+ The role of the message that contains this block.
+
+ Returns:
+ `dict[str, Any] | None`:
+ A dictionary in the Responses API format, or ``None`` when the
+ block type is unsupported.
+ """
+ base_result = self._format_openai_data_block(block, role)
+ if base_result is None:
+ return None
+
+ if base_result.get("type") == "image_url":
+ return {
+ "type": "input_image",
+ "image_url": base_result["image_url"]["url"],
+ }
+
+ return base_result
+
+
+class OpenAIResponseFormatter(_OpenAIResponseFormatterBase):
+ """Formatter for the OpenAI Responses API in chat (single-agent) mode.
+
+ Produces input items compatible with ``client.responses.create(
+ input=...)``.
+ Compared with the Chat Completions format, the key differences are:
+
+ * Text content blocks use ``input_text`` instead of ``text``.
+ * Image content blocks use ``input_image`` instead of ``image_url``.
+ * Assistant tool-call messages become top-level ``function_call`` items.
+ * Tool result messages become ``function_call_output`` items.
+ * Reasoning items (``ThinkingBlock`` with ``reasoning_item_id``) are
+ echoed back verbatim as required by reasoning models (e.g. ``o1``).
+ """
+
+ async def format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format message objects into OpenAI Response API input items.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of Msg objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of input items for ``client.responses.create``.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ items: list[dict] = []
+ i = 0
+ while i < len(msgs):
+ msg = msgs[i]
+ content_parts: list[dict] = []
+ function_calls: list[dict] = []
+
+ for block in msg.get_content_blocks():
+ if isinstance(block, TextBlock):
+ content_parts.append(
+ {"type": "input_text", "text": block.text},
+ )
+
+ elif isinstance(block, DataBlock):
+ formatted = self._format_response_data_block(
+ block,
+ role=msg.role,
+ )
+ if formatted is not None:
+ content_parts.append(formatted)
+
+ elif isinstance(block, HintBlock):
+ if content_parts:
+ items.append(
+ {
+ "role": msg.role,
+ "content": content_parts,
+ },
+ )
+ content_parts = []
+
+ elif isinstance(block, ThinkingBlock):
+ # When reasoning_item_id is present the block originated
+ # from a Responses API "reasoning" output item. The API
+ # requires that such items are echoed back verbatim in
+ # multi-turn history (especially when they precede a
+ # function_call). Without the ID we skip silently.
+ reasoning_item_id = getattr(
+ block,
+ "reasoning_item_id",
+ None,
+ )
+ if reasoning_item_id:
+ if content_parts:
+ items.append(
+ {
+ "role": msg.role,
+ "content": content_parts,
+ },
+ )
+ content_parts = []
+ # summary may be empty when the model did not produce
+ # reasoning summary text (e.g. o4-mini with streaming)
+ summary = (
+ [{"type": "summary_text", "text": block.thinking}]
+ if block.thinking
+ else []
+ )
+ items.append(
+ {
+ "type": "reasoning",
+ "id": reasoning_item_id,
+ "summary": summary,
+ "content": [],
+ },
+ )
+
+ elif isinstance(block, ToolCallBlock):
+ # The Responses API distinguishes two identifiers on a
+ # function_call item:
+ # id → fc_xxx: the item identifier used when
+ # echoing the item in multi-turn history
+ # call_id → call_xxx: the identifier that must be
+ # echoed in the matching function_call_output
+ # For other APIs (Chat Completions, DashScope …) only one
+ # ID exists; call_id extra field is None and we fall back
+ # to id for both fields.
+ function_calls.append(
+ {
+ "type": "function_call",
+ "id": block.id,
+ "call_id": getattr(block, "call_id", None)
+ or block.id,
+ "name": block.name,
+ "arguments": block.input,
+ },
+ )
+
+ elif isinstance(block, ToolResultBlock):
+ (
+ textual_output,
+ multimodal_data,
+ ) = self.convert_tool_result_to_string(block.output)
+
+ items.append(
+ {
+ "type": "function_call_output",
+ "call_id": block.id,
+ "output": textual_output,
+ },
+ )
+
+ if multimodal_data:
+ msgs.insert(
+ i + 1,
+ UserMsg(
+ name="system-reminder",
+ content=multimodal_data,
+ ),
+ )
+
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, skipped.",
+ type(block),
+ )
+
+ if function_calls:
+ if content_parts:
+ items.append(
+ {
+ "role": msg.role,
+ "content": content_parts,
+ },
+ )
+ items.extend(function_calls)
+ elif content_parts:
+ items.append(
+ {
+ "role": msg.role,
+ "content": content_parts,
+ },
+ )
+
+ i += 1
+
+ return items
+
+
+class OpenAIResponseMultiAgentFormatter(_OpenAIResponseFormatterBase):
+ """Formatter for the OpenAI Responses API in multi-agent mode.
+
+ Handles conversations where more than a user and a single agent are
+ involved. Tool call/result sequences are formatted with the Responses API
+ ``function_call`` / ``function_call_output`` items (delegated to
+ :class:`OpenAIResponseFormatter`). Agent conversation history messages
+ are wrapped inside ``<history></history>`` tags and presented as a single
+ ``user`` input item.
+ """
+
+ conversation_history_prompt: str = Field(
+ default=(
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ description="The prompt to use for the conversation history section.",
+ )
+
+ async def format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format messages for multi-agent Responses API conversations.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of Msg objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of input items for ``client.responses.create``.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ formatted_msgs: list[dict] = []
+ start_index = 0
+ if len(msgs) > 0 and msgs[0].role == "system":
+ formatted_msgs.append(
+ await self._format_system_message(msgs[0]),
+ )
+ start_index = 1
+
+ is_first_agent_message = True
+ async for typ, group in self._group_messages(msgs[start_index:]):
+ if typ == "tool_sequence":
+ formatted_msgs.extend(
+ await self._format_tool_sequence(group),
+ )
+ elif typ == "agent_message":
+ formatted_msgs.extend(
+ await self._format_agent_message(
+ group,
+ is_first_agent_message,
+ ),
+ )
+ is_first_agent_message = False
+
+ return formatted_msgs
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format a sequence of tool call/result messages using the Responses
+ API format.
+
+ Args:
+ msgs (`list[Msg]`):
+ The tool call/result messages to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of Responses API input items.
+ """
+ return await OpenAIResponseFormatter(
+ input_types=self.input_types,
+ ).format(msgs)
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Format a sequence of agent messages as a history-wrapped user item.
+
+ Args:
+ msgs (`list[Msg]`):
+ The agent messages to format.
+ is_first (`bool`, defaults to ``True``):
+ Whether this is the first agent message group, which triggers
+ the conversation history prompt.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list containing at most one user input item.
+ """
+ conversation_history_prompt = (
+ self.conversation_history_prompt if is_first else ""
+ )
+
+ accumulated_text: list[str] = []
+ media_blocks: list[dict] = []
+
+ for msg in msgs:
+ for block in msg.get_content_blocks():
+ if isinstance(block, TextBlock):
+ accumulated_text.append(f"{msg.name}: {block.text}")
+ elif isinstance(block, DataBlock):
+ formatted = self._format_response_data_block(
+ block,
+ role=msg.role,
+ )
+ if formatted is not None:
+ media_blocks.append(formatted)
+
+ if not accumulated_text and not media_blocks:
+ return []
+
+ history_text = "\n".join(accumulated_text)
+ wrapped = (
+ conversation_history_prompt
+ + "<history>\n"
+ + history_text
+ + "\n</history>"
+ )
+
+ content_list: list[dict[str, Any]] = [
+ {"type": "input_text", "text": wrapped},
+ ]
+ content_list.extend(media_blocks)
+
+ return [{"role": "user", "content": content_list}]
+
+ @staticmethod
+ async def _format_system_message(
+ msg: Msg,
+ ) -> dict[str, Any]:
+ """Format a system message for the Responses API.
+
+ Args:
+ msg (`Msg`):
+ The system message to format.
+
+ Returns:
+ `dict[str, Any]`:
+ A dictionary with ``role`` and ``content`` keys.
+ """
+ return {
+ "role": "system",
+ "content": msg.get_text_content(),
+ }
diff --git a/src/agentscope/formatter/_xai_formatter.py b/src/agentscope/formatter/_xai_formatter.py
new file mode 100644
index 000000000..bfb665951
--- /dev/null
+++ b/src/agentscope/formatter/_xai_formatter.py
@@ -0,0 +1,335 @@
+# -*- coding: utf-8 -*-
+"""The xAI formatter module.
+
+This formatter converts AgentScope ``Msg`` objects into the protobuf
+``Message`` objects expected by the ``xai_sdk`` gRPC client. Unlike every
+other formatter, the ``format()`` method returns a list of
+``chat_pb2.Message`` proto objects rather than plain dicts, because the
+``xai_sdk`` chat API accepts proto messages directly.
+"""
+import base64
+from typing import Any, List
+
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
+from .._logging import logger
+from ..message import (
+ Msg,
+ TextBlock,
+ ThinkingBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ DataBlock,
+ URLSource,
+ Base64Source,
+ HintBlock,
+)
+
+
+class XAIChatFormatter(FormatterBase):
+ """Formatter for the xAI chat model.
+
+ Converts ``Msg`` objects into ``xai_sdk`` protobuf ``Message`` objects
+ that can be appended directly to a ``xai_sdk`` chat session.
+
+ Unlike other formatters whose ``format()`` returns ``list[dict]``, this
+ formatter returns ``list[chat_pb2.Message]``. The type annotation is
+ intentionally widened to ``list[Any]`` to accommodate this difference.
+ """
+
+ input_types: list[str] = Field(
+ default=["text/plain", "image/jpeg", "image/png"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/jpeg", "image/png"]``.'
+ ),
+ )
+
+ async def format(
+ self,
+ msgs: list[Msg],
+ **kwargs: Any,
+ ) -> List[Any]:
+ """Convert a list of ``Msg`` objects to ``xai_sdk`` proto messages.
+
+ Args:
+ msgs (`list[Msg]`):
+ A list of ``Msg`` objects representing the conversation.
+ **kwargs (`Any`):
+ Unused; retained for interface compatibility.
+
+ Returns:
+ `list[Any]`:
+ A list of ``chat_pb2.Message`` proto objects, ready to be
+ appended to a ``xai_sdk`` chat session via
+ ``chat.append()``.
+ """
+ from xai_sdk.chat import (
+ assistant,
+ image,
+ system,
+ tool_result,
+ user,
+ chat_pb2,
+ )
+
+ self.assert_list_of_msgs(msgs)
+
+ xai_messages: List[Any] = []
+
+ for msg in msgs:
+ blocks = msg.get_content_blocks()
+
+ text_blocks = [b for b in blocks if isinstance(b, TextBlock)]
+ tool_call_blocks = [
+ b for b in blocks if isinstance(b, ToolCallBlock)
+ ]
+ tool_result_blocks = [
+ b for b in blocks if isinstance(b, ToolResultBlock)
+ ]
+
+ if msg.role == "system":
+ text = "\n".join(b.text for b in text_blocks)
+ xai_messages.append(system(text))
+
+ elif msg.role == "user":
+ content_args: list = []
+ for block in blocks:
+ if isinstance(block, (HintBlock, ThinkingBlock)):
+ pass
+ elif isinstance(block, TextBlock):
+ content_args.append(block.text)
+ elif isinstance(block, DataBlock):
+ if block.source.media_type.startswith("image/"):
+ if isinstance(block.source, URLSource):
+ url_str = str(block.source.url)
+ if url_str.startswith("file://"):
+ # Local file — read and encode as data URI
+ local_path = url_str.removeprefix(
+ "file://",
+ )
+ with open(local_path, "rb") as f:
+ encoded = base64.b64encode(
+ f.read(),
+ ).decode("utf-8")
+ content_args.append(
+ image(
+ f"data:{block.source.media_type};"
+ f"base64,{encoded}",
+ ),
+ )
+ else:
+ content_args.append(image(url_str))
+ elif isinstance(block.source, Base64Source):
+ content_args.append(
+ image(
+ f"data:{block.source.media_type};"
+ f"base64,{block.source.data}",
+ ),
+ )
+ else:
+ logger.warning(
+ "Unsupported media type %s for xAI API. "
+ "Only image/jpeg and image/png are supported. "
+ "This block will be skipped.",
+ block.source.media_type,
+ )
+ else:
+ logger.warning(
+ "Unsupported block type %s in user message, "
+ "skipped.",
+ type(block).__name__,
+ )
+
+ if content_args:
+ xai_messages.append(user(*content_args))
+
+ elif msg.role == "assistant":
+ if tool_result_blocks:
+ # Convert each ToolResultBlock to a tool_result message.
+ for tr_block in tool_result_blocks:
+ output_text = self._extract_result_text(
+ tr_block.output,
+ )
+ xai_messages.append(
+ tool_result(
+ output_text,
+ tool_call_id=tr_block.id,
+ ),
+ )
+
+ elif tool_call_blocks:
+ # Assistant turn that triggered tool calls (history).
+ msg_proto = chat_pb2.Message()
+ msg_proto.role = chat_pb2.MessageRole.Value(
+ "ROLE_ASSISTANT",
+ )
+ if text_blocks:
+ c = msg_proto.content.add()
+ c.text = "\n".join(b.text for b in text_blocks)
+ for tc in tool_call_blocks:
+ proto_tc = msg_proto.tool_calls.add()
+ proto_tc.id = tc.id
+ proto_tc.type = chat_pb2.ToolCallType.Value(
+ "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL",
+ )
+ proto_tc.function.name = tc.name
+ proto_tc.function.arguments = tc.input
+ xai_messages.append(msg_proto)
+
+ else:
+ # Regular assistant text message.
+ text = "\n".join(b.text for b in text_blocks)
+ if text:
+ xai_messages.append(assistant(text))
+
+ else:
+ logger.warning(
+ "Unsupported message role '%s', skipped.",
+ msg.role,
+ )
+
+ return xai_messages
+
+ def _extract_result_text(self, output: Any) -> str:
+ """Extract a plain-text string from a ``ToolResultBlock`` output.
+
+ Args:
+ output (`Any`):
+ The raw output of a ``ToolResultBlock``, which may be a
+ string, a list of blocks, or another type.
+
+ Returns:
+ `str`:
+ A plain-text representation of the output.
+ """
+ if output is None:
+ return ""
+ if isinstance(output, str):
+ return output
+ if isinstance(output, list):
+ parts = []
+ for item in output:
+ if isinstance(item, TextBlock):
+ parts.append(item.text)
+ elif isinstance(item, str):
+ parts.append(item)
+ else:
+ parts.append(str(item))
+ return "\n".join(parts)
+ return str(output)
+
+
+class XAIMultiAgentFormatter(FormatterBase):
+ """Formatter for the xAI chat model in multi-agent conversations.
+
+ 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; tool
+ call / result sequences are delegated to :class:`XAIChatFormatter`.
+
+ .. note:: ``format()`` returns ``list[Any]`` (protobuf messages), not
+ ``list[dict]``.
+ """
+
+ conversation_history_prompt: str = Field(
+ default=(
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ description="The prompt to use for the conversation history section.",
+ )
+
+ input_types: list[str] = Field(
+ default=["text/plain", "image/jpeg", "image/png"],
+ description=(
+ "The supported input types. "
+ 'Defaults to ``["text/plain", "image/jpeg", "image/png"]``.'
+ ),
+ )
+
+ async def format(
+ self,
+ msgs: list[Msg],
+ **kwargs: Any,
+ ) -> List[Any]:
+ """Convert a list of ``Msg`` objects to ``xai_sdk`` proto messages.
+
+ Conversation history (non-tool messages) is collapsed into a single
+ ``user`` protobuf message containing ``<history></history>`` tags.
+ Tool sequences are formatted by :class:`XAIChatFormatter`.
+
+ Args:
+ msgs (`list[Msg]`):
+ A list of ``Msg`` objects representing the conversation.
+ **kwargs (`Any`):
+ Unused; retained for interface compatibility.
+
+ Returns:
+ `list[Any]`:
+ A list of ``chat_pb2.Message`` proto objects.
+ """
+ from xai_sdk.chat import system, user
+
+ self.assert_list_of_msgs(msgs)
+
+ xai_messages: List[Any] = []
+ start_index = 0
+
+ if msgs and msgs[0].role == "system":
+ text = msgs[0].get_text_content()
+ xai_messages.append(system(text))
+ start_index = 1
+
+ is_first_agent_message = True
+ async for typ, group in self._group_messages(msgs[start_index:]):
+ if typ == "tool_sequence":
+ xai_messages.extend(
+ await XAIChatFormatter(
+ input_types=self.input_types,
+ ).format(group),
+ )
+ elif typ == "agent_message":
+ history_text = self._build_history_text(
+ group,
+ is_first=is_first_agent_message,
+ )
+ if history_text:
+ xai_messages.append(user(history_text))
+ is_first_agent_message = False
+
+ return xai_messages
+
+ def _build_history_text(self, msgs: list[Msg], *, is_first: bool) -> str:
+ """Build a ``<history>…</history>`` text block from agent messages.
+
+ Args:
+ msgs (`list[Msg]`):
+ Non-tool messages to collapse into history.
+ is_first (`bool`):
+ When ``True``, prepend
+ :attr:`conversation_history_prompt` before the tag.
+
+ Returns:
+ `str`:
+ The formatted history string, or an empty string when there
+ is no text content.
+ """
+ lines: list[str] = []
+ for msg in msgs:
+ parts: list[str] = []
+ if msg.name:
+ parts.append(f"{msg.name}:")
+ for block in msg.get_content_blocks():
+ if isinstance(block, TextBlock):
+ parts.append(block.text)
+ if parts:
+ lines.append(" ".join(parts))
+
+ if not lines:
+ return ""
+
+ prefix = self.conversation_history_prompt if is_first else ""
+ return prefix + "<history>\n" + "\n".join(lines) + "\n</history>"
diff --git a/src/agentscope/message/_block.py b/src/agentscope/message/_block.py
index 56fbd7d0b..2b557f0b9 100644
--- a/src/agentscope/message/_block.py
+++ b/src/agentscope/message/_block.py
@@ -18,7 +18,14 @@ class TextBlock(BaseModel):
class ThinkingBlock(BaseModel):
- """The thinking block."""
+ """The thinking block.
+
+ Allows extra provider-specific fields (e.g. Anthropic's ``signature``)
+ via ``extra="allow"`` so that model implementations can pass
+ arbitrary metadata without subclassing.
+ """
+
+ model_config = ConfigDict(extra="allow")
type: Literal["thinking"] = "thinking"
"""The type of the thinking block, which is always 'thinking'."""
@@ -94,9 +101,13 @@ class ToolCallState(StrEnum):
class ToolCallBlock(BaseModel):
- """The tool call block."""
+ """The tool call block.
- model_config = ConfigDict(use_enum_values=True)
+ Allows extra provider-specific fields (e.g. the OpenAI Responses API's
+ ``call_id``) via ``extra="allow"`` without requiring subclassing.
+ """
+
+ model_config = ConfigDict(use_enum_values=True, extra="allow")
type: Literal["tool_call"] = "tool_call"
"""The type of the tool call block, which is always 'tool_call'."""
diff --git a/src/agentscope/model/__init__.py b/src/agentscope/model/__init__.py
index f164a88ae..3394c037c 100644
--- a/src/agentscope/model/__init__.py
+++ b/src/agentscope/model/__init__.py
@@ -1,74 +1,33 @@
# -*- coding: utf-8 -*-
"""The model module."""
-from typing import Any, Type
-from ._model_base import ChatModelBase
+from ._base import ChatModelBase
+from ._model_card import ModelCard
from ._model_response import ChatResponse, StructuredResponse
-from ._dashscope_model import DashScopeChatModel
-from ._openai_model import OpenAIChatModel
-from ._anthropic_model import AnthropicChatModel
-from ._ollama_model import OllamaChatModel
-from ._gemini_model import GeminiChatModel
from ._model_usage import ChatUsage
-
-# Built-in model classes (internal use only)
-_BUILTIN_MODELS: list[Type[ChatModelBase]] = [
- DashScopeChatModel,
- OpenAIChatModel,
- AnthropicChatModel,
- OllamaChatModel,
- GeminiChatModel,
-]
-
-
-def _deserialize_model(
- data: dict[str, Any],
- custom_classes: list[Type[ChatModelBase]] | None = None,
- context: dict[str, Any] | None = None,
-) -> ChatModelBase:
- """Deserialize a chat model from a dictionary.
-
- Args:
- data: Dictionary containing serialized model data with 'type' field.
- custom_classes: Optional list of custom model classes to support.
- context: Optional context dict to pass to nested validators.
-
- Returns:
- Deserialized model instance.
-
- Raises:
- ValueError: If 'type' field is missing or unknown.
- """
- if "type" not in data:
- raise ValueError("Model data must contain 'type' field")
-
- type_value = data["type"]
-
- all_classes = _BUILTIN_MODELS + (custom_classes or [])
- registry = {
- cls.model_fields["type"].default: cls
- for cls in all_classes
- if "type" in cls.model_fields
- and cls.model_fields["type"].default is not None
- }
-
- if type_value not in registry:
- raise ValueError(
- f"Unknown model type '{type_value}'. "
- f"Available types: {list(registry.keys())}",
- )
-
- return registry[type_value].model_validate(data, context=context)
-
+from ._anthropic import AnthropicChatModel
+from ._dashscope import DashScopeChatModel
+from ._deepseek import DeepSeekChatModel
+from ._gemini import GeminiChatModel
+from ._ollama import OllamaChatModel
+from ._openai_chat import OpenAIChatModel
+from ._xai import XAIChatModel
+from ._kimi import KimiChatModel
+from ._openai_response import OpenAIResponseModel
__all__ = [
"ChatUsage",
"ChatModelBase",
"ChatResponse",
+ "ModelCard",
"StructuredResponse",
- "DashScopeChatModel",
- "OpenAIChatModel",
"AnthropicChatModel",
- "OllamaChatModel",
+ "DashScopeChatModel",
+ "DeepSeekChatModel",
"GeminiChatModel",
+ "OllamaChatModel",
+ "OpenAIChatModel",
+ "XAIChatModel",
+ "KimiChatModel",
+ "OpenAIResponseModel",
]
diff --git a/src/agentscope/model/_anthropic/__init__.py b/src/agentscope/model/_anthropic/__init__.py
new file mode 100644
index 000000000..fd62e62a5
--- /dev/null
+++ b/src/agentscope/model/_anthropic/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The Anthropic LLM API modules."""
+
+from ._model import AnthropicCredential, AnthropicChatModel
+
+__all__ = [
+ "AnthropicCredential",
+ "AnthropicChatModel",
+]
diff --git a/src/agentscope/model/_anthropic_model.py b/src/agentscope/model/_anthropic/_model.py
similarity index 64%
rename from src/agentscope/model/_anthropic_model.py
rename to src/agentscope/model/_anthropic/_model.py
index 39e826cce..830d8f0cf 100644
--- a/src/agentscope/model/_anthropic_model.py
+++ b/src/agentscope/model/_anthropic/_model.py
@@ -1,119 +1,101 @@
# -*- coding: utf-8 -*-
-"""The Anthropic API model classes."""
-from datetime import datetime
-from typing import (
- Any,
- AsyncGenerator,
- TYPE_CHECKING,
- List,
- Literal,
-)
+"""The Anthropic chat model implementation."""
from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
-from ._model_base import ChatModelBase
-from ._model_response import ChatResponse
-from ._model_usage import ChatUsage
-from ..formatter import FormatterBase, AnthropicChatFormatter
-from ..message import TextBlock, ToolCallBlock, ThinkingBlock
-from ..tool import ToolChoice
-from ..tracing import trace_llm
-from ..types import JSONSerializableObject
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import AnthropicCredential
+from ...formatter import FormatterBase, AnthropicChatFormatter
+from ...message import ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+from ...tracing import trace_llm
if TYPE_CHECKING:
from anthropic.types.message import Message
from anthropic import AsyncStream
else:
- Message = "anthropic.types.message.Message"
- AsyncStream = "anthropic.AsyncStream"
+ Message = Any
+ AsyncStream = Any
class AnthropicChatModel(ChatModelBase):
- """The Anthropic model wrapper for AgentScope."""
+ """The Anthropic chat model."""
+
+ type: Literal["anthropic_chat"] = "anthropic_chat"
+ """The type of the chat model."""
+
+ class Parameters(BaseModel):
+ """The parameters for the Anthropic chat model."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description=(
+ "The maximum number of tokens to generate in the chat "
+ "completion."
+ ),
+ gt=0,
+ )
- class ThinkingConfig(BaseModel):
- """Configuration for Claude's internal reasoning process."""
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description="The thinking enable for the LLM output.",
+ )
- enable_thinking: bool
- budget_tokens: int = 1024
+ thinking_budget: int | None = Field(
+ default=None,
+ title="Thinking budget",
+ description="The thinking budget for the LLM output.",
+ gt=0,
+ )
def __init__(
self,
- model_name: str,
- context_length: int,
- api_key: str | None = None,
- max_tokens: int = 2048,
+ credential: AnthropicCredential,
+ model: str,
+ parameters: "AnthropicChatModel.Parameters | None" = None,
stream: bool = True,
- max_retries: int = 0,
- fallback_model_name: str | None = None,
+ max_retries: int = 3,
+ context_size: int = 200000,
formatter: FormatterBase | None = None,
- thinking_config: ThinkingConfig | None = None,
- stream_tool_parsing: bool = True,
- client_kwargs: dict[str, JSONSerializableObject] | None = None,
- generate_kwargs: dict[str, JSONSerializableObject] | None = None,
) -> None:
"""Initialize the Anthropic chat model.
Args:
- model_name (`str`):
- The model names.
- context_length (`int`):
- The context length of the model, used in context compression.
- api_key (`str`):
- The anthropic API key.
- max_tokens (`int`):
- Limit the maximum token count the model can generate.
- stream (`bool`):
- The streaming output or not
- max_retries (`int`, optional):
- Maximum number of retries on failure. Defaults to 0.
- fallback_model_name (`str | None`, optional):
- Fallback model name to use after all retries fail.
- formatter (`FormatterBase | None`, optional):
- Formatter for message preprocessing.
- thinking_config (`ThinkingConfig | None`, default `None`):
- Configuration for Claude's internal reasoning process.
- stream_tool_parsing (`bool`, default to `True`):
- Whether to parse incomplete tool use JSON during streaming
- with auto-repair. If True, partial JSON (e.g., `'{"a": "x'`)
- is repaired to valid dicts ({"a": "x"}) in real-time for
- immediate tool function input. Otherwise, the input field
- remains {} until the final chunk arrives.
- client_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments to initialize the Anthropic client.
- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments used in Anthropic API generation,
- e.g. `temperature`, `seed`.
+ credential (`AnthropicCredential`):
+ The Anthropic credential used to authenticate API calls.
+ model (`str`):
+ The Anthropic model name, e.g. ``claude-opus-4-7``.
+ parameters (`AnthropicChatModel.Parameters | None`, defaults to \
+ `None`):
+ The Anthropic API parameters. When ``None``, the default
+ parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the Anthropic API.
+ context_size (`int`, defaults to `200000`):
+ The model context size used for context compression.
+ formatter (`FormatterBase | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to the format
+ required by the Anthropic API. When ``None``, an
+ ``AnthropicChatFormatter`` instance will be used.
"""
-
- try:
- import anthropic
- except ImportError as e:
- raise ImportError(
- "Please install the `anthropic` package by running "
- "`pip install anthropic`.",
- ) from e
-
super().__init__(
- model_name=model_name,
+ model=model,
stream=stream,
- context_length=context_length,
max_retries=max_retries,
- fallback_model_name=fallback_model_name,
- formatter=formatter or AnthropicChatFormatter(),
- )
-
- self.client = anthropic.AsyncAnthropic(
- api_key=api_key,
- **(client_kwargs or {}),
+ context_size=context_size,
)
- self.max_tokens = max_tokens
- self.thinking_config = thinking_config
- self.stream_tool_parsing = stream_tool_parsing
- self.generate_kwargs = generate_kwargs or {}
+ self.credential = credential
+ self.parameters = parameters or self.Parameters()
+ self.formatter = formatter or AnthropicChatFormatter()
@trace_llm
async def _call_api(
@@ -121,7 +103,7 @@ class AnthropicChatModel(ChatModelBase):
model_name: str,
messages: list[dict[str, Any]],
tools: list[dict] | None = None,
- tool_choice: Literal["auto", "none", "required"] | str | None = None,
+ tool_choice: ToolChoice | None = None,
**generate_kwargs: Any,
) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
"""Get the response from Anthropic chat completions API by the given
@@ -135,29 +117,47 @@ class AnthropicChatModel(ChatModelBase):
required, and `name` field is optional.
tools (`list[dict]`, default `None`):
The tools JSON schemas.
- tool_choice (`Literal["auto", "none", "required"] | str \
- | None`, default `None`):
+ tool_choice (`ToolChoice | None`, optional):
Controls which (if any) tool is called by the model.
**generate_kwargs (`Any`):
The keyword arguments for Anthropic chat completions API.
Returns:
`ChatResponse | AsyncGenerator[ChatResponse, None]`:
- The response from the Anthropic chat completions API."""
+ A ``ChatResponse`` when streaming is disabled, or an async
+ generator of ``ChatResponse`` objects when streaming is
+ enabled.
+ """
+
+ import anthropic
+
+ client = anthropic.AsyncAnthropic(
+ api_key=self.credential.api_key.get_secret_value(),
+ base_url=self.credential.base_url,
+ )
+
+ # Anthropic requires max_tokens; fall back to a safe default when
+ # the user hasn't configured one explicitly.
+ max_tokens = self.parameters.max_tokens or 8192
kwargs: dict[str, Any] = {
"model": model_name,
- "max_tokens": self.max_tokens,
+ "max_tokens": max_tokens,
"stream": self.stream,
- **self.generate_kwargs,
**generate_kwargs,
}
- if self.thinking_config and "thinking" not in kwargs:
+
+ # Anthropic extended thinking — only set when explicitly enabled.
+ # Anthropic requires max_tokens > budget_tokens strictly.
+ if self.parameters.thinking_enable and "thinking" not in kwargs:
+ budget = self.parameters.thinking_budget or (max_tokens // 2)
+ if budget >= max_tokens:
+ # Auto-expand max_tokens to satisfy the strict inequality.
+ max_tokens = budget + 1024
+ kwargs["max_tokens"] = max_tokens
kwargs["thinking"] = {
- "type": "enabled"
- if self.thinking_config.enable_thinking
- else "disabled",
- "budget_tokens": self.thinking_config.budget_tokens,
+ "type": "enabled",
+ "budget_tokens": budget,
}
if tools:
@@ -169,16 +169,18 @@ class AnthropicChatModel(ChatModelBase):
tools,
)
+ formatted_messages = await self.formatter.format(messages)
+
# Extract the system message
- if messages[0]["role"] == "system":
- kwargs["system"] = messages[0]["content"]
- messages = messages[1:]
+ if formatted_messages and formatted_messages[0]["role"] == "system":
+ kwargs["system"] = formatted_messages[0]["content"]
+ formatted_messages = formatted_messages[1:]
- kwargs["messages"] = messages
+ kwargs["messages"] = formatted_messages
start_datetime = datetime.now()
- response = await self.client.messages.create(**kwargs)
+ response = await client.messages.create(**kwargs)
if self.stream:
return self._parse_anthropic_stream_completion_response(
@@ -209,8 +211,9 @@ class AnthropicChatModel(ChatModelBase):
Anthropic Message object to parse.
Returns:
- ChatResponse (`ChatResponse`):
- A ChatResponse object containing the content blocks and usage.
+ `ChatResponse`:
+ A single ``ChatResponse`` with ``is_last=True`` containing
+ the extracted content blocks and usage.
"""
content_blocks: List[ThinkingBlock | TextBlock | ToolCallBlock] = []
@@ -222,8 +225,9 @@ class AnthropicChatModel(ChatModelBase):
):
thinking_block = ThinkingBlock(
thinking=content_block.thinking,
+ signature=getattr(content_block, "signature", "")
+ or "",
)
- thinking_block["signature"] = content_block.signature
content_blocks.append(thinking_block)
elif (
@@ -281,22 +285,21 @@ class AnthropicChatModel(ChatModelBase):
response (`AsyncStream`):
Anthropic AsyncStream object to parse.
- Returns:
- `AsyncGenerator[ChatResponse, None]`:
- An async generator that yields ChatResponse objects containing
- the content blocks and usage information for each chunk in
- the streaming response.
+ Yields:
+ `ChatResponse`:
+ Incremental ``ChatResponse`` objects with ``is_last=False``
+ followed by a final one with ``is_last=True`` containing the
+ fully accumulated content blocks and usage.
"""
usage = None
response_id: str | None = None
- # Accumulated state
- acc_text = ""
- acc_thinking = ""
+ # All delta should have the same block identifier
+ acc_text = TextBlock(text="")
+ acc_thinking = ThinkingBlock(thinking="")
thinking_signature = ""
- acc_tool_calls: OrderedDict = (
- OrderedDict()
- ) # index -> {id, name, input}
+ # index -> {id, name, input}
+ acc_tool_calls: OrderedDict = OrderedDict()
async for event in response:
delta_content: list = []
@@ -330,12 +333,17 @@ class AnthropicChatModel(ChatModelBase):
block_index = event.index
delta = event.delta
if delta.type == "text_delta":
- acc_text += delta.text
- delta_content.append(TextBlock(text=delta.text))
+ acc_text.text += delta.text
+ delta_content.append(
+ TextBlock(id=acc_text.id, text=delta.text),
+ )
elif delta.type == "thinking_delta":
- acc_thinking += delta.thinking
+ acc_thinking.thinking += delta.thinking
delta_content.append(
- ThinkingBlock(thinking=delta.thinking),
+ ThinkingBlock(
+ id=acc_thinking.id,
+ thinking=delta.thinking,
+ ),
)
elif delta.type == "signature_delta":
thinking_signature = delta.signature
@@ -370,12 +378,11 @@ class AnthropicChatModel(ChatModelBase):
# Build final accumulated content
final_content: list = []
- if acc_thinking:
- thinking_block = ThinkingBlock(thinking=acc_thinking)
- thinking_block["signature"] = thinking_signature
- final_content.append(thinking_block)
- if acc_text:
- final_content.append(TextBlock(text=acc_text))
+ if acc_thinking.thinking:
+ acc_thinking.signature = thinking_signature
+ final_content.append(acc_thinking)
+ if acc_text.text:
+ final_content.append(acc_text)
for tc in acc_tool_calls.values():
input_str = tc["input"]
final_content.append(
diff --git a/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yaml b/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yaml
new file mode 100644
index 000000000..feae8f167
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yaml
@@ -0,0 +1,21 @@
+name: claude-haiku-4-5
+label: Claude Haiku 4.5
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 200000
+output_size: 65536
+
+parameter_overrides:
+ max_tokens: {"maximum": 65536}
diff --git a/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yaml b/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yaml
new file mode 100644
index 000000000..a3a9beee1
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yaml
@@ -0,0 +1,21 @@
+name: claude-opus-4-7
+label: Claude Opus 4.7
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1000000
+output_size: 128000
+
+parameter_overrides:
+ max_tokens: {"maximum": 128000}
diff --git a/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yaml b/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yaml
new file mode 100644
index 000000000..61d22d04c
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yaml
@@ -0,0 +1,21 @@
+name: claude-sonnet-4-6
+label: Claude Sonnet 4.6
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1000000
+output_size: 65536
+
+parameter_overrides:
+ max_tokens: {"maximum": 65536}
diff --git a/src/agentscope/model/_model_base.py b/src/agentscope/model/_base.py
similarity index 71%
rename from src/agentscope/model/_model_base.py
rename to src/agentscope/model/_base.py
index 54d1b4a2e..b0376260e 100644
--- a/src/agentscope/model/_model_base.py
+++ b/src/agentscope/model/_base.py
@@ -1,92 +1,125 @@
# -*- coding: utf-8 -*-
-"""The chat model base class."""
+"""The base class for the chat models."""
+import inspect
import json
from abc import abstractmethod
from copy import deepcopy
-from typing import AsyncGenerator, Any, TYPE_CHECKING, Type
+from pathlib import Path
+from typing import Type, Any, AsyncGenerator
import jsonschema
from pydantic import BaseModel
-from ._model_response import ChatResponse, StructuredResponse
+from ._model_response import StructuredResponse, ChatResponse
+from ._model_card import ModelCard
from .._logging import logger
from .._utils._common import _json_loads_with_repair
-from ..formatter import FormatterBase
from ..message import (
Msg,
TextBlock,
- ThinkingBlock,
+ UserMsg,
ToolCallBlock,
+ ThinkingBlock,
ToolResultBlock,
DataBlock,
URLSource,
Base64Source,
- UserMsg,
)
-
-if TYPE_CHECKING:
- from ..tool import ToolChoice
-else:
- ToolChoice = Any
+from ..tool import ToolChoice
_TOOL_CHOICE_MODES = ["auto", "none", "required"]
class ChatModelBase:
- """Base class for chat models."""
+ """The base class for chat models."""
- model_name: str
- """The model name"""
+ class Parameters(BaseModel):
+ """Each subclass should implement this inner class to define its
+ parameters."""
+
+ model: str
+ """The model name."""
stream: bool
- """Is the model output streaming or not"""
+ """The enable stream output for the LLM output."""
max_retries: int
- """Maximum number of retries on failure"""
-
- context_length: int
- """The context length of the model, which will be used in context
- compression."""
+ """The maximum retries for the Anthropic API."""
- fallback_model_name: str | None
- """Fallback model name to use after all retries fail"""
-
- formatter: FormatterBase
- """The API formatter that format the messages into the required format for
- the underlying API."""
+ context_size: int
+ """The model context size that will be used in the context compression."""
def __init__(
self,
- model_name: str,
- stream: bool,
- context_length: int,
- formatter: FormatterBase,
- max_retries: int = 0,
- fallback_model_name: str | None = None,
+ model: str,
+ stream: bool = True,
+ max_retries: int = 3,
+ context_size: int = 32768,
) -> None:
- """Initialize the chat model base class.
+ """Initialize the chat model base.
Args:
- model_name (`str`):
- The name of the model
- stream (`bool`):
- Whether the model output is streaming or not
- context_length (`int`):
- The context length of the model, which will be used
- in context compression.
- formatter (`FormatterBase`):
- Formatter for message preprocessing.
- max_retries (`int`, optional):
- Maximum number of retries on failure. Defaults to 0.
- fallback_model_name (`str | None`, optional):
- Fallback model name to use after all retries fail.
+ model (`str`):
+ The model name.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output for the LLM.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for API calls.
+ context_size (`int`, defaults to `32768`):
+ The model context size used for context compression.
"""
- self.model_name = model_name
+ self.model = model
self.stream = stream
- self.context_length = context_length
self.max_retries = max_retries
- self.fallback_model_name = fallback_model_name
- self.formatter = formatter
+ self.context_size = context_size
+
+ @classmethod
+ def list_models(
+ cls,
+ custom_yaml_dir: str | None = None,
+ ) -> list[ModelCard]:
+ """List candidate models of the API.
+
+ Args:
+ custom_yaml_dir (`str | None`):
+ The custom YAML directory.
+
+ Returns:
+ `list[ModelCard]`:
+ A list of candidate models.
+ """
+
+ # Determine YAML directory
+ if custom_yaml_dir is None:
+ # Use the ``_models`` directory that sits next to the concrete
+ # subclass's source file (not this base file).
+ subclass_file = Path(inspect.getfile(cls))
+ yaml_dir = subclass_file.parent / "_models"
+ else:
+ yaml_dir = Path(custom_yaml_dir)
+
+ # Find all .yaml files
+ yaml_files = list(yaml_dir.glob("*.yaml"))
+
+ # Load each YAML file and create ModelCard
+ model_cards = []
+ for yaml_file in yaml_files:
+ try:
+ card = ModelCard.from_yaml(
+ yaml_path=str(yaml_file),
+ parameter_class=cls.Parameters,
+ )
+ model_cards.append(card)
+ except Exception as e:
+ # Log error but continue with other files
+ logger.warning(
+ "Warning: Failed to load %s: %s",
+ yaml_file,
+ str(e),
+ )
+ continue
+
+ return model_cards
async def __call__(
self,
@@ -114,42 +147,38 @@ class ChatModelBase:
last_error: Exception | None = None
- for model_name in self._models_to_try():
- for attempt in range(self.max_retries + 1):
- try:
- return await self._call_api(
- model_name,
- messages=messages,
- tools=tools,
- tool_choice=tool_choice,
- **kwargs,
+ for attempt in range(self.max_retries + 1):
+ try:
+ return await self._call_api(
+ self.model,
+ messages=messages,
+ tools=tools,
+ tool_choice=tool_choice,
+ **kwargs,
+ )
+ except Exception as e:
+ last_error = e
+ if attempt < self.max_retries:
+ logger.warning(
+ "Attempt %d failed for model %s: %s. Retrying...",
+ attempt + 1,
+ self.model,
+ str(e),
+ )
+ else:
+ logger.warning(
+ "All %d attempt(s) failed for model %s.",
+ self.max_retries + 1,
+ self.model,
)
- except Exception as e:
- last_error = e
- if attempt < self.max_retries:
- logger.warning(
- "Attempt %d failed for model %s: %s. Retrying...",
- attempt + 1,
- model_name,
- str(e),
- )
- else:
- logger.warning(
- "All %d attempt(s) failed for model %s.",
- self.max_retries + 1,
- model_name,
- )
if last_error is not None:
raise last_error
- raise RuntimeError("No models to try")
- def _models_to_try(self) -> list[str]:
- """Return the ordered list of model names to try."""
- models = [self.model_name]
- if self.fallback_model_name:
- models.append(self.fallback_model_name)
- return models
+ raise RuntimeError(
+ f"Failed to call model {self.model} after "
+ f"{self.max_retries + 1} retries.",
+ )
@abstractmethod
async def _call_api(
@@ -318,34 +347,37 @@ class ChatModelBase:
last_error: Exception | None = None
- for model_name in self._models_to_try():
- for attempt in range(self.max_retries + 1):
- try:
- return await self._call_api_with_structured_output(
- model_name,
- messages=messages,
- structured_model=structured_model,
- **kwargs,
+ for attempt in range(self.max_retries + 1):
+ try:
+ return await self._call_api_with_structured_output(
+ self.model,
+ messages=messages,
+ structured_model=structured_model,
+ **kwargs,
+ )
+ except Exception as e:
+ last_error = e
+ if attempt < self.max_retries:
+ logger.warning(
+ "Attempt %d failed for model %s: %s. Retrying...",
+ attempt + 1,
+ self.model,
+ str(e),
+ )
+ else:
+ logger.warning(
+ "All %d attempt(s) failed for model %s.",
+ self.max_retries + 1,
+ self.model,
)
- except Exception as e:
- last_error = e
- if attempt < self.max_retries:
- logger.warning(
- "Attempt %d failed for model %s: %s. Retrying...",
- attempt + 1,
- model_name,
- str(e),
- )
- else:
- logger.warning(
- "All %d attempt(s) failed for model %s.",
- self.max_retries + 1,
- model_name,
- )
if last_error is not None:
raise last_error
- raise RuntimeError("No models to try")
+
+ raise RuntimeError(
+ f"Failed to generate structured output after "
+ f"{self.max_retries + 1} retries.",
+ )
async def _call_api_with_structured_output(
self,
diff --git a/src/agentscope/model/_dashscope/__init__.py b/src/agentscope/model/_dashscope/__init__.py
new file mode 100644
index 000000000..e22af4fa6
--- /dev/null
+++ b/src/agentscope/model/_dashscope/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The DashScope API modules."""
+
+from ._model import DashScopeChatModel, DashScopeCredential
+
+__all__ = [
+ "DashScopeChatModel",
+ "DashScopeCredential",
+]
diff --git a/src/agentscope/model/_dashscope_model.py b/src/agentscope/model/_dashscope/_model.py
similarity index 72%
rename from src/agentscope/model/_dashscope_model.py
rename to src/agentscope/model/_dashscope/_model.py
index 728d7e053..c2398ec51 100644
--- a/src/agentscope/model/_dashscope_model.py
+++ b/src/agentscope/model/_dashscope/_model.py
@@ -1,30 +1,22 @@
# -*- coding: utf-8 -*-
-"""The dashscope API model classes."""
+"""The DashScope chat model class."""
import uuid
import warnings
from datetime import datetime
from http import HTTPStatus
-from typing import (
- Any,
- AsyncGenerator,
- Generator,
- Union,
- TYPE_CHECKING,
- List,
-)
-
-from pydantic import BaseModel
+from typing import Any, AsyncGenerator, Generator, List, Literal, TYPE_CHECKING
+
+from pydantic import BaseModel, Field
from aioitertools import iter as giter
-from ._model_base import ChatModelBase
-from ._model_response import ChatResponse
-from ._model_usage import ChatUsage
-from ..formatter import FormatterBase, DashScopeChatFormatter
-from ..message import TextBlock, ToolCallBlock, ThinkingBlock, Msg
-from ..tool import ToolChoice
-from ..tracing import trace_llm
-from ..types import JSONSerializableObject
-from .._logging import logger
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import DashScopeCredential
+from ...formatter import FormatterBase, DashScopeChatFormatter
+from ...message import Msg, TextBlock, ThinkingBlock, ToolCallBlock
+from ...tool import ToolChoice
+from ...tracing import trace_llm
if TYPE_CHECKING:
@@ -33,131 +25,117 @@ if TYPE_CHECKING:
MultiModalConversationResponse,
)
else:
- GenerationResponse = (
- "dashscope.api_entities.dashscope_response.GenerationResponse"
- )
- MultiModalConversationResponse = (
- "dashscope.api_entities.dashscope_response."
- "MultiModalConversationResponse"
- )
+ GenerationResponse = Any
+ MultiModalConversationResponse = Any
class DashScopeChatModel(ChatModelBase):
- """The DashScope chat model class, which unifies the Generation and
- MultimodalConversation APIs into one method.
-
- This class provides a unified interface for DashScope API by automatically
- selecting between text-only (Generation API) and multimodal
- (MultiModalConversation API) endpoints. The `multimodality` parameter
- allows explicit control over API selection:
-
- - When `multimodality=True`: Forces use of MultiModalConversation API
- for handling images, videos, and other multimodal inputs
- - When `multimodality=False`: Forces use of Generation API for
- text-only processing
- - When `multimodality=None` (default): Automatically selects the API
- based on model name (e.g., models with "-vl" suffix or starting
- with "qvq" will use MultiModalConversation API)
-
- This design enables seamless switching between text and multimodal
- models without changing code structure, making it easier to work with
- DashScope's diverse model offerings.
- """
-
- class ThinkingConfig(BaseModel):
- """The configuration for the thinking process in DashScope API."""
-
- enable_thinking: bool
- thinking_budget: int = 2000
- preserve_thinking: bool = False
+ """The DashScope chat model."""
+
+ class Parameters(BaseModel):
+ """The parameters for DashScope LLM API."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description="The maximum number of tokens for the LLM output.",
+ gt=0,
+ )
+
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description="The thinking enable for the LLM output.",
+ )
+
+ thinking_budget: int | None = Field(
+ default=None,
+ title="Thinking budget",
+ description="The thinking budget for the LLM output.",
+ gt=0,
+ )
+
+ temperature: float | None = Field(
+ default=None,
+ title="Temperature",
+ description="The temperature for the LLM output.",
+ ge=0,
+ lt=2,
+ )
+
+ top_p: float | None = Field(
+ default=None,
+ title="Top P",
+ description="The top P value for the LLM output.",
+ gt=0,
+ le=1,
+ )
+
+ top_k: int | None = Field(
+ default=None,
+ title="Top K",
+ description="The top K value for the LLM output.",
+ gt=0,
+ le=100,
+ )
+
+ parallel_tool_calls: bool = Field(
+ default=True,
+ title="Parallel Tool Calls",
+ description="If enable parallel tool calls for the LLM output.",
+ )
+
+ type: Literal["dashscope_chat"] = "dashscope_chat"
+ """The type of the chat model."""
def __init__(
self,
- model_name: str,
- api_key: str,
- context_length: int,
+ credential: DashScopeCredential,
+ model: str,
+ parameters: "DashScopeChatModel.Parameters | None" = None,
stream: bool = True,
- max_retries: int = 0,
- fallback_model_name: str | None = None,
+ max_retries: int = 3,
+ context_size: int = 131072,
+ multimodality: bool | None = None,
formatter: FormatterBase | None = None,
- thinking_config: ThinkingConfig | None = None,
- multimodality: bool = False,
- generate_kwargs: dict[str, JSONSerializableObject] | None = None,
- base_http_api_url: str | None = None,
- **_kwargs: Any,
) -> None:
"""Initialize the DashScope chat model.
Args:
- model_name (`str`):
- The model names.
- api_key (`str`):
- The dashscope API key.
- context_length (`int`):
- The context length of the model.
- stream (`bool`):
- The streaming output or not
- enable_thinking (`bool | None`, optional):
- Enable thinking or not, only support Qwen3, QwQ, DeepSeek-R1.
- Refer to `DashScope documentation
- <https://help.aliyun.com/zh/model-studio/deep-thinking>`_
- for more details.
- multimodality (`bool | None`, optional):
- Whether to use multimodal conversation API. If `True`,
- it will use `dashscope.AioMultiModalConversation.call`
- to process multimodal inputs such as images and text. If
- `False`, it will use
- `dashscope.aigc.generation.AioGeneration.call` to process
- text inputs. If `None` (default), the choice is based on
- the model name.
- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments used in DashScope API generation,
- e.g. `temperature`, `seed`.
- base_http_api_url (`str | None`, optional):
- The base URL for DashScope API requests. If not provided,
- the default base URL from the DashScope SDK will be used.
- stream_tool_parsing (`bool`, default to `True`):
- Whether to parse incomplete tool use JSON in streaming mode
- with auto-repair. If True, partial JSON (e.g., `'{"a": "x'`)
- is repaired to valid dicts (`{"a": "x"}`) in real-time for
- immediate tool function input. Otherwise, the input field
- remains {} until the final chunk arrives.
- **_kwargs (`Any`):
- Additional keyword arguments.
+ credential (`DashScopeCredential`):
+ The DashScope credential used to authenticate API calls.
+ model (`str`):
+ The DashScope model name, e.g. ``qwen-plus``.
+ parameters (`DashScopeChatModel.Parameters | None`, defaults to \
+ `None`):
+ The DashScope API parameters. When ``None``, the default
+ parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the DashScope API.
+ context_size (`int`, defaults to `131072`):
+ The model context size used for context compression.
+ multimodality (`bool | None`, defaults to `None`):
+ Whether to call the MultiModalConversation API. ``True``
+ forces multimodal mode, ``False`` forces text-only mode,
+ and ``None`` auto-detects from the model name
+ (e.g. ``qvq`` or ``-vl`` suffix).
+ formatter (`FormatterBase | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to the format
+ required by the DashScope API. When ``None``, a
+ ``DashScopeChatFormatter`` instance will be used.
"""
-
- self.thinking_config = (
- thinking_config
- or DashScopeChatModel.ThinkingConfig(
- enable_thinking=False,
- )
- )
-
- if self.thinking_config.enable_thinking and not stream:
- logger.info(
- "In DashScope API, `stream` must be True when "
- "`enable_thinking` is True. ",
- )
- stream = True
-
super().__init__(
- model_name,
- stream,
- context_length,
- formatter or DashScopeChatFormatter(),
- max_retries,
- fallback_model_name,
+ model=model,
+ stream=stream,
+ max_retries=max_retries,
+ context_size=context_size,
)
-
- self.api_key = api_key
+ self.credential = credential
+ self.parameters = parameters or self.Parameters()
self.multimodality = multimodality
- self.generate_kwargs = generate_kwargs or {}
-
- if base_http_api_url is not None:
- import dashscope
-
- dashscope.base_http_api_url = base_http_api_url
+ self.formatter = formatter or DashScopeChatFormatter()
@trace_llm
async def _call_api(
@@ -210,7 +188,6 @@ class DashScopeChatModel(ChatModelBase):
# In agentscope, the `incremental_output` must be `True` when
# `self.stream` is True
"incremental_output": self.stream,
- **self.generate_kwargs,
**kwargs,
}
@@ -225,25 +202,32 @@ class DashScopeChatModel(ChatModelBase):
tools,
)
- # thinking related options
- kwargs = {**kwargs, **self.thinking_config.model_dump()}
+ # thinking related options — map to DashScope API parameter names
+ kwargs["enable_thinking"] = self.parameters.thinking_enable
+ if self.parameters.thinking_budget is not None:
+ kwargs["thinking_budget"] = self.parameters.thinking_budget
# 3. Call the API and parse the response
start_datetime = datetime.now()
# Use MultiModalConversation API if multimodality is True, or if the
# model is multimodal based on the model name.
+ api_key = self.credential.api_key.get_secret_value()
if self.multimodality or (
self.multimodality is None
- and ("qvq" in self.model_name or "-vl" in self.model_name)
+ and (
+ "qvq" in model_name
+ or "-vl" in model_name
+ or "-omni" in model_name
+ )
):
response = await dashscope.AioMultiModalConversation.call(
- api_key=self.api_key,
+ api_key=api_key,
**kwargs,
)
else:
response = await dashscope.aigc.generation.AioGeneration.call(
- api_key=self.api_key,
+ api_key=api_key,
**kwargs,
)
@@ -351,6 +335,9 @@ class DashScopeChatModel(ChatModelBase):
# Use the index to identify different tool calls
index = tool_call.get("index", 0)
+ # Initialize accumulator for a new tool call index
+ acc_tool_calls.setdefault(index, {})
+
# Avoid appending duplicate id
if "id" in tool_call and tool_call["id"] != acc_tool_calls[
index
@@ -402,16 +389,24 @@ class DashScopeChatModel(ChatModelBase):
)
# Yield a final complete response with the accumulated content and
- # final usage
+ # final usage. Thinking comes before text to preserve the natural
+ # generation order (reasoning first, then answer).
content = []
- if acc_text.text:
- content.append(acc_text)
-
if acc_thinking.thinking:
content.append(acc_thinking)
+ if acc_text.text:
+ content.append(acc_text)
+
if acc_tool_calls:
- content.extend(acc_tool_calls.values())
+ content.extend(
+ ToolCallBlock(
+ id=tc.get("id", uuid.uuid4().hex),
+ name=tc.get("name", ""),
+ input=tc.get("arguments", "{}"),
+ )
+ for tc in acc_tool_calls.values()
+ )
yield ChatResponse(
id=response_id or uuid.uuid4().hex,
@@ -423,10 +418,7 @@ class DashScopeChatModel(ChatModelBase):
async def _parse_dashscope_generation_response(
self,
start_datetime: datetime,
- response: Union[
- GenerationResponse,
- MultiModalConversationResponse,
- ],
+ response: GenerationResponse | MultiModalConversationResponse,
) -> ChatResponse:
"""Given a DashScope GenerationResponse object, extract the content
blocks and usages from it.
@@ -435,7 +427,7 @@ class DashScopeChatModel(ChatModelBase):
start_datetime (`datetime`):
The start datetime of the response generation.
response (
- `Union[GenerationResponse, MultiModalConversationResponse]`
+ `GenerationResponse | MultiModalConversationResponse`
):
Dashscope GenerationResponse | MultiModalConversationResponse
object to parse.
diff --git a/src/agentscope/model/_dashscope/_models/qwen-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen-plus.yaml
new file mode 100644
index 000000000..f7f77d55e
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen-plus.yaml
@@ -0,0 +1,16 @@
+name: qwen-plus
+label: Qwen Plus
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1000000
+output_size: 16384
+
+parameter_overrides:
+ max_tokens: {"maximum": 16384}
diff --git a/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yaml
new file mode 100644
index 000000000..973e282dd
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yaml
@@ -0,0 +1,28 @@
+name: qwen3.5-omni-plus
+label: Qwen3.5-Omni-Plus
+status: active
+
+input_types:
+ - text/plain
+ - image/bmp
+ - image/jpeg
+ - image/png
+ - image/tiff
+ - image/webp
+ - image/heic
+ - audio/mp3
+ - audio/wav
+ - audio/flac
+ - video/mp4
+
+output_types:
+ - text/plain
+ - application/x-thinking
+ - audio/wav
+
+context_size: 262144
+output_size: 65536
+
+parameter_overrides:
+ max_tokens: {"maximum": 65536}
+
diff --git a/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yaml
new file mode 100644
index 000000000..3ae5e677d
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yaml
@@ -0,0 +1,24 @@
+name: qwen3.6-plus
+label: Qwen3.6-Plus
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/bmp
+ - image/jpeg
+ - image/png
+ - image/tiff
+ - image/webp
+ - image/heic
+ - video/mp4
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1000000
+output_size: 65536
+
+parameter_overrides:
+ max_tokens: {"maximum": 65536}
diff --git a/src/agentscope/model/_deepseek/__init__.py b/src/agentscope/model/_deepseek/__init__.py
new file mode 100644
index 000000000..580146f06
--- /dev/null
+++ b/src/agentscope/model/_deepseek/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The DeepSeek LLM API modules."""
+
+from ._model import DeepSeekCredential, DeepSeekChatModel
+
+__all__ = [
+ "DeepSeekCredential",
+ "DeepSeekChatModel",
+]
diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.py
new file mode 100644
index 000000000..52a247671
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_model.py
@@ -0,0 +1,384 @@
+# -*- coding: utf-8 -*-
+"""The DeepSeek chat model implementation."""
+from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import DeepSeekCredential
+from ...formatter import FormatterBase, DeepSeekChatFormatter
+from ...message import ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+from ...tracing import trace_llm
+
+if TYPE_CHECKING:
+ from openai.types.chat import ChatCompletion
+ from openai import AsyncStream
+else:
+ ChatCompletion = Any
+ AsyncStream = Any
+
+
+class DeepSeekChatModel(ChatModelBase):
+ """The DeepSeek chat model."""
+
+ class Parameters(BaseModel):
+ """The parameters for the DeepSeek chat model."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description="The maximum number of tokens for the LLM output.",
+ gt=0,
+ )
+
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description=(
+ "Whether to enable thinking. Note: for the DeepSeek API, "
+ "thinking mode is selected by choosing the deepseek-reasoner "
+ "model rather than an API parameter."
+ ),
+ )
+
+ temperature: float | None = Field(
+ default=None,
+ title="Temperature",
+ description="The temperature for the LLM output.",
+ ge=0,
+ le=2,
+ )
+
+ top_p: float | None = Field(
+ default=None,
+ title="Top P",
+ description="The top P value for the LLM output.",
+ gt=0,
+ le=1,
+ )
+
+ type: Literal["deepseek_chat"] = "deepseek_chat"
+ """The type of the chat model."""
+
+ def __init__(
+ self,
+ credential: DeepSeekCredential,
+ model: str,
+ parameters: "DeepSeekChatModel.Parameters | None" = None,
+ stream: bool = True,
+ max_retries: int = 3,
+ context_size: int = 65536,
+ formatter: FormatterBase | None = None,
+ ) -> None:
+ """Initialize the DeepSeek chat model.
+
+ Args:
+ credential (`DeepSeekCredential`):
+ The DeepSeek credential used to authenticate API calls.
+ model (`str`):
+ The DeepSeek model name, e.g. ``deepseek-chat``.
+ parameters (`DeepSeekChatModel.Parameters | None`, defaults to \
+ `None`):
+ The DeepSeek API parameters. When ``None``, the default
+ parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the DeepSeek API.
+ context_size (`int`, defaults to `65536`):
+ The model context size used for context compression.
+ formatter (`FormatterBase | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to the format
+ required by the DeepSeek API. When ``None``, a
+ ``DeepSeekChatFormatter`` instance will be used.
+ """
+ super().__init__(
+ model=model,
+ stream=stream,
+ max_retries=max_retries,
+ context_size=context_size,
+ )
+ self.credential = credential
+ self.parameters = parameters or self.Parameters()
+ self.formatter = formatter or DeepSeekChatFormatter()
+
+ @trace_llm
+ async def _call_api(
+ self,
+ model_name: str,
+ messages: list[Any],
+ tools: list[dict] | None = None,
+ tool_choice: ToolChoice | None = None,
+ **generate_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Call the DeepSeek chat completions API.
+
+ Args:
+ model_name (`str`):
+ The model name to use for this call.
+ messages (`list`):
+ A list of message dicts with ``role`` and ``content`` keys.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas.
+ tool_choice (`ToolChoice | None`, optional):
+ Controls which (if any) tool is called by the model.
+ **generate_kwargs (`Any`):
+ Extra keyword arguments forwarded to the API.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ A ``ChatResponse`` when streaming is disabled, or an async
+ generator of ``ChatResponse`` objects when streaming is
+ enabled.
+ """
+ import openai
+
+ client = openai.AsyncClient(
+ api_key=self.credential.api_key.get_secret_value(),
+ base_url=self.credential.base_url,
+ )
+
+ formatted_messages = await self.formatter.format(messages)
+
+ kwargs: dict[str, Any] = {
+ "model": model_name,
+ "messages": formatted_messages,
+ "stream": self.stream,
+ }
+
+ if self.parameters.max_tokens is not None:
+ kwargs["max_tokens"] = self.parameters.max_tokens
+
+ if self.parameters.temperature is not None:
+ kwargs["temperature"] = self.parameters.temperature
+
+ if self.parameters.top_p is not None:
+ kwargs["top_p"] = self.parameters.top_p
+
+ kwargs.update(generate_kwargs)
+
+ if tools:
+ kwargs["tools"] = tools
+
+ if tool_choice:
+ kwargs["tool_choice"] = self._format_tool_choice(
+ tool_choice,
+ tools,
+ )
+
+ if self.stream:
+ kwargs["stream_options"] = {"include_usage": True}
+
+ start_datetime = datetime.now()
+ response = await client.chat.completions.create(**kwargs)
+
+ if self.stream:
+ return self._parse_stream_response(start_datetime, response)
+
+ return self._parse_completion_response(start_datetime, response)
+
+ async def _parse_stream_response(
+ self,
+ start_datetime: datetime,
+ response: AsyncStream,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the DeepSeek streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`AsyncStream`):
+ The OpenAI-compatible async stream object.
+
+ Yields:
+ `ChatResponse`:
+ Incremental ``ChatResponse`` objects with ``is_last=False``
+ followed by a final one with ``is_last=True``.
+ """
+ usage = None
+ response_id: str | None = None
+ # All delta should have the same block identifier
+ acc_text = TextBlock(text="")
+ acc_thinking = ThinkingBlock(thinking="")
+ acc_tool_calls: OrderedDict = OrderedDict()
+
+ async with response as stream:
+ async for chunk in stream:
+ if chunk.usage:
+ usage = ChatUsage(
+ input_tokens=chunk.usage.prompt_tokens,
+ output_tokens=chunk.usage.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=chunk.usage,
+ )
+
+ # Capture response_id from the first chunk that carries it
+ response_id = response_id or getattr(chunk, "id", None)
+
+ if not chunk.choices:
+ continue
+
+ choice = chunk.choices[0]
+ delta = choice.delta
+
+ delta_thinking = (
+ getattr(delta, "reasoning_content", None) or ""
+ )
+ delta_text = getattr(delta, "content", None) or ""
+
+ acc_thinking.thinking += delta_thinking
+ acc_text.text += delta_text
+
+ for tool_call in getattr(delta, "tool_calls", None) or []:
+ idx = tool_call.index
+ if idx in acc_tool_calls:
+ if tool_call.function.arguments is not None:
+ acc_tool_calls[idx][
+ "input"
+ ] += tool_call.function.arguments
+ else:
+ acc_tool_calls[idx] = {
+ "id": tool_call.id,
+ "name": tool_call.function.name,
+ "input": tool_call.function.arguments or "",
+ }
+
+ delta_contents: List[
+ TextBlock | ToolCallBlock | ThinkingBlock
+ ] = []
+ if delta_thinking:
+ delta_contents.append(
+ ThinkingBlock(
+ id=acc_thinking.id,
+ thinking=delta_thinking,
+ ),
+ )
+ if delta_text:
+ delta_contents.append(
+ TextBlock(id=acc_text.id, text=delta_text),
+ )
+
+ if delta_contents:
+ _kwargs: dict[str, Any] = {
+ "content": delta_contents,
+ "usage": usage,
+ "is_last": False,
+ }
+ if response_id:
+ _kwargs["id"] = response_id
+ yield ChatResponse(**_kwargs)
+
+ final_contents: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+ if acc_thinking.thinking:
+ final_contents.append(acc_thinking)
+ if acc_text.text:
+ final_contents.append(acc_text)
+ for tc in acc_tool_calls.values():
+ final_contents.append(
+ ToolCallBlock(
+ id=tc["id"],
+ name=tc["name"],
+ input=tc["input"],
+ ),
+ )
+
+ _final_kwargs: dict[str, Any] = {
+ "content": final_contents,
+ "usage": usage,
+ "is_last": True,
+ }
+ if response_id:
+ _final_kwargs["id"] = response_id
+ yield ChatResponse(**_final_kwargs)
+
+ def _parse_completion_response(
+ self,
+ start_datetime: datetime,
+ response: ChatCompletion,
+ ) -> ChatResponse:
+ """Parse the DeepSeek non-streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`ChatCompletion`):
+ The OpenAI-compatible chat completion object.
+
+ Returns:
+ `ChatResponse`:
+ A single ``ChatResponse`` with ``is_last=True``.
+ """
+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+ if response.choices:
+ choice = response.choices[0]
+ reasoning = getattr(choice.message, "reasoning_content", None)
+ if isinstance(reasoning, str) and reasoning:
+ content_blocks.append(ThinkingBlock(thinking=reasoning))
+
+ if choice.message.content:
+ content_blocks.append(TextBlock(text=choice.message.content))
+
+ for tool_call in choice.message.tool_calls or []:
+ content_blocks.append(
+ ToolCallBlock(
+ id=tool_call.id,
+ name=tool_call.function.name,
+ input=tool_call.function.arguments,
+ ),
+ )
+
+ usage = None
+ if response.usage:
+ usage = ChatUsage(
+ input_tokens=response.usage.prompt_tokens,
+ output_tokens=response.usage.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=response.usage,
+ )
+
+ resp_kwargs: dict[str, Any] = {
+ "content": content_blocks,
+ "is_last": True,
+ "usage": usage,
+ }
+ response_id = getattr(response, "id", None)
+ if response_id:
+ resp_kwargs["id"] = response_id
+
+ return ChatResponse(**resp_kwargs)
+
+ def _format_tool_choice(
+ self,
+ tool_choice: ToolChoice | None,
+ tools: list[dict] | None,
+ ) -> str | dict | None:
+ """Format tool_choice parameter for the DeepSeek API.
+
+ Args:
+ tool_choice (`ToolChoice | None`):
+ The unified tool choice parameter which can be ``"auto"``,
+ ``"none"``, ``"required"``, or a specific function name.
+ tools (`list[dict] | None`):
+ The list of available tools, used for validation when
+ ``tool_choice`` is a specific function name.
+
+ Returns:
+ `str | dict | None`:
+ The formatted tool choice string or configuration dict for
+ the DeepSeek API, or ``None`` if ``tool_choice`` is ``None``.
+ """
+ self._validate_tool_choice(tool_choice, tools)
+
+ if tool_choice is None:
+ return None
+
+ if tool_choice in ["auto", "none", "required"]:
+ return tool_choice
+
+ return {"type": "function", "function": {"name": tool_choice}}
diff --git a/src/agentscope/model/_deepseek/_models/deepseek-chat.yaml b/src/agentscope/model/_deepseek/_models/deepseek-chat.yaml
new file mode 100644
index 000000000..36adf5c7e
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_models/deepseek-chat.yaml
@@ -0,0 +1,17 @@
+name: deepseek-chat
+label: DeepSeek Chat
+status: sunset
+deprecated_at: "2026-07-24T00:00:00"
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+
+context_size: 1000000
+output_size: 384000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 384000
diff --git a/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yaml b/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yaml
new file mode 100644
index 000000000..8c0b010c6
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yaml
@@ -0,0 +1,18 @@
+name: deepseek-reasoner
+label: DeepSeek Reasoner
+status: sunset
+deprecated_at: "2026-07-24T00:00:00"
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1000000
+output_size: 384000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 384000
diff --git a/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yaml b/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yaml
new file mode 100644
index 000000000..fed1a83f0
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yaml
@@ -0,0 +1,18 @@
+name: deepseek-v4-flash
+label: DeepSeek V4 Flash
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1000000
+output_size: 384000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 384000
diff --git a/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yaml b/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yaml
new file mode 100644
index 000000000..ffb1a2e93
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yaml
@@ -0,0 +1,18 @@
+name: deepseek-v4-pro
+label: DeepSeek V4 Pro
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1000000
+output_size: 384000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 384000
diff --git a/src/agentscope/model/_gemini/__init__.py b/src/agentscope/model/_gemini/__init__.py
new file mode 100644
index 000000000..66afd74a6
--- /dev/null
+++ b/src/agentscope/model/_gemini/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The Google Gemini LLM API modules."""
+
+from ._model import GeminiCredential, GeminiChatModel
+
+__all__ = [
+ "GeminiCredential",
+ "GeminiChatModel",
+]
diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.py
new file mode 100644
index 000000000..e96f6c612
--- /dev/null
+++ b/src/agentscope/model/_gemini/_model.py
@@ -0,0 +1,522 @@
+# -*- coding: utf-8 -*-
+"""The Google Gemini chat model implementation."""
+import base64
+import copy
+import json
+import uuid
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import GeminiCredential
+from ...formatter import FormatterBase, GeminiChatFormatter
+from ...message import ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+from ...tracing import trace_llm
+from ..._logging import logger
+
+if TYPE_CHECKING:
+ from google.genai.types import GenerateContentResponse
+else:
+ GenerateContentResponse = Any
+
+
+def _flatten_json_schema(schema: dict) -> dict:
+ """Flatten a JSON schema by resolving all $ref references.
+
+ Gemini API does not support ``$defs`` and ``$ref`` in JSON schemas.
+
+ Args:
+ schema (`dict`):
+ The JSON schema that may contain ``$defs`` and ``$ref`` references.
+
+ Returns:
+ `dict`:
+ A flattened JSON schema with all references resolved inline.
+ """
+ schema = copy.deepcopy(schema)
+ defs = schema.pop("$defs", {})
+
+ def _resolve_ref(obj: Any, visited: set | None = None) -> Any:
+ if visited is None:
+ visited = set()
+ if not isinstance(obj, dict):
+ if isinstance(obj, list):
+ return [_resolve_ref(item, visited.copy()) for item in obj]
+ return obj
+ if "$ref" in obj:
+ ref_path = obj["$ref"]
+ if ref_path.startswith("#/$defs/"):
+ def_name = ref_path[len("#/$defs/") :]
+ if def_name in visited:
+ logger.warning(
+ "Circular reference detected for '%s' in tool schema",
+ def_name,
+ )
+ return {
+ "type": "object",
+ "description": f"(circular: {def_name})",
+ }
+ visited.add(def_name)
+ if def_name in defs:
+ resolved = _resolve_ref(defs[def_name], visited.copy())
+ for key, value in obj.items():
+ if key != "$ref":
+ resolved[key] = _resolve_ref(value, visited.copy())
+ return resolved
+ return obj
+ result = {}
+ for key, value in obj.items():
+ result[key] = _resolve_ref(value, visited.copy())
+ return result
+
+ return _resolve_ref(schema)
+
+
+class GeminiChatModel(ChatModelBase):
+ """The Google Gemini chat model."""
+
+ class Parameters(BaseModel):
+ """The parameters for the Gemini chat model."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description="The maximum number of tokens for the LLM output.",
+ gt=0,
+ )
+
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description="Whether to enable thinking output.",
+ )
+
+ thinking_budget: int | None = Field(
+ default=None,
+ title="Thinking Budget",
+ description="The thinking budget in tokens.",
+ gt=0,
+ )
+
+ temperature: float | None = Field(
+ default=None,
+ title="Temperature",
+ description="The temperature for the LLM output.",
+ ge=0,
+ le=2,
+ )
+
+ top_p: float | None = Field(
+ default=None,
+ title="Top P",
+ description="The top P value for the LLM output.",
+ gt=0,
+ le=1,
+ )
+
+ type: Literal["gemini_chat"] = "gemini_chat"
+ """The type of the chat model."""
+
+ def __init__(
+ self,
+ credential: GeminiCredential,
+ model: str,
+ parameters: "GeminiChatModel.Parameters | None" = None,
+ stream: bool = True,
+ max_retries: int = 3,
+ context_size: int = 1048576,
+ formatter: FormatterBase | None = None,
+ ) -> None:
+ """Initialize the Gemini chat model.
+
+ Args:
+ credential (`GeminiCredential`):
+ The Google Gemini credential used to authenticate API calls.
+ model (`str`):
+ The Gemini model name, e.g. ``gemini-2.0-flash-exp``.
+ parameters (`GeminiChatModel.Parameters | None`, defaults to \
+ `None`):
+ The Gemini API parameters. When ``None``, the default
+ parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the Gemini API.
+ context_size (`int`, defaults to `1048576`):
+ The model context size used for context compression.
+ formatter (`FormatterBase | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to the format
+ required by the Gemini API. When ``None``, a
+ ``GeminiChatFormatter`` instance will be used.
+ """
+ super().__init__(
+ model=model,
+ stream=stream,
+ max_retries=max_retries,
+ context_size=context_size,
+ )
+ self.credential = credential
+ self.parameters = parameters or self.Parameters()
+ self.formatter = formatter or GeminiChatFormatter()
+
+ @trace_llm
+ async def _call_api(
+ self,
+ model_name: str,
+ messages: list[Any],
+ tools: list[dict] | None = None,
+ tool_choice: ToolChoice | None = None,
+ **config_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Call the Gemini chat API.
+
+ Args:
+ model_name (`str`):
+ The model name to use for this call.
+ messages (`list`):
+ A list of message objects for Gemini API.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas.
+ tool_choice (`ToolChoice | None`, optional):
+ Controls which (if any) tool is called by the model.
+ **config_kwargs (`Any`):
+ Extra keyword arguments for the Gemini config.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ A ``ChatResponse`` when streaming is disabled, or an async
+ generator of ``ChatResponse`` objects when streaming is
+ enabled.
+ """
+ from google import genai
+
+ client = genai.Client(
+ api_key=self.credential.api_key.get_secret_value(),
+ )
+
+ formatted_messages = await self.formatter.format(messages)
+
+ config: dict[str, Any] = {**config_kwargs}
+
+ if self.parameters.max_tokens is not None:
+ config["max_output_tokens"] = self.parameters.max_tokens
+
+ if self.parameters.temperature is not None:
+ config["temperature"] = self.parameters.temperature
+
+ if self.parameters.top_p is not None:
+ config["top_p"] = self.parameters.top_p
+
+ if self.parameters.thinking_enable:
+ config["thinking_config"] = {
+ "include_thoughts": True,
+ "thinking_budget": self.parameters.thinking_budget or 1024,
+ }
+
+ if tools:
+ config["tools"] = self._format_tools_json_schemas(tools)
+
+ if tool_choice:
+ config["tool_config"] = self._format_tool_choice(
+ tool_choice,
+ tools,
+ )
+
+ kwargs: dict[str, Any] = {
+ "model": model_name,
+ "contents": formatted_messages,
+ "config": config,
+ }
+
+ start_datetime = datetime.now()
+
+ if self.stream:
+ response = await client.aio.models.generate_content_stream(
+ **kwargs,
+ )
+ # Pass client to the generator so the aiohttp session it owns
+ # stays alive until the stream is fully consumed.
+ return self._parse_stream_response(
+ start_datetime,
+ response,
+ client,
+ )
+
+ response = await client.aio.models.generate_content(**kwargs)
+ return self._parse_completion_response(start_datetime, response)
+
+ async def _parse_stream_response(
+ self,
+ start_datetime: datetime,
+ response: Any,
+ _client: Any = None,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the Gemini streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`Any`):
+ The Gemini async stream object from
+ ``client.aio.models.generate_content_stream``.
+ _client (`Any`, optional):
+ The ``genai.Client`` that produced the stream. Held here so
+ its aiohttp session is not garbage-collected before the
+ stream is fully consumed.
+
+ Yields:
+ `ChatResponse`:
+ Incremental ``ChatResponse`` objects with ``is_last=False``
+ followed by a final one with ``is_last=True``.
+ """
+ # All delta should have the same block identifier
+ # Use the API's response_id when available (it arrives at the first
+ # chunk); otherwise generate a UUID to ensure all chunks share a
+ # stable id.
+ response_id: str | None = None
+ acc_text = TextBlock(text="")
+ acc_thinking = ThinkingBlock(thinking="")
+ acc_tool_calls: dict = {}
+ usage = None
+
+ async for chunk in response:
+ # Capture response_id from the first chunk that carries it
+ if response_id is None:
+ response_id = (
+ getattr(chunk, "response_id", None) or uuid.uuid4().hex
+ )
+
+ delta_content: list = []
+
+ if (
+ chunk.candidates
+ and chunk.candidates[0].content
+ and chunk.candidates[0].content.parts
+ ):
+ for part in chunk.candidates[0].content.parts:
+ if part.text:
+ if part.thought:
+ acc_thinking.thinking += part.text
+ delta_content.append(
+ ThinkingBlock(
+ id=acc_thinking.id,
+ thinking=part.text,
+ ),
+ )
+ else:
+ acc_text.text += part.text
+ delta_content.append(
+ TextBlock(id=acc_text.id, text=part.text),
+ )
+
+ if part.function_call:
+ keyword_args = part.function_call.args or {}
+ if part.thought_signature:
+ call_id = base64.b64encode(
+ part.thought_signature,
+ ).decode("utf-8")
+ else:
+ call_id = part.function_call.id
+ input_str = json.dumps(
+ keyword_args,
+ ensure_ascii=False,
+ )
+ acc_tool_calls[call_id] = {
+ "name": part.function_call.name,
+ "input": input_str,
+ }
+ delta_content.append(
+ ToolCallBlock(
+ id=call_id,
+ name=part.function_call.name,
+ input=input_str,
+ ),
+ )
+
+ usage = self._extract_usage(chunk.usage_metadata, start_datetime)
+
+ if delta_content:
+ yield ChatResponse(
+ id=response_id,
+ content=delta_content,
+ is_last=False,
+ usage=usage,
+ )
+
+ final_content: list = []
+ if acc_thinking.thinking:
+ final_content.append(acc_thinking)
+ if acc_text.text:
+ final_content.append(acc_text)
+ for call_id, tc in acc_tool_calls.items():
+ final_content.append(
+ ToolCallBlock(id=call_id, name=tc["name"], input=tc["input"]),
+ )
+
+ yield ChatResponse(
+ id=response_id or uuid.uuid4().hex,
+ content=final_content,
+ is_last=True,
+ usage=usage,
+ )
+
+ def _parse_completion_response(
+ self,
+ start_datetime: datetime,
+ response: GenerateContentResponse,
+ ) -> ChatResponse:
+ """Parse the Gemini non-streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`GenerateContentResponse`):
+ The Gemini generate content response object.
+
+ Returns:
+ `ChatResponse`:
+ A single ``ChatResponse`` with ``is_last=True``.
+ """
+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+ if (
+ response.candidates
+ and response.candidates[0].content
+ and response.candidates[0].content.parts
+ ):
+ for part in response.candidates[0].content.parts:
+ if part.text:
+ if part.thought:
+ content_blocks.append(
+ ThinkingBlock(thinking=part.text),
+ )
+ else:
+ content_blocks.append(TextBlock(text=part.text))
+
+ if part.function_call:
+ keyword_args = part.function_call.args or {}
+ if part.thought_signature:
+ call_id = base64.b64encode(
+ part.thought_signature,
+ ).decode("utf-8")
+ else:
+ call_id = part.function_call.id
+ content_blocks.append(
+ ToolCallBlock(
+ id=call_id,
+ name=part.function_call.name,
+ input=json.dumps(keyword_args, ensure_ascii=False),
+ ),
+ )
+
+ usage = self._extract_usage(response.usage_metadata, start_datetime)
+
+ return ChatResponse(
+ id=getattr(response, "response_id", None) or uuid.uuid4().hex,
+ content=content_blocks,
+ is_last=True,
+ usage=usage,
+ )
+
+ def _extract_usage(
+ self,
+ usage_metadata: Any,
+ start_datetime: datetime,
+ ) -> ChatUsage | None:
+ """Extract ChatUsage from usage_metadata.
+
+ Args:
+ usage_metadata (`Any`):
+ The usage metadata object from a Gemini response.
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+
+ Returns:
+ `ChatUsage | None`:
+ A ``ChatUsage`` object if usage data is available, otherwise
+ ``None``.
+ """
+ if not usage_metadata:
+ return None
+ prompt_tokens = usage_metadata.prompt_token_count
+ total_tokens = usage_metadata.total_token_count
+ if prompt_tokens is not None and total_tokens is not None:
+ return ChatUsage(
+ input_tokens=prompt_tokens,
+ output_tokens=total_tokens - prompt_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=usage_metadata,
+ )
+ return None
+
+ def _format_tools_json_schemas(
+ self,
+ schemas: list[dict[str, Any]],
+ ) -> list[dict[str, Any]]:
+ """Format tool schemas for the Gemini API.
+
+ Args:
+ schemas (`list[dict[str, Any]]`):
+ The raw tool JSON schemas in the standard ``{"function": ...}``
+ format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list containing a single dict with
+ ``"function_declarations"`` key, as required by the Gemini
+ API.
+ """
+ function_declarations = []
+ for schema in schemas:
+ if "function" not in schema:
+ continue
+ func = schema["function"].copy()
+ if "parameters" in func:
+ func["parameters"] = _flatten_json_schema(func["parameters"])
+ function_declarations.append(func)
+ return [{"function_declarations": function_declarations}]
+
+ def _format_tool_choice(
+ self,
+ tool_choice: ToolChoice | None,
+ tools: list[dict] | None,
+ ) -> dict | None:
+ """Format tool_choice parameter for the Gemini API.
+
+ Args:
+ tool_choice (`ToolChoice | None`):
+ The unified tool choice parameter which can be ``"auto"``,
+ ``"none"``, ``"required"``, or a specific function name.
+ tools (`list[dict] | None`):
+ The list of available tools, used for validation when
+ ``tool_choice`` is a specific function name.
+
+ Returns:
+ `dict | None`:
+ The formatted ``tool_config`` dict for the Gemini API, or
+ ``None`` if ``tool_choice`` is ``None``.
+ """
+ self._validate_tool_choice(tool_choice, tools)
+
+ if tool_choice is None:
+ return None
+
+ mode_mapping = {
+ "auto": "AUTO",
+ "none": "NONE",
+ "required": "ANY",
+ }
+ mode = mode_mapping.get(tool_choice)
+ if mode:
+ return {"function_calling_config": {"mode": mode}}
+ return {
+ "function_calling_config": {
+ "mode": "ANY",
+ "allowed_function_names": [tool_choice],
+ },
+ }
diff --git a/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yaml b/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yaml
new file mode 100644
index 000000000..9e1b9020a
--- /dev/null
+++ b/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yaml
@@ -0,0 +1,25 @@
+name: gemini-2.5-flash
+label: Gemini 2.5 Flash
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+ - audio/mp3
+ - audio/wav
+ - video/mp4
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1048576
+output_size: 65536
+
+parameter_overrides:
+ max_tokens:
+ maximum: 65536
diff --git a/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yaml b/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yaml
new file mode 100644
index 000000000..6b975fe54
--- /dev/null
+++ b/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yaml
@@ -0,0 +1,25 @@
+name: gemini-2.5-pro
+label: Gemini 2.5 Pro
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+ - audio/mp3
+ - audio/wav
+ - video/mp4
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1048576
+output_size: 65536
+
+parameter_overrides:
+ max_tokens:
+ maximum: 65536
diff --git a/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yaml b/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yaml
new file mode 100644
index 000000000..954f462e4
--- /dev/null
+++ b/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yaml
@@ -0,0 +1,25 @@
+name: gemini-3-flash-preview
+label: Gemini 3 Flash Preview
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+ - audio/mp3
+ - audio/wav
+ - video/mp4
+ - application/pdf
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1048576
+output_size: 65536
+
+parameter_overrides:
+ max_tokens:
+ maximum: 65536
diff --git a/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yaml b/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yaml
new file mode 100644
index 000000000..4040646c1
--- /dev/null
+++ b/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yaml
@@ -0,0 +1,25 @@
+name: gemini-3.1-pro-preview
+label: Gemini 3.1 Pro Preview
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+ - audio/mp3
+ - audio/wav
+ - video/mp4
+ - application/pdf
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1048576
+output_size: 65536
+
+parameter_overrides:
+ max_tokens:
+ maximum: 65536
diff --git a/src/agentscope/model/_gemini_model.py b/src/agentscope/model/_gemini_model.py
deleted file mode 100644
index 427cd85c9..000000000
--- a/src/agentscope/model/_gemini_model.py
+++ /dev/null
@@ -1,583 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The Google Gemini model in agentscope."""
-import base64
-import copy
-from datetime import datetime
-import json
-from typing import (
- AsyncGenerator,
- Any,
- TYPE_CHECKING,
- AsyncIterator,
- Literal,
- List,
-)
-
-from pydantic import BaseModel
-
-from .._logging import logger
-from ..formatter import FormatterBase, GeminiChatFormatter
-from ..message import ToolCallBlock, TextBlock, ThinkingBlock
-from ._model_usage import ChatUsage
-from ._model_base import ChatModelBase
-from ._model_response import ChatResponse
-from ..tracing import trace_llm
-from ..types import JSONSerializableObject
-from ..tool import ToolChoice
-
-if TYPE_CHECKING:
- from google.genai.types import GenerateContentResponse
-else:
- GenerateContentResponse = "google.genai.types.GenerateContentResponse"
-
-
-def _flatten_json_schema(schema: dict) -> dict:
- """Flatten a JSON schema by resolving all $ref references.
-
- .. note::
- Gemini API does not support `$defs` and `$ref` in JSON schemas.
- This function resolves all `$ref` references by inlining the
- referenced definitions, producing a self-contained schema without
- any references.
-
- Args:
- schema (`dict`):
- The JSON schema that may contain `$defs` and `$ref` references.
-
- Returns:
- `dict`:
- A flattened JSON schema with all references resolved inline.
- """
- # Deep copy to avoid modifying the original schema
- schema = copy.deepcopy(schema)
-
- # Extract $defs if present
- defs = schema.pop("$defs", {})
-
- def _resolve_ref(obj: Any, visited: set | None = None) -> Any:
- """Recursively resolve $ref references in the schema."""
- if visited is None:
- visited = set()
-
- if not isinstance(obj, dict):
- if isinstance(obj, list):
- return [_resolve_ref(item, visited.copy()) for item in obj]
- return obj
-
- # Handle $ref
- if "$ref" in obj:
- ref_path = obj["$ref"]
- # Extract definition name from "#/$defs/DefinitionName"
- if ref_path.startswith("#/$defs/"):
- def_name = ref_path[len("#/$defs/") :]
-
- # Prevent infinite recursion for circular references
- if def_name in visited:
- logger.warning(
- "Circular reference detected for '%s' in tool schema",
- def_name,
- )
- return {
- "type": "object",
- "description": f"(circular: {def_name})",
- }
-
- visited.add(def_name)
-
- if def_name in defs:
- # Recursively resolve any nested refs in the definition
- resolved = _resolve_ref(
- defs[def_name],
- visited.copy(),
- )
- # Merge any additional properties from the original object
- # (excluding $ref itself)
- for key, value in obj.items():
- if key != "$ref":
- resolved[key] = _resolve_ref(value, visited.copy())
- return resolved
-
- # If we can't resolve the ref, return as-is (shouldn't happen)
- return obj
-
- # Recursively process all nested objects
- result = {}
- for key, value in obj.items():
- result[key] = _resolve_ref(value, visited.copy())
-
- return result
-
- return _resolve_ref(schema)
-
-
-class GeminiChatModel(ChatModelBase):
- """The Google Gemini chat model class in agentscope."""
-
- class ThinkingConfig(BaseModel):
- """Configuration for enabling thinking blocks in Gemini responses."""
-
- enable_thinking: bool
- thinking_budget: int = 1024
-
- def __init__(
- self,
- model_name: str,
- api_key: str,
- context_length: int,
- stream: bool = True,
- max_retries: int = 0,
- fallback_model_name: str | None = None,
- formatter: FormatterBase | None = None,
- thinking_config: ThinkingConfig | None = None,
- client_kwargs: dict[str, JSONSerializableObject] | None = None,
- generate_kwargs: dict[str, JSONSerializableObject] | None = None,
- ) -> None:
- """Initialize the Gemini chat model.
-
- Args:
- model_name (`str`):
- The name of the Gemini model to use, e.g. "gemini-2.5-flash".
- api_key (`str`):
- The API key for Google Gemini.
- context_length (`int`):
- The context length of the model, used in context compression.
- stream (`bool`, default `True`):
- Whether to use streaming output or not.
- max_retries (`int`, optional):
- Maximum number of retries on failure. Defaults to 0.
- fallback_model_name (`str | None`, optional):
- Fallback model name to use after all retries fail.
- formatter (`FormatterBase | None`, optional):
- Formatter for message preprocessing.
- thinking_config (`ThinkingConfig | None`, optional):
- Thinking config, supported models are 2.5 Pro, 2.5 Flash, etc.
- client_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments to initialize the Gemini client.
- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments used in Gemini API generation,
- e.g. `temperature`, `seed`.
- """
-
- try:
- from google import genai
- except ImportError as e:
- raise ImportError(
- "Please install gemini Python sdk with "
- "`pip install -q -U google-genai`",
- ) from e
-
- super().__init__(
- model_name=model_name,
- stream=stream,
- context_length=context_length,
- max_retries=max_retries,
- fallback_model_name=fallback_model_name,
- formatter=formatter or GeminiChatFormatter(),
- )
-
- self.client = genai.Client(
- api_key=api_key,
- **(client_kwargs or {}),
- )
- self.thinking_config = thinking_config
- self.generate_kwargs = generate_kwargs or {}
-
- @trace_llm
- async def _call_api(
- self,
- model_name: str,
- messages: list[dict],
- tools: list[dict] | None = None,
- tool_choice: Literal["auto", "none", "required"] | str | None = None,
- **config_kwargs: Any,
- ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
- """Call the Gemini model with the provided arguments.
-
- Args:
- messages (`list[dict[str, Any]]`):
- A list of dictionaries, where `role` and `content` fields are
- required.
- tools (`list[dict] | None`, default `None`):
- The tools JSON schemas that the model can use.
- tool_choice (`Literal["auto", "none", "required"] | str \
- | None`, default `None`):
- Controls which (if any) tool is called by the model.
- Can be "auto", "none", "required", or specific tool name.
- For more details, please refer to
- https://ai.google.dev/gemini-api/docs/function-calling?hl=en&example=meeting#function_calling_modes
- **config_kwargs (`Any`):
- The keyword arguments for Gemini chat completions API.
- """
-
- config: dict = {
- **self.generate_kwargs,
- **config_kwargs,
- }
- if self.thinking_config:
- config["thinking_config"] = {
- "include_thoughts": self.thinking_config.enable_thinking,
- "thinking_budget": self.thinking_config.thinking_budget,
- }
-
- if tools:
- config["tools"] = self._format_tools_json_schemas(tools)
-
- if tool_choice:
- config["tool_config"] = self._format_tool_choice(
- tool_choice,
- tools,
- )
-
- # Prepare the arguments for the Gemini API call
- kwargs: dict = {
- "model": model_name,
- "contents": messages,
- "config": config,
- }
-
- start_datetime = datetime.now()
- if self.stream:
- response = await self.client.aio.models.generate_content_stream(
- **kwargs,
- )
-
- return self._parse_gemini_stream_generation_response(
- start_datetime,
- response,
- )
-
- # non-streaming
- response = await self.client.aio.models.generate_content(
- **kwargs,
- )
-
- parsed_response = self._parse_gemini_generation_response(
- start_datetime,
- response,
- )
-
- return parsed_response
-
- def _extract_usage(
- self,
- usage_metadata: Any,
- start_datetime: datetime,
- ) -> ChatUsage | None:
- """Extract ChatUsage from usage_metadata safely, returning None if
- unavailable or if token counts are None.
-
- Args:
- usage_metadata:
- The usage metadata object from the Gemini response.
- start_datetime (`datetime`):
- The start datetime of the generation.
-
- Returns:
- `ChatUsage | None`:
- A ChatUsage object, or None if data is unavailable.
- """
- if not usage_metadata:
- return None
- prompt_tokens = usage_metadata.prompt_token_count
- total_tokens = usage_metadata.total_token_count
- if prompt_tokens is not None and total_tokens is not None:
- return ChatUsage(
- input_tokens=prompt_tokens,
- output_tokens=total_tokens - prompt_tokens,
- time=(datetime.now() - start_datetime).total_seconds(),
- )
- return None
-
- # pylint: disable=too-many-branches
- async def _parse_gemini_stream_generation_response(
- self,
- start_datetime: datetime,
- response: AsyncIterator[GenerateContentResponse],
- ) -> AsyncGenerator[ChatResponse, None]:
- """Given a Gemini streaming generation response, extract the
- content blocks and usages from it and yield ChatResponse objects.
-
- Args:
- start_datetime (`datetime`):
- The start datetime of the response generation.
- response (`AsyncIterator[GenerateContentResponse]`):
- Gemini GenerateContentResponse async iterator to parse.
-
- Returns:
- `AsyncGenerator[ChatResponse, None]`:
- An async generator that yields ChatResponse objects containing
- the content blocks and usage information for each chunk in the
- streaming response.
- """
-
- # Accumulated state
- acc_text = ""
- acc_thinking = ""
- acc_tool_calls: dict = {} # call_id -> {name, input}
- usage = None
-
- async for chunk in response:
- delta_content: list = []
-
- if (
- chunk.candidates
- and chunk.candidates[0].content
- and chunk.candidates[0].content.parts
- ):
- for part in chunk.candidates[0].content.parts:
- if part.text:
- if part.thought:
- acc_thinking += part.text
- delta_content.append(
- ThinkingBlock(thinking=part.text),
- )
- else:
- acc_text += part.text
- delta_content.append(TextBlock(text=part.text))
-
- if part.function_call:
- keyword_args = part.function_call.args or {}
- if part.thought_signature:
- call_id = base64.b64encode(
- part.thought_signature,
- ).decode("utf-8")
- else:
- call_id = part.function_call.id
-
- input_str = json.dumps(
- keyword_args,
- ensure_ascii=False,
- )
- acc_tool_calls[call_id] = {
- "name": part.function_call.name,
- "input": input_str,
- }
- delta_content.append(
- ToolCallBlock(
- id=call_id,
- name=part.function_call.name,
- input=input_str,
- ),
- )
-
- usage = self._extract_usage(chunk.usage_metadata, start_datetime)
-
- if delta_content:
- yield ChatResponse(
- content=delta_content,
- is_last=False,
- usage=usage,
- )
-
- # Build final accumulated content
- final_content: list = []
- if acc_thinking:
- final_content.append(ThinkingBlock(thinking=acc_thinking))
- if acc_text:
- final_content.append(TextBlock(text=acc_text))
- for call_id, tc in acc_tool_calls.items():
- final_content.append(
- ToolCallBlock(
- id=call_id,
- name=tc["name"],
- input=tc["input"],
- ),
- )
-
- yield ChatResponse(
- content=final_content,
- is_last=True,
- usage=usage,
- )
-
- def _parse_gemini_generation_response(
- self,
- start_datetime: datetime,
- response: GenerateContentResponse,
- ) -> ChatResponse:
- """Given a Gemini chat completion response object, extract the content
- blocks and usages from it.
-
- Args:
- start_datetime (`datetime`):
- The start datetime of the response generation.
- response (`GenerateContentResponse`):
- The Gemini generation response object to parse.
-
- Returns:
- ChatResponse (`ChatResponse`):
- A ChatResponse object containing the content blocks and usage.
- """
- content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
-
- if (
- response.candidates
- and response.candidates[0].content
- and response.candidates[0].content.parts
- ):
- for part in response.candidates[0].content.parts:
- if part.text:
- if part.thought:
- content_blocks.append(
- ThinkingBlock(thinking=part.text),
- )
- else:
- content_blocks.append(
- TextBlock(text=part.text),
- )
-
- if part.function_call:
- keyword_args = part.function_call.args or {}
- if part.thought_signature:
- call_id = base64.b64encode(
- part.thought_signature,
- ).decode("utf-8")
- else:
- call_id = part.function_call.id
-
- content_blocks.append(
- ToolCallBlock(
- id=call_id,
- name=part.function_call.name,
- input=json.dumps(keyword_args, ensure_ascii=False),
- ),
- )
-
- usage = self._extract_usage(response.usage_metadata, start_datetime)
-
- return ChatResponse(
- content=content_blocks,
- is_last=True,
- usage=usage,
- )
-
- def _format_tools_json_schemas(
- self,
- schemas: list[dict[str, Any]],
- ) -> list[dict[str, Any]]:
- """Format the tools JSON schema into required format for Gemini API.
-
- .. note:: Gemini API does not support `$defs` and `$ref` in JSON
- schemas. This function resolves all `$ref` references by inlining the
- referenced definitions, producing a self-contained schema without
- any references.
-
- Args:
- schemas (`dict[str, Any]`):
- The tools JSON schemas.
-
- Returns:
- List[Dict[str, Any]]:
- A list containing a dictionary with the
- "function_declarations" key, which maps to a list of
- function definitions.
-
- Example:
- .. code-block:: python
- :caption: Example tool schemas of Gemini API
-
- # Input JSON schema
- schemas = [
- {
- 'type': 'function',
- 'function': {
- 'name': 'execute_shell_command',
- 'description': 'xxx',
- 'parameters': {
- 'type': 'object',
- 'properties': {
- 'command': {
- 'type': 'string',
- 'description': 'xxx.'
- },
- 'timeout': {
- 'type': 'integer',
- 'default': 300
- }
- },
- 'required': ['command']
- }
- }
- }
- ]
-
- # Output format (Gemini API expected):
- [
- {
- 'function_declarations': [
- {
- 'name': 'execute_shell_command',
- 'description': 'xxx.',
- 'parameters': {
- 'type': 'object',
- 'properties': {
- 'command': {
- 'type': 'string',
- 'description': 'xxx.'
- },
- 'timeout': {
- 'type': 'integer',
- 'default': 300
- }
- },
- 'required': ['command']
- }
- }
- ]
- }
- ]
-
- """
- function_declarations = []
- for schema in schemas:
- if "function" not in schema:
- continue
- func = schema["function"].copy()
- # Flatten the parameters schema to resolve $ref references
- if "parameters" in func:
- func["parameters"] = _flatten_json_schema(func["parameters"])
- function_declarations.append(func)
-
- return [{"function_declarations": function_declarations}]
-
- def _format_tool_choice(
- self,
- tool_choice: ToolChoice | None,
- tools: list[dict] | None,
- ) -> dict | None:
- """Format tool_choice parameter for API compatibility.
-
- Args:
- tool_choice (`ToolChoice | None`):
- The unified tool choice parameter which can be a mode ("auto",
- "none", "required") or a specific function name.
- tools (`list[dict] | None`):
- The list of available tools, used for validation if
- tool_choice is a specific function name.
-
- Returns:
- `dict | None`:
- The formatted tool choice configuration dict, or None if
- tool_choice is None.
- """
- self._validate_tool_choice(tool_choice, tools)
-
- if tool_choice is None:
- return None
-
- mode_mapping = {
- "auto": "AUTO",
- "none": "NONE",
- "required": "ANY",
- }
- mode = mode_mapping.get(tool_choice)
- if mode:
- return {"function_calling_config": {"mode": mode}}
- return {
- "function_calling_config": {
- "mode": "ANY",
- "allowed_function_names": [tool_choice],
- },
- }
diff --git a/src/agentscope/model/_kimi/__init__.py b/src/agentscope/model/_kimi/__init__.py
new file mode 100644
index 000000000..fb5632be1
--- /dev/null
+++ b/src/agentscope/model/_kimi/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The Kimi (Moonshot AI) LLM API modules."""
+
+from ._model import KimiCredential, KimiChatModel
+
+__all__ = [
+ "KimiCredential",
+ "KimiChatModel",
+]
diff --git a/src/agentscope/model/_kimi/_model.py b/src/agentscope/model/_kimi/_model.py
new file mode 100644
index 000000000..1d3991a1c
--- /dev/null
+++ b/src/agentscope/model/_kimi/_model.py
@@ -0,0 +1,375 @@
+# -*- coding: utf-8 -*-
+"""The Kimi (Moonshot AI) chat model implementation."""
+from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import KimiCredential
+from ...formatter import FormatterBase, KimiChatFormatter
+from ...message import ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+from ...tracing import trace_llm
+
+if TYPE_CHECKING:
+ from openai.types.chat import ChatCompletion
+ from openai import AsyncStream
+else:
+ ChatCompletion = Any
+ AsyncStream = Any
+
+
+class KimiChatModel(ChatModelBase):
+ """The Kimi (Moonshot AI) chat model."""
+
+ class Parameters(BaseModel):
+ """The parameters for the Kimi chat model."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description="The maximum number of tokens for the LLM output.",
+ gt=0,
+ )
+
+ temperature: float | None = Field(
+ default=None,
+ title="Temperature",
+ description="The temperature for the LLM output.",
+ ge=0,
+ le=1,
+ )
+
+ top_p: float | None = Field(
+ default=None,
+ title="Top P",
+ description="The top P value for the LLM output.",
+ gt=0,
+ le=1,
+ )
+
+ type: Literal["kimi_chat"] = "kimi_chat"
+ """The type of the chat model."""
+
+ def __init__(
+ self,
+ credential: KimiCredential,
+ model: str,
+ parameters: "KimiChatModel.Parameters | None" = None,
+ stream: bool = True,
+ max_retries: int = 3,
+ context_size: int = 131072,
+ formatter: FormatterBase | None = None,
+ ) -> None:
+ """Initialize the Kimi chat model.
+
+ Args:
+ credential (`KimiCredential`):
+ The Kimi (Moonshot AI) credential used to authenticate API
+ calls.
+ model (`str`):
+ The Kimi model name, e.g. ``moonshot-v1-8k``.
+ parameters (`KimiChatModel.Parameters | None`, defaults to \
+ `None`):
+ The Kimi API parameters. When ``None``, the default
+ parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the Kimi API.
+ context_size (`int`, defaults to `131072`):
+ The model context size used for context compression.
+ formatter (`FormatterBase | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to the format
+ required by the Kimi API. When ``None``, a
+ ``KimiChatFormatter`` instance will be used.
+ """
+ super().__init__(
+ model=model,
+ stream=stream,
+ max_retries=max_retries,
+ context_size=context_size,
+ )
+ self.credential = credential
+ self.parameters = parameters or self.Parameters()
+ self.formatter = formatter or KimiChatFormatter()
+
+ @trace_llm
+ async def _call_api(
+ self,
+ model_name: str,
+ messages: list[Any],
+ tools: list[dict] | None = None,
+ tool_choice: ToolChoice | None = None,
+ **generate_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Call the Kimi chat API (OpenAI-compatible).
+
+ Args:
+ model_name (`str`):
+ The model name to use for this call.
+ messages (`list`):
+ A list of message dicts with ``role`` and ``content`` keys.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas.
+ tool_choice (`ToolChoice | None`, optional):
+ Controls which (if any) tool is called by the model.
+ **generate_kwargs (`Any`):
+ Extra keyword arguments forwarded to the API.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ A ``ChatResponse`` when streaming is disabled, or an async
+ generator of ``ChatResponse`` objects when streaming is
+ enabled.
+ """
+ import openai
+
+ client = openai.AsyncClient(
+ api_key=self.credential.api_key.get_secret_value(),
+ base_url=self.credential.base_url,
+ )
+
+ formatted_messages = await self.formatter.format(messages)
+
+ kwargs: dict[str, Any] = {
+ "model": model_name,
+ "messages": formatted_messages,
+ "stream": self.stream,
+ }
+
+ if self.parameters.max_tokens is not None:
+ kwargs["max_tokens"] = self.parameters.max_tokens
+
+ if self.parameters.temperature is not None:
+ kwargs["temperature"] = self.parameters.temperature
+
+ if self.parameters.top_p is not None:
+ kwargs["top_p"] = self.parameters.top_p
+
+ kwargs.update(generate_kwargs)
+
+ if tools:
+ kwargs["tools"] = tools
+
+ if tool_choice:
+ kwargs["tool_choice"] = self._format_tool_choice(
+ tool_choice,
+ tools,
+ )
+
+ if self.stream:
+ kwargs["stream_options"] = {"include_usage": True}
+
+ start_datetime = datetime.now()
+ response = await client.chat.completions.create(**kwargs)
+
+ if self.stream:
+ return self._parse_stream_response(start_datetime, response)
+
+ return self._parse_completion_response(start_datetime, response)
+
+ async def _parse_stream_response(
+ self,
+ start_datetime: datetime,
+ response: AsyncStream,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the Kimi streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`AsyncStream`):
+ The OpenAI-compatible async stream object.
+
+ Yields:
+ `ChatResponse`:
+ Incremental ``ChatResponse`` objects with ``is_last=False``
+ followed by a final one with ``is_last=True``.
+ """
+ usage = None
+ response_id: str | None = None
+ # All delta should have the same block identifier
+ acc_text = TextBlock(text="")
+ acc_thinking = ThinkingBlock(thinking="")
+ acc_tool_calls: OrderedDict = OrderedDict()
+
+ async with response as stream:
+ async for chunk in stream:
+ if chunk.usage:
+ usage = ChatUsage(
+ input_tokens=chunk.usage.prompt_tokens,
+ output_tokens=chunk.usage.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=chunk.usage,
+ )
+
+ # Capture response_id from the first chunk that carries it
+ response_id = response_id or getattr(chunk, "id", None)
+
+ if not chunk.choices:
+ continue
+
+ choice = chunk.choices[0]
+ delta = choice.delta
+
+ # Kimi thinking models (kimi-k2.6, kimi-k2-thinking) return
+ # reasoning_content before content in the stream.
+ delta_thinking = (
+ getattr(delta, "reasoning_content", None) or ""
+ )
+ if delta_thinking:
+ acc_thinking.thinking += delta_thinking
+ _thinking_kwargs: dict[str, Any] = {
+ "content": [
+ ThinkingBlock(
+ id=acc_thinking.id,
+ thinking=delta_thinking,
+ ),
+ ],
+ "usage": usage,
+ "is_last": False,
+ }
+ if response_id:
+ _thinking_kwargs["id"] = response_id
+ yield ChatResponse(**_thinking_kwargs)
+ continue
+
+ delta_text = getattr(delta, "content", None) or ""
+ acc_text.text += delta_text
+
+ for tool_call in getattr(delta, "tool_calls", None) or []:
+ idx = tool_call.index
+ if idx in acc_tool_calls:
+ if tool_call.function.arguments is not None:
+ acc_tool_calls[idx][
+ "input"
+ ] += tool_call.function.arguments
+ else:
+ acc_tool_calls[idx] = {
+ "id": tool_call.id,
+ "name": tool_call.function.name,
+ "input": tool_call.function.arguments or "",
+ }
+
+ if delta_text:
+ _text_kwargs: dict[str, Any] = {
+ "content": [
+ TextBlock(id=acc_text.id, text=delta_text),
+ ],
+ "usage": usage,
+ "is_last": False,
+ }
+ if response_id:
+ _text_kwargs["id"] = response_id
+ yield ChatResponse(**_text_kwargs)
+
+ final_contents: List[ThinkingBlock | TextBlock | ToolCallBlock] = []
+ if acc_thinking.thinking:
+ final_contents.append(acc_thinking)
+ if acc_text.text:
+ final_contents.append(acc_text)
+ for tc in acc_tool_calls.values():
+ final_contents.append(
+ ToolCallBlock(id=tc["id"], name=tc["name"], input=tc["input"]),
+ )
+
+ _final_kwargs: dict[str, Any] = {
+ "content": final_contents,
+ "usage": usage,
+ "is_last": True,
+ }
+ if response_id:
+ _final_kwargs["id"] = response_id
+ yield ChatResponse(**_final_kwargs)
+
+ def _parse_completion_response(
+ self,
+ start_datetime: datetime,
+ response: ChatCompletion,
+ ) -> ChatResponse:
+ """Parse the Kimi non-streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`ChatCompletion`):
+ The OpenAI-compatible chat completion object.
+
+ Returns:
+ `ChatResponse`:
+ A single ``ChatResponse`` with ``is_last=True``.
+ """
+ content_blocks: List[ThinkingBlock | TextBlock | ToolCallBlock] = []
+
+ if response.choices:
+ choice = response.choices[0]
+ reasoning = getattr(choice.message, "reasoning_content", None)
+ if reasoning:
+ content_blocks.append(ThinkingBlock(thinking=reasoning))
+
+ if choice.message.content:
+ content_blocks.append(TextBlock(text=choice.message.content))
+
+ for tool_call in choice.message.tool_calls or []:
+ content_blocks.append(
+ ToolCallBlock(
+ id=tool_call.id,
+ name=tool_call.function.name,
+ input=tool_call.function.arguments,
+ ),
+ )
+
+ usage = None
+ if response.usage:
+ usage = ChatUsage(
+ input_tokens=response.usage.prompt_tokens,
+ output_tokens=response.usage.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=response.usage,
+ )
+
+ resp_kwargs: dict[str, Any] = {
+ "content": content_blocks,
+ "is_last": True,
+ "usage": usage,
+ }
+ response_id = getattr(response, "id", None)
+ if response_id:
+ resp_kwargs["id"] = response_id
+
+ return ChatResponse(**resp_kwargs)
+
+ def _format_tool_choice(
+ self,
+ tool_choice: ToolChoice | None,
+ tools: list[dict] | None,
+ ) -> str | dict | None:
+ """Format tool_choice parameter for the Kimi API.
+
+ Args:
+ tool_choice (`ToolChoice | None`):
+ The unified tool choice parameter which can be ``"auto"``,
+ ``"none"``, ``"required"``, or a specific function name.
+ tools (`list[dict] | None`):
+ The list of available tools, used for validation when
+ ``tool_choice`` is a specific function name.
+
+ Returns:
+ `str | dict | None`:
+ The formatted tool choice string or configuration dict for
+ the Kimi API, or ``None`` if ``tool_choice`` is ``None``.
+ """
+ self._validate_tool_choice(tool_choice, tools)
+
+ if tool_choice is None:
+ return None
+
+ if tool_choice in ["auto", "none", "required"]:
+ return tool_choice
+
+ return {"type": "function", "function": {"name": tool_choice}}
diff --git a/src/agentscope/model/_kimi/_models/kimi-k2.5.yaml b/src/agentscope/model/_kimi/_models/kimi-k2.5.yaml
new file mode 100644
index 000000000..bc2e2739a
--- /dev/null
+++ b/src/agentscope/model/_kimi/_models/kimi-k2.5.yaml
@@ -0,0 +1,22 @@
+name: kimi-k2.5
+label: Kimi K2.5
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 262144
+output_size: 65536
+
+parameter_overrides:
+ max_tokens:
+ maximum: 65536
diff --git a/src/agentscope/model/_kimi/_models/kimi-k2.6.yaml b/src/agentscope/model/_kimi/_models/kimi-k2.6.yaml
new file mode 100644
index 000000000..53c58bd9e
--- /dev/null
+++ b/src/agentscope/model/_kimi/_models/kimi-k2.6.yaml
@@ -0,0 +1,27 @@
+name: kimi-k2.6
+label: Kimi K2.6
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+ - video/mp4
+ - video/mpeg
+ - video/quicktime
+ - video/avi
+ - video/webm
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 262144
+output_size: 32768
+
+parameter_overrides:
+ max_tokens:
+ maximum: 32768
diff --git a/src/agentscope/model/_kimi/_models/moonshot-v1-128k.yaml b/src/agentscope/model/_kimi/_models/moonshot-v1-128k.yaml
new file mode 100644
index 000000000..7bfa9a9fb
--- /dev/null
+++ b/src/agentscope/model/_kimi/_models/moonshot-v1-128k.yaml
@@ -0,0 +1,16 @@
+name: moonshot-v1-128k
+label: Kimi Moonshot v1 128K
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+
+context_size: 131072
+output_size: 131072
+
+parameter_overrides:
+ max_tokens:
+ maximum: 131072
diff --git a/src/agentscope/model/_kimi/_models/moonshot-v1-32k.yaml b/src/agentscope/model/_kimi/_models/moonshot-v1-32k.yaml
new file mode 100644
index 000000000..b6ffdd288
--- /dev/null
+++ b/src/agentscope/model/_kimi/_models/moonshot-v1-32k.yaml
@@ -0,0 +1,16 @@
+name: moonshot-v1-32k
+label: Kimi Moonshot v1 32K
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+
+context_size: 32768
+output_size: 32768
+
+parameter_overrides:
+ max_tokens:
+ maximum: 32768
diff --git a/src/agentscope/model/_kimi/_models/moonshot-v1-8k.yaml b/src/agentscope/model/_kimi/_models/moonshot-v1-8k.yaml
new file mode 100644
index 000000000..488cd8d74
--- /dev/null
+++ b/src/agentscope/model/_kimi/_models/moonshot-v1-8k.yaml
@@ -0,0 +1,16 @@
+name: moonshot-v1-8k
+label: Kimi Moonshot v1 8K
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+
+context_size: 8192
+output_size: 8192
+
+parameter_overrides:
+ max_tokens:
+ maximum: 8192
diff --git a/src/agentscope/model/_model_card.py b/src/agentscope/model/_model_card.py
new file mode 100644
index 000000000..711ae6654
--- /dev/null
+++ b/src/agentscope/model/_model_card.py
@@ -0,0 +1,150 @@
+# -*- coding: utf-8 -*-
+"""The model card class."""
+import copy
+from datetime import datetime
+from typing import Literal, Self, Type
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class ModelCard(BaseModel):
+ """The model card class."""
+
+ type: Literal["chat_model"] = "chat_model"
+ """The model card type."""
+
+ name: str = Field(description="The name of the model")
+ """The model name."""
+
+ label: str = Field(description="The model label.")
+ """The model label used for frontend rendering."""
+
+ status: Literal["active", "deprecated", "sunset"] = Field(
+ title="Status",
+ description="The model status",
+ )
+ """The model status."""
+
+ deprecated_at: datetime | None = Field(
+ default=None,
+ description="The model deprecation date and time.",
+ title="Deprecation date",
+ )
+ """The model deprecated at."""
+
+ input_types: list[str] = Field(
+ description="The supported model input types.",
+ title="Input types",
+ default=["text/plain"],
+ )
+ """The model supported input types."""
+
+ output_types: list[str] = Field(
+ description="The supported model output types.",
+ title="Output types",
+ default=["text/plain"],
+ )
+ """The model supported output types."""
+
+ context_size: int = Field(
+ title="Context size",
+ description="The context size.",
+ gt=0,
+ )
+ """The model context size."""
+
+ output_size: int = Field(
+ title="Max output tokens",
+ description="The maximum number of tokens.",
+ gt=0,
+ )
+ """The model max output tokens."""
+
+ parameter_schema: dict
+ """The parameters schema, which will be combined with the schema from the
+ DashScopeChatParameter class."""
+
+ parameters_overrides: dict[str, dict]
+ """The parameter overrides, which will be merged into the parameter schema.
+ """
+
+ @classmethod
+ def from_yaml(
+ cls,
+ yaml_path: str,
+ parameter_class: Type[BaseModel],
+ ) -> Self:
+ """Read a model card from a YAML file, and merge the parameter schema
+ with the override parameter schema in the yaml file.
+
+ Args:
+ yaml_path (`str`):
+ Path to the YAML file
+ parameter_class (`Type[BaseModel]`):
+ The parameter class (e.g., DashScopeChatParameters)
+
+ Returns:
+ `list[ModelCard]`:
+ ModelCard instance with merged parameter schema
+ """
+
+ # Load YAML config
+ with open(yaml_path, "r", encoding="utf-8") as file:
+ config = yaml.safe_load(file)
+
+ # Get base schema from parameter class
+ base_schema = parameter_class.model_json_schema()
+ properties = copy.deepcopy(base_schema.get("properties", {}))
+
+ # Auto-filter: remove thinking parameters if not supported
+ output_types = config.get("output_types", [])
+ if "application/x-thinking" not in output_types:
+ properties.pop("thinking_enable", None)
+ properties.pop("thinking_budget", None)
+
+ # Auto-inject: set max_tokens maximum from output_size
+ if "max_tokens" in properties and "output_size" in config:
+ properties["max_tokens"]["maximum"] = config["output_size"]
+
+ # Apply parameter_overrides with simple dict merge
+ overrides = config.get("parameter_overrides", {})
+ for param_name, override in overrides.items():
+ if override is None:
+ # null means remove
+ properties.pop(param_name, None)
+ continue
+
+ if isinstance(override, dict):
+ # Check for hidden flag
+ if override.get("hidden"):
+ properties.pop(param_name, None)
+ continue
+
+ # Simple dict merge: {**base, **override}
+ if param_name in properties:
+ properties[param_name] = {
+ **properties[param_name],
+ **override,
+ }
+
+ # Build final parameter schema
+ final_schema = {
+ "type": "object",
+ "properties": properties,
+ "required": base_schema.get("required", []),
+ }
+
+ # Create ModelCard instance
+ return cls(
+ name=config["name"],
+ label=config["label"],
+ status=config.get("status", "active"),
+ deprecated_at=config.get("deprecated_at"),
+ input_types=config.get("input_types", ["text/plain"]),
+ output_types=config.get("output_types", ["text/plain"]),
+ context_size=config["context_size"],
+ output_size=config["output_size"],
+ parameter_schema=final_schema,
+ parameters_overrides=config.get("parameter_overrides", {}),
+ )
diff --git a/src/agentscope/model/_ollama/__init__.py b/src/agentscope/model/_ollama/__init__.py
new file mode 100644
index 000000000..0e152fc0c
--- /dev/null
+++ b/src/agentscope/model/_ollama/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The Ollama LLM API modules."""
+
+from ._model import OllamaCredential, OllamaChatModel
+
+__all__ = [
+ "OllamaCredential",
+ "OllamaChatModel",
+]
diff --git a/src/agentscope/model/_ollama/_model.py b/src/agentscope/model/_ollama/_model.py
new file mode 100644
index 000000000..bd3dbb43e
--- /dev/null
+++ b/src/agentscope/model/_ollama/_model.py
@@ -0,0 +1,310 @@
+# -*- coding: utf-8 -*-
+"""The Ollama chat model implementation."""
+import json
+import uuid
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import OllamaCredential
+from ...formatter import FormatterBase, OllamaChatFormatter
+from ...message import ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+from ...tracing import trace_llm
+from ..._logging import logger
+
+if TYPE_CHECKING:
+ from ollama._types import ChatResponse as OllamaChatResponse
+else:
+ OllamaChatResponse = Any
+
+
+class OllamaChatModel(ChatModelBase):
+ """The Ollama chat model."""
+
+ class Parameters(BaseModel):
+ """The parameters for the Ollama chat model."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description="The maximum number of tokens for the LLM output.",
+ gt=0,
+ )
+
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description="Whether to enable thinking"
+ " (for models like qwen3, deepseek-r1).",
+ )
+
+ temperature: float | None = Field(
+ default=None,
+ title="Temperature",
+ description="The temperature for the LLM output.",
+ ge=0,
+ le=2,
+ )
+
+ type: Literal["ollama_chat"] = "ollama_chat"
+ """The type of the chat model."""
+
+ def __init__(
+ self,
+ credential: OllamaCredential | None = None,
+ model: str = "",
+ parameters: "OllamaChatModel.Parameters | None" = None,
+ stream: bool = True,
+ max_retries: int = 3,
+ context_size: int = 32768,
+ formatter: FormatterBase | None = None,
+ ) -> None:
+ """Initialize the Ollama chat model.
+
+ Args:
+ credential (`OllamaCredential | None`, defaults to `None`):
+ The Ollama connection settings. When ``None``, a default
+ ``OllamaCredential`` (localhost) will be used.
+ model (`str`):
+ The Ollama model name, e.g. ``llama3.3`` or ``qwen3:14b``.
+ parameters (`OllamaChatModel.Parameters | None`, defaults to \
+ `None`):
+ The Ollama API parameters. When ``None``, the default
+ parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the Ollama API.
+ context_size (`int`, defaults to `32768`):
+ The model context size used for context compression.
+ formatter (`FormatterBase | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to the format
+ required by the Ollama API. When ``None``, an
+ ``OllamaChatFormatter`` instance will be used.
+ """
+ super().__init__(
+ model=model,
+ stream=stream,
+ max_retries=max_retries,
+ context_size=context_size,
+ )
+ self.credential = credential or OllamaCredential()
+ self.parameters = parameters or self.Parameters()
+ self.formatter = formatter or OllamaChatFormatter()
+
+ @trace_llm
+ async def _call_api(
+ self,
+ model_name: str,
+ messages: list[Any],
+ tools: list[dict] | None = None,
+ tool_choice: ToolChoice | None = None,
+ **generate_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Call the Ollama chat API.
+
+ Args:
+ model_name (`str`):
+ The model name to use for this call.
+ messages (`list`):
+ A list of message dicts with ``role`` and ``content`` keys.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas.
+ tool_choice (`ToolChoice | None`, optional):
+ Not supported by Ollama yet (ignored with warning).
+ **generate_kwargs (`Any`):
+ Extra keyword arguments forwarded to the Ollama API.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ A ``ChatResponse`` when streaming is disabled, or an async
+ generator of ``ChatResponse`` objects when streaming is
+ enabled.
+ """
+ import ollama
+
+ client = ollama.AsyncClient(host=self.credential.host)
+
+ formatted_messages = await self.formatter.format(messages)
+
+ kwargs: dict[str, Any] = {
+ "model": model_name,
+ "messages": formatted_messages,
+ "stream": self.stream,
+ }
+
+ options: dict[str, Any] = {}
+ if self.parameters.max_tokens is not None:
+ options["num_predict"] = self.parameters.max_tokens
+ if self.parameters.temperature is not None:
+ options["temperature"] = self.parameters.temperature
+ if options:
+ kwargs["options"] = options
+
+ if self.parameters.thinking_enable:
+ kwargs["think"] = True
+
+ kwargs.update(generate_kwargs)
+
+ if tools:
+ kwargs["tools"] = tools
+
+ if tool_choice:
+ logger.warning("Ollama does not support tool_choice yet, ignored.")
+
+ start_datetime = datetime.now()
+ response = await client.chat(**kwargs)
+
+ if self.stream:
+ return self._parse_stream_response(start_datetime, response)
+
+ return await self._parse_completion_response(start_datetime, response)
+
+ async def _parse_stream_response(
+ self,
+ start_datetime: datetime,
+ response: Any,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the Ollama streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`Any`):
+ The Ollama async stream object.
+
+ Yields:
+ `ChatResponse`:
+ Incremental ``ChatResponse`` objects with ``is_last=False``
+ followed by a final one with ``is_last=True``.
+ """
+ # All delta should have the same block identifier.
+ # Ollama does not return a request id, so we generate one upfront
+ # to keep it stable.
+ response_id = getattr(response, "id", None) or uuid.uuid4().hex
+ acc_text = TextBlock(text="")
+ acc_thinking = ThinkingBlock(thinking="")
+ acc_tool_calls: dict = {}
+ usage = None
+
+ async for chunk in response:
+ delta_content: list = []
+ msg = chunk.message
+
+ chunk_thinking = getattr(msg, "thinking", None)
+ if chunk_thinking:
+ acc_thinking.thinking += chunk_thinking
+ delta_content.append(
+ ThinkingBlock(id=acc_thinking.id, thinking=chunk_thinking),
+ )
+
+ if msg.content:
+ acc_text.text += msg.content
+ delta_content.append(
+ TextBlock(id=acc_text.id, text=msg.content),
+ )
+
+ for idx, tool_call in enumerate(msg.tool_calls or []):
+ function = tool_call.function
+ tool_id = f"{idx}_{function.name}"
+ input_str = json.dumps(function.arguments)
+ acc_tool_calls[tool_id] = {
+ "name": function.name,
+ "input": input_str,
+ }
+ delta_content.append(
+ ToolCallBlock(
+ id=tool_id,
+ name=function.name,
+ input=input_str,
+ ),
+ )
+
+ current_time = (datetime.now() - start_datetime).total_seconds()
+ usage = ChatUsage(
+ input_tokens=getattr(chunk, "prompt_eval_count", 0) or 0,
+ output_tokens=getattr(chunk, "eval_count", 0) or 0,
+ time=current_time,
+ )
+
+ if delta_content:
+ yield ChatResponse(
+ id=response_id,
+ content=delta_content,
+ is_last=False,
+ usage=usage,
+ )
+
+ final_content: list = []
+ if acc_thinking.thinking:
+ final_content.append(acc_thinking)
+ if acc_text.text:
+ final_content.append(acc_text)
+ for tool_id, tc in acc_tool_calls.items():
+ final_content.append(
+ ToolCallBlock(id=tool_id, name=tc["name"], input=tc["input"]),
+ )
+
+ yield ChatResponse(
+ id=response_id,
+ content=final_content,
+ is_last=True,
+ usage=usage,
+ )
+
+ async def _parse_completion_response(
+ self,
+ start_datetime: datetime,
+ response: OllamaChatResponse,
+ ) -> ChatResponse:
+ """Parse the Ollama non-streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`OllamaChatResponse`):
+ The Ollama chat response object.
+
+ Returns:
+ `ChatResponse`:
+ A single ``ChatResponse`` with ``is_last=True``.
+ """
+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+ message_thinking = getattr(response.message, "thinking", None)
+ if message_thinking:
+ content_blocks.append(ThinkingBlock(thinking=message_thinking))
+
+ if response.message.content:
+ content_blocks.append(TextBlock(text=response.message.content))
+
+ for idx, tool_call in enumerate(response.message.tool_calls or []):
+ content_blocks.append(
+ ToolCallBlock(
+ id=f"{idx}_{tool_call.function.name}",
+ name=tool_call.function.name,
+ input=json.dumps(tool_call.function.arguments),
+ ),
+ )
+
+ usage = None
+ prompt_eval = getattr(response, "prompt_eval_count", None)
+ eval_count = getattr(response, "eval_count", None)
+ if prompt_eval is not None and eval_count is not None:
+ usage = ChatUsage(
+ input_tokens=prompt_eval,
+ output_tokens=eval_count,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ )
+
+ return ChatResponse(
+ id=getattr(response, "id", None) or uuid.uuid4().hex,
+ content=content_blocks,
+ is_last=True,
+ usage=usage,
+ )
diff --git a/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yaml b/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yaml
new file mode 100644
index 000000000..4e968ad92
--- /dev/null
+++ b/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yaml
@@ -0,0 +1,17 @@
+name: deepseek-r1:14b
+label: DeepSeek R1 14B
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 131072
+output_size: 8192
+
+parameter_overrides:
+ max_tokens:
+ maximum: 8192
diff --git a/src/agentscope/model/_ollama/_models/llama4.yaml b/src/agentscope/model/_ollama/_models/llama4.yaml
new file mode 100644
index 000000000..502df9207
--- /dev/null
+++ b/src/agentscope/model/_ollama/_models/llama4.yaml
@@ -0,0 +1,22 @@
+name: llama4
+label: Llama 4 Scout
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+
+context_size: 10485760
+output_size: 8192
+
+parameter_overrides:
+ max_tokens:
+ maximum: 8192
+ thinking_enable:
+ hidden: true
diff --git a/src/agentscope/model/_ollama/_models/qwen3-14b.yaml b/src/agentscope/model/_ollama/_models/qwen3-14b.yaml
new file mode 100644
index 000000000..e7fa9836e
--- /dev/null
+++ b/src/agentscope/model/_ollama/_models/qwen3-14b.yaml
@@ -0,0 +1,17 @@
+name: qwen3:14b
+label: Qwen3 14B
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 40960
+output_size: 8192
+
+parameter_overrides:
+ max_tokens:
+ maximum: 8192
diff --git a/src/agentscope/model/_ollama/_models/qwen3.5-9b.yaml b/src/agentscope/model/_ollama/_models/qwen3.5-9b.yaml
new file mode 100644
index 000000000..d517d33c7
--- /dev/null
+++ b/src/agentscope/model/_ollama/_models/qwen3.5-9b.yaml
@@ -0,0 +1,17 @@
+name: qwen3.5
+label: Qwen3.5 9B
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 262144
+output_size: 8192
+
+parameter_overrides:
+ max_tokens:
+ maximum: 8192
diff --git a/src/agentscope/model/_ollama_model.py b/src/agentscope/model/_ollama_model.py
deleted file mode 100644
index c69c0a480..000000000
--- a/src/agentscope/model/_ollama_model.py
+++ /dev/null
@@ -1,352 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Model wrapper for Ollama models."""
-import json
-from datetime import datetime
-from typing import (
- Any,
- TYPE_CHECKING,
- List,
- AsyncGenerator,
- AsyncIterator,
- Literal,
-)
-
-from pydantic import BaseModel
-
-from . import ChatResponse
-from ._model_base import ChatModelBase
-from ._model_usage import ChatUsage
-from .._logging import logger
-from ..formatter import FormatterBase, OllamaChatFormatter
-from ..message import ToolCallBlock, TextBlock, ThinkingBlock
-from ..tracing import trace_llm
-from ..types import JSONSerializableObject
-
-if TYPE_CHECKING:
- from ollama._types import ChatResponse as OllamaChatResponse
-else:
- OllamaChatResponse = "ollama._types.ChatResponse"
-
-
-class OllamaChatModel(ChatModelBase):
- """The Ollama chat model class in agentscope."""
-
- class ThinkingConfig(BaseModel):
- """Configuration for thinking in Ollama chat models."""
-
- enable_thinking: bool
-
- def __init__(
- self,
- model_name: str,
- context_length: int,
- stream: bool = False,
- max_retries: int = 0,
- fallback_model_name: str | None = None,
- formatter: FormatterBase | None = None,
- thinking_config: ThinkingConfig | None = None,
- options: dict = None,
- keep_alive: str = "5m",
- host: str | None = None,
- client_kwargs: dict[str, JSONSerializableObject] | None = None,
- generate_kwargs: dict[str, JSONSerializableObject] | None = None,
- ) -> None:
- """Initialize the Ollama chat model.
-
- Args:
- model_name (`str`):
- The name of the model.
- context_length (`int`):
- The context length of the model, which will be used in
- context compression.
- stream (`bool`, default `True`):
- Streaming mode or not.
- max_retries (`int`, optional):
- Maximum number of retries on failure. Defaults to 0.
- fallback_model_name (`str | None`, optional):
- Fallback model name to use after all retries fail.
- formatter (`FormatterBase | None`, optional):
- Formatter for message preprocessing.
- thinking_config (`ThinkingConfig | None`, default `None`)
- Configuration for thinking, only for models such as qwen3,
- deepseek-r1, etc.
- options (`dict`, default `None`):
- Additional parameters to pass to the Ollama API. These can
- include temperature etc.
- keep_alive (`str`, default `"5m"`):
- Duration to keep the model loaded in memory. The format is a
- number followed by a unit suffix (s for seconds, m for minutes
- , h for hours).
- host (`str | None`, default `None`):
- The host address of the Ollama server. If None, uses the
- default address (typically http://localhost:11434).
- client_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments to initialize the Ollama client.
- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments used in Ollama API generation.
- """
-
- try:
- import ollama
- except ImportError as e:
- raise ImportError(
- "The package ollama is not found. Please install it by "
- 'running command `pip install "ollama>=0.1.7"`',
- ) from e
-
- super().__init__(
- model_name=model_name,
- stream=stream,
- context_length=context_length,
- max_retries=max_retries,
- fallback_model_name=fallback_model_name,
- formatter=formatter or OllamaChatFormatter(),
- )
-
- self.client = ollama.AsyncClient(
- host=host,
- **(client_kwargs or {}),
- )
- self.options = options
- self.keep_alive = keep_alive
- self.thinking_config = thinking_config
- self.generate_kwargs = generate_kwargs or {}
-
- @trace_llm
- async def _call_api(
- self,
- model_name: str,
- messages: list[dict[str, Any]],
- tools: list[dict] | None = None,
- tool_choice: Literal["auto", "none", "required"] | str | None = None,
- **kwargs: Any,
- ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
- """Get the response from Ollama chat completions API by the given
- arguments.
-
- Args:
- model_name (`str`):
- The model name to use for this call.
- messages (`list[dict]`):
- A list of dictionaries, where `role` and `content` fields are
- required, and `name` field is optional.
- tools (`list[dict]`, default `None`):
- The tools JSON schemas that the model can use.
- tool_choice (`Literal["auto", "none", "required"] | str \
- | None`, default `None`):
- Ollama doesn't support `tool_choice` argument yet.
- **kwargs (`Any`):
- The keyword arguments for Ollama chat completions API,
- e.g. `think`etc. Please refer to the Ollama API
- documentation for more details.
-
- Returns:
- `ChatResponse | AsyncGenerator[ChatResponse, None]`:
- The response from the Ollama chat completions API.
- """
-
- kwargs = {
- "model": model_name,
- "messages": messages,
- "stream": self.stream,
- "options": self.options,
- "keep_alive": self.keep_alive,
- **self.generate_kwargs,
- **kwargs,
- }
-
- if self.thinking_config and "think" not in kwargs:
- kwargs["think"] = self.thinking_config.enable_thinking
-
- if tools:
- kwargs["tools"] = self._format_tools_json_schemas(tools)
-
- if tool_choice:
- logger.warning("Ollama does not support tool_choice yet, ignored.")
-
- start_datetime = datetime.now()
- response = await self.client.chat(**kwargs)
-
- if self.stream:
- return self._parse_ollama_stream_completion_response(
- start_datetime,
- response,
- )
-
- parsed_response = await self._parse_ollama_completion_response(
- start_datetime,
- response,
- )
-
- return parsed_response
-
- async def _parse_ollama_stream_completion_response(
- self,
- start_datetime: datetime,
- response: AsyncIterator[OllamaChatResponse],
- ) -> AsyncGenerator[ChatResponse, None]:
- """Given an Ollama streaming completion response, extract the
- content blocks and usages from it and yield ChatResponse objects.
-
- Args:
- start_datetime (`datetime`):
- The start datetime of the response generation.
- response (`AsyncIterator[OllamaChatResponse]`):
- Ollama streaming response async iterator to parse.
-
- Returns:
- AsyncGenerator[ChatResponse, None]:
- An async generator that yields ChatResponse objects containing
- the content blocks and usage information for each chunk in the
- streaming response.
-
- """
- # Accumulated state
- acc_text = ""
- acc_thinking = ""
- acc_tool_calls: dict = {} # tool_id -> {name, input}
- response_id: str | None = None
- usage = None
-
- async for chunk in response:
- delta_content: list = []
- msg = chunk.message
-
- # Handle thinking delta
- if msg.thinking:
- acc_thinking += msg.thinking
- delta_content.append(ThinkingBlock(thinking=msg.thinking))
-
- # Handle text delta
- if msg.content:
- acc_text += msg.content
- delta_content.append(TextBlock(text=msg.content))
-
- # Handle tool calls
- for idx, tool_call in enumerate(msg.tool_calls or []):
- function = tool_call.function
- tool_id = f"{idx}_{function.name}"
- input_str = json.dumps(function.arguments)
- acc_tool_calls[tool_id] = {
- "name": function.name,
- "input": input_str,
- }
- delta_content.append(
- ToolCallBlock(
- id=tool_id,
- name=function.name,
- input=input_str,
- ),
- )
-
- if response_id is None:
- response_id = getattr(chunk, "id", None)
-
- # Calculate usage
- current_time = (datetime.now() - start_datetime).total_seconds()
- usage = ChatUsage(
- input_tokens=getattr(chunk, "prompt_eval_count", 0) or 0,
- output_tokens=getattr(chunk, "eval_count", 0) or 0,
- time=current_time,
- )
-
- if delta_content:
- _kwargs: dict[str, Any] = {
- "content": delta_content,
- "is_last": False,
- "usage": usage,
- }
- if response_id:
- _kwargs["id"] = response_id
- yield ChatResponse(**_kwargs)
-
- # Build final accumulated content
- final_content: list = []
- if acc_thinking:
- final_content.append(ThinkingBlock(thinking=acc_thinking))
- if acc_text:
- final_content.append(TextBlock(text=acc_text))
- for tool_id, tc in acc_tool_calls.items():
- final_content.append(
- ToolCallBlock(
- id=tool_id,
- name=tc["name"],
- input=tc["input"],
- ),
- )
-
- _final_kwargs: dict[str, Any] = {
- "content": final_content,
- "is_last": True,
- "usage": usage,
- }
- if response_id:
- _final_kwargs["id"] = response_id
- yield ChatResponse(**_final_kwargs)
-
- async def _parse_ollama_completion_response(
- self,
- start_datetime: datetime,
- response: OllamaChatResponse,
- ) -> ChatResponse:
- """Given an Ollama chat completion response object, extract the content
- blocks and usages from it.
-
- Args:
- start_datetime (`datetime`):
- The start datetime of the response generation.
- response (`OllamaChatResponse`):
- Ollama OllamaChatResponse object to parse.
-
- Returns:
- `ChatResponse`:
- A ChatResponse object containing the content blocks and usage.
- """
- content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
-
- if response.message.thinking:
- content_blocks.append(
- ThinkingBlock(thinking=response.message.thinking),
- )
-
- if response.message.content:
- content_blocks.append(
- TextBlock(text=response.message.content),
- )
-
- for idx, tool_call in enumerate(response.message.tool_calls or []):
- content_blocks.append(
- ToolCallBlock(
- id=f"{idx}_{tool_call.function.name}",
- name=tool_call.function.name,
- input=json.dumps(tool_call.function.arguments),
- ),
- )
-
- usage = None
- if "prompt_eval_count" in response and "eval_count" in response:
- usage = ChatUsage(
- input_tokens=response.get("prompt_eval_count", 0),
- output_tokens=response.get("eval_count", 0),
- time=(datetime.now() - start_datetime).total_seconds(),
- )
-
- resp_kwargs: dict[str, Any] = {
- "content": content_blocks,
- "is_last": True,
- "usage": usage,
- }
- response_id = getattr(response, "id", None)
- if response_id:
- resp_kwargs["id"] = response_id
-
- return ChatResponse(**resp_kwargs)
-
- def _format_tools_json_schemas(
- self,
- schemas: list[dict[str, Any]],
- ) -> list[dict[str, Any]]:
- """Format the tools JSON schemas to the Ollama format."""
- return schemas
diff --git a/src/agentscope/model/_openai_chat/__init__.py b/src/agentscope/model/_openai_chat/__init__.py
new file mode 100644
index 000000000..c3e39e091
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI Chat Completions API modules."""
+
+from ._model import OpenAIChatModel
+
+__all__ = [
+ "OpenAIChatModel",
+]
diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.py
new file mode 100644
index 000000000..3bcf4709d
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_model.py
@@ -0,0 +1,394 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI Chat Completions model implementation."""
+from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import OpenAICredential
+from ...formatter import FormatterBase, OpenAIChatFormatter
+from ...message import ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+from ...tracing import trace_llm
+
+if TYPE_CHECKING:
+ from openai.types.chat import ChatCompletion
+ from openai import AsyncStream
+else:
+ ChatCompletion = Any
+ AsyncStream = Any
+
+
+class OpenAIChatModel(ChatModelBase):
+ """The OpenAI Chat Completions model."""
+
+ class Parameters(BaseModel):
+ """The parameters for the OpenAI Chat model."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description="The maximum number of tokens for the LLM output.",
+ gt=0,
+ )
+
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description=(
+ "Whether to enable reasoning output. Note: for the OpenAI "
+ "Chat Completions API, reasoning is controlled by model "
+ "selection (e.g. o3, o4-mini) rather than an API parameter."
+ ),
+ )
+
+ temperature: float | None = Field(
+ default=None,
+ title="Temperature",
+ description="The temperature for the LLM output.",
+ ge=0,
+ le=2,
+ )
+
+ top_p: float | None = Field(
+ default=None,
+ title="Top P",
+ description="The top P value for the LLM output.",
+ gt=0,
+ le=1,
+ )
+
+ parallel_tool_calls: bool = Field(
+ default=True,
+ title="Parallel Tool Calls",
+ description="Whether to enable parallel tool calls.",
+ )
+
+ type: Literal["openai_chat"] = "openai_chat"
+ """The type of the chat model."""
+
+ def __init__(
+ self,
+ credential: OpenAICredential,
+ model: str,
+ parameters: "OpenAIChatModel.Parameters | None" = None,
+ stream: bool = True,
+ max_retries: int = 3,
+ context_size: int = 128000,
+ formatter: FormatterBase | None = None,
+ ) -> None:
+ """Initialize the OpenAI chat model.
+
+ Args:
+ credential (`OpenAICredential`):
+ The OpenAI credential used to authenticate API calls.
+ model (`str`):
+ The OpenAI model name, e.g. ``gpt-4.1``.
+ parameters (`OpenAIChatModel.Parameters | None`, defaults to \
+ `None`):
+ The OpenAI Chat API parameters. When ``None``, the default
+ parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the OpenAI API.
+ context_size (`int`, defaults to `128000`):
+ The model context size used for context compression.
+ formatter (`FormatterBase | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to the format
+ required by the OpenAI API. When ``None``, an
+ ``OpenAIChatFormatter`` instance will be used.
+ """
+ super().__init__(
+ model=model,
+ stream=stream,
+ max_retries=max_retries,
+ context_size=context_size,
+ )
+ self.credential = credential
+ self.parameters = parameters or self.Parameters()
+ self.formatter = formatter or OpenAIChatFormatter()
+
+ @trace_llm
+ async def _call_api(
+ self,
+ model_name: str,
+ messages: list[Any],
+ tools: list[dict] | None = None,
+ tool_choice: ToolChoice | None = None,
+ **generate_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Call the OpenAI Chat Completions API.
+
+ Args:
+ model_name (`str`):
+ The model name to use for this call.
+ messages (`list`):
+ A list of message dicts with ``role`` and ``content`` keys.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas.
+ tool_choice (`ToolChoice | None`, optional):
+ Controls which (if any) tool is called by the model.
+ **generate_kwargs (`Any`):
+ Extra keyword arguments forwarded to the API.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ A ``ChatResponse`` when streaming is disabled, or an async
+ generator of ``ChatResponse`` objects when streaming is
+ enabled.
+ """
+ import openai
+
+ client = openai.AsyncClient(
+ api_key=self.credential.api_key.get_secret_value(),
+ organization=self.credential.organization,
+ base_url=self.credential.base_url,
+ )
+
+ formatted_messages = await self.formatter.format(messages)
+
+ kwargs: dict[str, Any] = {
+ "model": model_name,
+ "messages": formatted_messages,
+ "stream": self.stream,
+ }
+
+ if self.parameters.max_tokens is not None:
+ kwargs["max_tokens"] = self.parameters.max_tokens
+
+ if self.parameters.temperature is not None:
+ kwargs["temperature"] = self.parameters.temperature
+
+ if self.parameters.top_p is not None:
+ kwargs["top_p"] = self.parameters.top_p
+
+ kwargs.update(generate_kwargs)
+
+ if tools:
+ kwargs["tools"] = tools
+ if not self.parameters.parallel_tool_calls:
+ kwargs["parallel_tool_calls"] = False
+
+ if tool_choice:
+ kwargs["tool_choice"] = self._format_tool_choice(
+ tool_choice,
+ tools,
+ )
+
+ if self.stream:
+ kwargs["stream_options"] = {"include_usage": True}
+
+ start_datetime = datetime.now()
+ response = await client.chat.completions.create(**kwargs)
+
+ if self.stream:
+ return self._parse_stream_response(start_datetime, response)
+
+ return self._parse_completion_response(start_datetime, response)
+
+ async def _parse_stream_response(
+ self,
+ start_datetime: datetime,
+ response: AsyncStream,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the OpenAI Chat streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`AsyncStream`):
+ The OpenAI async stream object.
+
+ Yields:
+ `ChatResponse`:
+ Incremental ``ChatResponse`` objects with ``is_last=False``
+ followed by a final one with ``is_last=True``.
+ """
+ usage = None
+ response_id: str | None = None
+ # All delta should have the same block identifier
+ acc_text = TextBlock(text="")
+ acc_thinking = ThinkingBlock(thinking="")
+ acc_tool_calls: OrderedDict = OrderedDict()
+
+ async with response as stream:
+ async for chunk in stream:
+ if chunk.usage:
+ usage = ChatUsage(
+ input_tokens=chunk.usage.prompt_tokens,
+ output_tokens=chunk.usage.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=chunk.usage,
+ )
+
+ # Capture response_id from the first chunk that carries it
+ response_id = response_id or getattr(chunk, "id", None)
+
+ if not chunk.choices:
+ continue
+
+ choice = chunk.choices[0]
+ delta = choice.delta
+
+ delta_thinking = getattr(delta, "reasoning_content", None)
+ if not isinstance(delta_thinking, str):
+ delta_thinking = getattr(delta, "reasoning", None)
+ if not isinstance(delta_thinking, str):
+ delta_thinking = ""
+
+ delta_text = getattr(delta, "content", None) or ""
+
+ acc_thinking.thinking += delta_thinking
+ acc_text.text += delta_text
+
+ for tool_call in getattr(delta, "tool_calls", None) or []:
+ idx = tool_call.index
+ if idx in acc_tool_calls:
+ if tool_call.function.arguments is not None:
+ acc_tool_calls[idx][
+ "input"
+ ] += tool_call.function.arguments
+ else:
+ acc_tool_calls[idx] = {
+ "id": tool_call.id,
+ "name": tool_call.function.name,
+ "input": tool_call.function.arguments or "",
+ }
+
+ delta_contents: List[
+ TextBlock | ToolCallBlock | ThinkingBlock
+ ] = []
+ if delta_thinking:
+ delta_contents.append(
+ ThinkingBlock(
+ id=acc_thinking.id,
+ thinking=delta_thinking,
+ ),
+ )
+ if delta_text:
+ delta_contents.append(
+ TextBlock(id=acc_text.id, text=delta_text),
+ )
+
+ if delta_contents:
+ _kwargs: dict[str, Any] = {
+ "content": delta_contents,
+ "usage": usage,
+ "is_last": False,
+ }
+ if response_id:
+ _kwargs["id"] = response_id
+ yield ChatResponse(**_kwargs)
+
+ final_contents: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+ if acc_thinking.thinking:
+ final_contents.append(acc_thinking)
+ if acc_text.text:
+ final_contents.append(acc_text)
+ for tc in acc_tool_calls.values():
+ final_contents.append(
+ ToolCallBlock(id=tc["id"], name=tc["name"], input=tc["input"]),
+ )
+
+ _final_kwargs: dict[str, Any] = {
+ "content": final_contents,
+ "usage": usage,
+ "is_last": True,
+ }
+ if response_id:
+ _final_kwargs["id"] = response_id
+ yield ChatResponse(**_final_kwargs)
+
+ def _parse_completion_response(
+ self,
+ start_datetime: datetime,
+ response: ChatCompletion,
+ ) -> ChatResponse:
+ """Parse the OpenAI Chat non-streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`ChatCompletion`):
+ The OpenAI chat completion object.
+
+ Returns:
+ `ChatResponse`:
+ A single ``ChatResponse`` with ``is_last=True``.
+ """
+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+ if response.choices:
+ choice = response.choices[0]
+ reasoning = getattr(choice.message, "reasoning_content", None)
+ if not isinstance(reasoning, str):
+ reasoning = getattr(choice.message, "reasoning", None)
+ if isinstance(reasoning, str) and reasoning:
+ content_blocks.append(ThinkingBlock(thinking=reasoning))
+
+ if choice.message.content:
+ content_blocks.append(TextBlock(text=choice.message.content))
+
+ for tool_call in choice.message.tool_calls or []:
+ content_blocks.append(
+ ToolCallBlock(
+ id=tool_call.id,
+ name=tool_call.function.name,
+ input=tool_call.function.arguments,
+ ),
+ )
+
+ usage = None
+ if response.usage:
+ usage = ChatUsage(
+ input_tokens=response.usage.prompt_tokens,
+ output_tokens=response.usage.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=response.usage,
+ )
+
+ resp_kwargs: dict[str, Any] = {
+ "content": content_blocks,
+ "is_last": True,
+ "usage": usage,
+ }
+ response_id = getattr(response, "id", None)
+ if response_id:
+ resp_kwargs["id"] = response_id
+
+ return ChatResponse(**resp_kwargs)
+
+ def _format_tool_choice(
+ self,
+ tool_choice: ToolChoice | None,
+ tools: list[dict] | None,
+ ) -> str | dict | None:
+ """Format tool_choice parameter for the OpenAI Chat Completions API.
+
+ Args:
+ tool_choice (`ToolChoice | None`):
+ The unified tool choice parameter which can be ``"auto"``,
+ ``"none"``, ``"required"``, or a specific function name.
+ tools (`list[dict] | None`):
+ The list of available tools, used for validation when
+ ``tool_choice`` is a specific function name.
+
+ Returns:
+ `str | dict | None`:
+ The formatted tool choice string or configuration dict for
+ the OpenAI API, or ``None`` if ``tool_choice`` is ``None``.
+ """
+ self._validate_tool_choice(tool_choice, tools)
+
+ if tool_choice is None:
+ return None
+
+ if tool_choice in ["auto", "none", "required"]:
+ return tool_choice
+
+ return {"type": "function", "function": {"name": tool_choice}}
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-4.1.yaml b/src/agentscope/model/_openai_chat/_models/gpt-4.1.yaml
new file mode 100644
index 000000000..40ebbe051
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-4.1.yaml
@@ -0,0 +1,22 @@
+name: gpt-4.1
+label: GPT-4.1
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+
+context_size: 1047576
+output_size: 32768
+
+parameter_overrides:
+ max_tokens:
+ maximum: 32768
+ thinking_enable:
+ hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-5.4.yaml b/src/agentscope/model/_openai_chat/_models/gpt-5.4.yaml
new file mode 100644
index 000000000..ef1908708
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-5.4.yaml
@@ -0,0 +1,22 @@
+name: gpt-5.4
+label: GPT-5.4
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+
+context_size: 1050000
+output_size: 128000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 128000
+ thinking_enable:
+ hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/o3.yaml b/src/agentscope/model/_openai_chat/_models/o3.yaml
new file mode 100644
index 000000000..7aedacce8
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/o3.yaml
@@ -0,0 +1,21 @@
+name: o3
+label: o3
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 100000
diff --git a/src/agentscope/model/_openai_chat/_models/o4-mini.yaml b/src/agentscope/model/_openai_chat/_models/o4-mini.yaml
new file mode 100644
index 000000000..931013282
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/o4-mini.yaml
@@ -0,0 +1,21 @@
+name: o4-mini
+label: o4-mini
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 100000
diff --git a/src/agentscope/model/_openai_model.py b/src/agentscope/model/_openai_model.py
deleted file mode 100644
index bcf0167da..000000000
--- a/src/agentscope/model/_openai_model.py
+++ /dev/null
@@ -1,540 +0,0 @@
-# -*- coding: utf-8 -*-
-"""OpenAI Chat model class."""
-import warnings
-from datetime import datetime
-from typing import (
- Any,
- TYPE_CHECKING,
- List,
- AsyncGenerator,
- Literal,
-)
-from collections import OrderedDict
-
-from openai.types import ReasoningEffort
-from pydantic import BaseModel
-
-from . import ChatResponse
-from ._model_base import ChatModelBase
-from ._model_usage import ChatUsage
-from ..formatter import FormatterBase, OpenAIChatFormatter
-from ..message import (
- TextBlock,
- ThinkingBlock,
- Base64Source,
- DataBlock,
- ToolCallBlock,
-)
-from ..tool import ToolChoice
-from ..tracing import trace_llm
-from ..types import JSONSerializableObject
-
-if TYPE_CHECKING:
- from openai.types.chat import ChatCompletion
- from openai import AsyncStream
-else:
- ChatCompletion = "openai.types.chat.ChatCompletion"
- AsyncStream = "openai.types.chat.AsyncStream"
-
-
-def _format_audio_data_for_qwen_omni(messages: list[dict]) -> None:
- """Qwen-omni uses OpenAI-compatible API but requires different audio
- data format than OpenAI with "data:;base64," prefix.
- Refer to `Qwen-omni documentation
- <https://bailian.console.aliyun.com/?tab=doc#/doc/?type=model&url=2867839>`_
- for more details.
-
- Args:
- messages (`list[dict]`):
- The list of message dictionaries from OpenAI formatter.
- """
- for msg in messages:
- if isinstance(msg.get("content"), list):
- for block in msg["content"]:
- if (
- isinstance(block, dict)
- and "input_audio" in block
- and isinstance(block["input_audio"].get("data"), str)
- ):
- if not block["input_audio"]["data"].startswith("http"):
- block["input_audio"]["data"] = (
- "data:;base64," + block["input_audio"]["data"]
- )
-
-
-class OpenAIChatModel(ChatModelBase):
- """The OpenAI chat model class."""
-
- class ThinkingConfig(BaseModel):
- """Configuration for reasoning effort levels."""
-
- enable_thinking: bool
- reasoning_effect: ReasoningEffort | None = None
-
- def __init__(
- self,
- model_name: str,
- context_length: int,
- api_key: str | None = None,
- stream: bool = True,
- max_retries: int = 0,
- fallback_model_name: str | None = None,
- formatter: FormatterBase | None = None,
- thinking_config: ThinkingConfig | None = None,
- organization: str = None,
- client_type: Literal["openai", "azure"] = "openai",
- client_kwargs: dict[str, JSONSerializableObject] | None = None,
- generate_kwargs: dict[str, JSONSerializableObject] | None = None,
- ) -> None:
- """Initialize the openai client.
-
- Args:
- model_name (`str`, default `None`):
- The name of the model to use in OpenAI API.
- context_length (`int`):
- The context length of the model, which will be used in
- context compression.
- api_key (`str`, default `None`):
- The API key for OpenAI API. If not specified, it will
- be read from the environment variable `OPENAI_API_KEY`.
- stream (`bool`, default `True`):
- Whether to use streaming output or not.
- max_retries (`int`, optional):
- Maximum number of retries on failure. Defaults to 0.
- fallback_model_name (`str | None`, optional):
- Fallback model name to use after all retries fail.
- formatter (`FormatterBase | None`, optional):
- Formatter for message preprocessing.
- thinking_config (`ThinkingConfig | None`, optional):
- Configuration for reasoning effort levels.
- organization (`str`, default `None`):
- The organization ID for OpenAI API.
- client_type (`Literal["openai", "azure"]`, default `openai`):
- Selects which OpenAI-compatible client to initialize.
- client_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments to initialize the OpenAI client.
- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
- optional):
- The extra keyword arguments used in OpenAI API generation,
- e.g. `temperature`, `seed`.
- """
- self.thinking_config = (
- thinking_config
- or OpenAIChatModel.ThinkingConfig(enable_thinking=False)
- )
-
- super().__init__(
- model_name=model_name,
- stream=stream,
- max_retries=max_retries,
- context_length=context_length,
- fallback_model_name=fallback_model_name,
- formatter=formatter or OpenAIChatFormatter(),
- )
-
- import openai
-
- if client_type not in ("openai", "azure"):
- raise ValueError(
- "Invalid client_type. Supported values: 'openai', 'azure'.",
- )
-
- if client_type == "azure":
- self.client = openai.AsyncAzureOpenAI(
- api_key=api_key,
- organization=organization,
- **(client_kwargs or {}),
- )
- else:
- self.client = openai.AsyncClient(
- api_key=api_key,
- organization=organization,
- **(client_kwargs or {}),
- )
-
- self.generate_kwargs = generate_kwargs or {}
-
- @trace_llm
- async def _call_api(
- self,
- model_name: str,
- messages: list[dict],
- tools: list[dict] | None = None,
- tool_choice: Literal["auto", "none", "required"] | str | None = None,
- **kwargs: Any,
- ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
- """Get the response from OpenAI chat completions API by the given
- arguments.
-
- Args:
- model_name (`str`):
- The model name to use for this call.
- messages (`list[dict]`):
- A list of dictionaries, where `role` and `content` fields are
- required, and `name` field is optional.
- tools (`list[dict]`, default `None`):
- The tools JSON schemas that the model can use.
- tool_choice (`Literal["auto", "none", "required"] | str \
- | None`, default `None`):
- Controls which (if any) tool is called by the model.
- **kwargs (`Any`):
- The keyword arguments for OpenAI chat completions API.
-
- Returns:
- `ChatResponse | AsyncGenerator[ChatResponse, None]`:
- The response from the OpenAI chat completions API.
- """
-
- # checking messages
- if not isinstance(messages, list):
- raise ValueError(
- "OpenAI `messages` field expected type `list`, "
- f"got `{type(messages)}` instead.",
- )
- if not all("role" in msg and "content" in msg for msg in messages):
- raise ValueError(
- "Each message in the 'messages' list must contain a 'role' "
- "and 'content' key for OpenAI API.",
- )
-
- # Qwen-omni requires different base64 audio format from openai
- if "omni" in model_name.lower():
- _format_audio_data_for_qwen_omni(messages)
-
- kwargs = {
- "model": model_name,
- "messages": messages,
- "stream": self.stream,
- **self.generate_kwargs,
- **kwargs,
- }
- if (
- self.thinking_config.enable_thinking
- and self.thinking_config.reasoning_effect
- ):
- kwargs["reasoning_effort"] = self.thinking_config.reasoning_effect
-
- if tools:
- kwargs["tools"] = self._format_tools_json_schemas(tools)
-
- if tool_choice:
- # Handle deprecated "any" option with warning
- if tool_choice == "any":
- warnings.warn(
- '"any" is deprecated and will be removed in a future '
- "version.",
- DeprecationWarning,
- )
- tool_choice = "required"
- kwargs["tool_choice"] = self._format_tool_choice(
- tool_choice,
- tools,
- )
-
- if self.stream:
- kwargs["stream_options"] = {"include_usage": True}
-
- start_datetime = datetime.now()
-
- response = await self.client.chat.completions.create(**kwargs)
-
- if self.stream:
- return self._parse_openai_stream_response(
- start_datetime,
- response,
- )
-
- # Non-streaming response
- parsed_response = self._parse_openai_completion_response(
- start_datetime,
- response,
- )
-
- return parsed_response
-
- async def _parse_openai_stream_response(
- self,
- start_datetime: datetime,
- response: AsyncStream,
- ) -> AsyncGenerator[ChatResponse, None]:
- """Given an OpenAI streaming completion response, extract the content
- blocks and usages from it and yield ChatResponse objects.
-
- Args:
- start_datetime (`datetime`):
- The start datetime of the response generation.
- response (`AsyncStream`):
- OpenAI AsyncStream object to parse.
-
- Returns:
- `AsyncGenerator[ChatResponse, None]`:
- An async generator that yields ChatResponse objects containing
- the content blocks and usage information for each chunk in
- the streaming response.
- """
- usage = None
-
- # Accumulators
- acc_text = ""
- acc_thinking = ""
- acc_audio = ""
- acc_tool_calls = OrderedDict()
-
- async with response as stream:
- async for chunk in stream:
- if chunk.usage:
- usage = ChatUsage(
- input_tokens=chunk.usage.prompt_tokens,
- output_tokens=chunk.usage.completion_tokens,
- time=(datetime.now() - start_datetime).total_seconds(),
- metadata=chunk.usage,
- )
-
- if not chunk.choices:
- continue
-
- choice = chunk.choices[0]
-
- # Extract delta content
- delta_thinking = getattr(
- choice.delta,
- "reasoning_content",
- None,
- )
- if not isinstance(delta_thinking, str):
- delta_thinking = getattr(choice.delta, "reasoning", None)
- if not isinstance(delta_thinking, str):
- delta_thinking = ""
-
- delta_text = getattr(choice.delta, "content", None) or ""
- delta_audio = ""
-
- if isinstance(getattr(choice.delta, "audio", None), dict):
- if "data" in choice.delta.audio:
- delta_audio = choice.delta.audio["data"]
- if "transcript" in choice.delta.audio:
- delta_text += choice.delta.audio["transcript"]
-
- # Accumulate
- acc_thinking += delta_thinking
- acc_text += delta_text
- acc_audio += delta_audio
-
- # Handle tool calls
- for tool_call in (
- getattr(choice.delta, "tool_calls", None) or []
- ):
- if tool_call.index in acc_tool_calls:
- if tool_call.function.arguments is not None:
- acc_tool_calls[tool_call.index][
- "input"
- ] += tool_call.function.arguments
- else:
- acc_tool_calls[tool_call.index] = {
- "id": tool_call.id,
- "name": tool_call.function.name,
- "input": tool_call.function.arguments or "",
- }
-
- # Build delta content blocks
- delta_contents: List[
- TextBlock | ToolCallBlock | ThinkingBlock | DataBlock
- ] = []
-
- if delta_thinking:
- delta_contents.append(
- ThinkingBlock(thinking=delta_thinking),
- )
-
- if delta_audio:
- media_type = self.generate_kwargs.get("audio", {}).get(
- "format",
- "wav",
- )
- delta_contents.append(
- DataBlock(
- source=Base64Source(
- data=delta_audio,
- media_type=f"audio/{media_type}",
- ),
- ),
- )
-
- if delta_text:
- delta_contents.append(
- TextBlock(text=delta_text),
- )
-
- # Yield delta response
- if delta_contents:
- yield ChatResponse(
- content=delta_contents,
- usage=usage,
- is_last=False,
- )
-
- # Build final accumulated content blocks
- final_contents: List[
- TextBlock | ToolCallBlock | ThinkingBlock | DataBlock
- ] = []
-
- if acc_thinking:
- final_contents.append(ThinkingBlock(thinking=acc_thinking))
-
- if acc_audio:
- media_type = self.generate_kwargs.get("audio", {}).get(
- "format",
- "wav",
- )
- final_contents.append(
- DataBlock(
- source=Base64Source(
- data=acc_audio,
- media_type=f"audio/{media_type}",
- ),
- ),
- )
-
- if acc_text:
- final_contents.append(TextBlock(text=acc_text))
-
- for tool_call in acc_tool_calls.values():
- final_contents.append(
- ToolCallBlock(
- id=tool_call["id"],
- name=tool_call["name"],
- input=tool_call["input"],
- ),
- )
-
- # Yield final accumulated response
- yield ChatResponse(
- content=final_contents,
- usage=usage,
- is_last=True,
- )
-
- def _parse_openai_completion_response(
- self,
- start_datetime: datetime,
- response: ChatCompletion,
- ) -> ChatResponse:
- """Given an OpenAI chat completion response object, extract the content
- blocks and usages from it.
-
- Args:
- start_datetime (`datetime`):
- The start datetime of the response generation.
- response (`ChatCompletion`):
- OpenAI ChatCompletion object to parse.
-
- Returns:
- ChatResponse (`ChatResponse`):
- A ChatResponse object containing the content blocks and usage.
- """
- content_blocks: List[
- TextBlock | ToolCallBlock | ThinkingBlock | DataBlock
- ] = []
-
- if response.choices:
- choice = response.choices[0]
- reasoning = getattr(choice.message, "reasoning_content", None)
- if not isinstance(reasoning, str):
- reasoning = getattr(choice.message, "reasoning", None)
- if not isinstance(reasoning, str):
- reasoning = None
-
- if reasoning is not None:
- content_blocks.append(
- ThinkingBlock(thinking=reasoning),
- )
-
- if choice.message.content:
- content_blocks.append(
- TextBlock(text=response.choices[0].message.content),
- )
- if choice.message.audio:
- media_type = self.generate_kwargs.get("audio", {}).get(
- "format",
- "mp3",
- )
- content_blocks.append(
- DataBlock(
- source=Base64Source(
- data=choice.message.audio.data,
- media_type=f"audio/{media_type}",
- ),
- ),
- )
-
- if choice.message.audio.transcript:
- content_blocks.append(
- TextBlock(text=choice.message.audio.transcript),
- )
-
- for tool_call in choice.message.tool_calls or []:
- content_blocks.append(
- ToolCallBlock(
- id=tool_call.id,
- name=tool_call.function.name,
- input=tool_call.function.arguments,
- ),
- )
-
- usage = None
- if response.usage:
- usage = ChatUsage(
- input_tokens=response.usage.prompt_tokens,
- output_tokens=response.usage.completion_tokens,
- time=(datetime.now() - start_datetime).total_seconds(),
- metadata=response.usage,
- )
-
- resp_kwargs: dict[str, Any] = {
- "content": content_blocks,
- "is_last": True,
- "usage": usage,
- }
- response_id = getattr(response, "id", None)
- if response_id:
- resp_kwargs["id"] = response_id
-
- return ChatResponse(**resp_kwargs)
-
- def _format_tools_json_schemas(
- self,
- schemas: list[dict[str, Any]],
- ) -> list[dict[str, Any]]:
- """Format the tools JSON schemas to the OpenAI format."""
- return schemas
-
- def _format_tool_choice(
- self,
- tool_choice: ToolChoice | None,
- tools: list[dict] | None,
- ) -> str | dict | None:
- """Format tool_choice parameter for API compatibility.
-
- Args:
- tool_choice (`ToolChoice | None`):
- The unified tool choice parameter which can be a mode ("auto",
- "none", "required") or a specific function name.
- tools (`list[dict] | None`):
- The list of available tools, used for validation if
- tool_choice is a specific function name.
-
- Returns:
- `dict | None`:
- The formatted tool choice configuration dict, or None if
- tool_choice is None.
- """
- super()._validate_tool_choice(tool_choice, tools)
-
- if tool_choice is None:
- return None
-
- if tool_choice in ["auto", "none", "required"]:
- return tool_choice
-
- return {"type": "function", "function": {"name": tool_choice}}
diff --git a/src/agentscope/model/_openai_response/__init__.py b/src/agentscope/model/_openai_response/__init__.py
new file mode 100644
index 000000000..d6cbb08b5
--- /dev/null
+++ b/src/agentscope/model/_openai_response/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI Responses API modules."""
+
+from ._model import OpenAIResponseModel
+
+__all__ = [
+ "OpenAIResponseModel",
+]
diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.py
new file mode 100644
index 000000000..d7854a1d1
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_model.py
@@ -0,0 +1,435 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI Responses API chat model implementation."""
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, List, TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import OpenAICredential
+from ...formatter import FormatterBase, OpenAIResponseFormatter
+from ...message import ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+from ...tracing import trace_llm
+
+if TYPE_CHECKING:
+ from openai.types.responses import Response
+ from openai.types.responses import ResponseStreamEvent
+ from openai import AsyncStream
+else:
+ Response = Any
+ ResponseStreamEvent = Any
+ AsyncStream = Any
+
+_TOOL_CHOICE_LITERAL_MODES = ["auto", "none", "required"]
+
+
+class OpenAIResponseModel(ChatModelBase):
+ """The OpenAI Responses API chat model.
+
+ Compared with the Chat Completions API, the Responses API provides
+ first-class streaming events for reasoning / thinking, text output
+ and function-call arguments, which makes it a natural fit for models
+ that expose chain-of-thought reasoning (e.g. ``o3``, ``o4-mini``).
+ """
+
+ class Parameters(BaseModel):
+ """The parameters for the OpenAI Response API model."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description="The maximum number of output tokens.",
+ gt=0,
+ )
+
+ reasoning_effort: Literal["low", "medium", "high"] | None = Field(
+ default=None,
+ title="Reasoning Effort",
+ description=(
+ "The reasoning effort level for reasoning models "
+ "(e.g. o3, o4-mini)."
+ ),
+ )
+
+ temperature: float | None = Field(
+ default=None,
+ title="Temperature",
+ description="The temperature for the LLM output.",
+ ge=0,
+ le=2,
+ )
+
+ type: Literal["openai_response"] = "openai_response"
+ """The type of the chat model."""
+
+ def __init__(
+ self,
+ credential: OpenAICredential,
+ model: str,
+ parameters: "OpenAIResponseModel.Parameters | None" = None,
+ stream: bool = True,
+ max_retries: int = 3,
+ context_size: int = 200000,
+ formatter: FormatterBase | None = None,
+ ) -> None:
+ """Initialize the OpenAI Responses API chat model.
+
+ Args:
+ credential (`OpenAICredential`):
+ The OpenAI credential used to authenticate API calls.
+ model (`str`):
+ The OpenAI model name, e.g. ``o3`` or ``o4-mini``.
+ parameters (`OpenAIResponseModel.Parameters | None`, defaults \
+ to `None`):
+ The OpenAI Responses API parameters. When ``None``, the
+ default parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the OpenAI Responses API.
+ context_size (`int`, defaults to `200000`):
+ The model context size used for context compression.
+ formatter (`FormatterBase | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to the format
+ required by the OpenAI Responses API. When ``None``, an
+ ``OpenAIResponseFormatter`` instance will be used.
+ """
+ super().__init__(
+ model=model,
+ stream=stream,
+ max_retries=max_retries,
+ context_size=context_size,
+ )
+ self.credential = credential
+ self.parameters = parameters or self.Parameters()
+ self.formatter = formatter or OpenAIResponseFormatter()
+
+ @trace_llm
+ async def _call_api(
+ self,
+ model_name: str,
+ messages: list[Any],
+ tools: list[dict] | None = None,
+ tool_choice: ToolChoice | None = None,
+ **generate_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Call the OpenAI Responses API.
+
+ Args:
+ model_name (`str`):
+ The model name to use for this call.
+ messages (`list`):
+ A list of input items for the Responses API.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas.
+ tool_choice (`ToolChoice | None`, optional):
+ Controls which (if any) tool is called by the model.
+ **generate_kwargs (`Any`):
+ Extra keyword arguments forwarded to the API.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ A ``ChatResponse`` when streaming is disabled, or an async
+ generator of ``ChatResponse`` objects when streaming is
+ enabled.
+ """
+ import openai
+
+ client = openai.AsyncClient(
+ api_key=self.credential.api_key.get_secret_value(),
+ organization=self.credential.organization,
+ base_url=self.credential.base_url,
+ )
+
+ formatted_messages = await self.formatter.format(messages)
+
+ api_kwargs: dict[str, Any] = {
+ "model": model_name,
+ "input": formatted_messages,
+ "stream": self.stream,
+ }
+
+ if self.parameters.max_tokens is not None:
+ api_kwargs["max_output_tokens"] = self.parameters.max_tokens
+
+ if self.parameters.temperature is not None:
+ api_kwargs["temperature"] = self.parameters.temperature
+
+ if self.parameters.reasoning_effort is not None:
+ api_kwargs["reasoning"] = {
+ "effort": self.parameters.reasoning_effort,
+ }
+
+ api_kwargs.update(generate_kwargs)
+
+ fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
+ if fmt_tools is not None:
+ api_kwargs["tools"] = fmt_tools
+ if fmt_tool_choice is not None:
+ api_kwargs["tool_choice"] = fmt_tool_choice
+
+ start_datetime = datetime.now()
+ response = await client.responses.create(**api_kwargs)
+
+ if self.stream:
+ return self._parse_stream_response(start_datetime, response)
+
+ return self._parse_completion_response(start_datetime, response)
+
+ async def _parse_stream_response(
+ self,
+ start_datetime: datetime,
+ response: "AsyncStream[ResponseStreamEvent]",
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the OpenAI Responses API streaming response.
+
+ Each event yields only the delta content produced by that event so
+ that callers see a true incremental stream, consistent with other
+ model implementations. The final ``response.completed`` event emits
+ an ``is_last=True`` response with the full accumulated state.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`AsyncStream[ResponseStreamEvent]`):
+ The OpenAI Responses API async stream object.
+
+ Yields:
+ `ChatResponse`:
+ Incremental ``ChatResponse`` objects with ``is_last=False``
+ followed by a final one with ``is_last=True``.
+ """
+ usage: ChatUsage | None = None
+ response_id: str | None = None
+ # All delta should have the same block identifier
+ acc_text = TextBlock(text="")
+ acc_thinking = ThinkingBlock(thinking="")
+ tool_calls: dict[str, dict[str, Any]] = {}
+
+ async for event in response:
+ event_type = event.type
+
+ if response_id is None:
+ resp_obj = getattr(event, "response", None)
+ if resp_obj is not None:
+ response_id = getattr(resp_obj, "id", None)
+
+ delta_contents: List[
+ TextBlock | ToolCallBlock | ThinkingBlock
+ ] = []
+
+ if event_type == "response.reasoning_summary_text.delta":
+ # Reasoning summary text is NOT emitted by all models.
+ # As of 2026-05, o1 and o4-mini do not stream reasoning
+ # summary deltas. This handler exists for forward
+ # compatibility with models that do expose it.
+ delta = event.delta
+ acc_thinking.thinking += delta
+ delta_contents.append(
+ ThinkingBlock(id=acc_thinking.id, thinking=delta),
+ )
+
+ elif event_type == "response.output_text.delta":
+ delta = event.delta
+ acc_text.text += delta
+ delta_contents.append(TextBlock(id=acc_text.id, text=delta))
+
+ elif event_type == "response.output_item.added":
+ item = event.item
+ if getattr(item, "type", None) == "function_call":
+ # item.id → fc_xxx (item identifier, needed for
+ # function_call.id in multi-turn history)
+ # item.call_id → call_xxx (needed for
+ # function_call_output.call_id)
+ tool_calls[item.id] = {
+ "id": item.id,
+ "call_id": getattr(item, "call_id", None),
+ "name": getattr(item, "name", ""),
+ "input": "",
+ }
+
+ elif event_type == "response.function_call_arguments.delta":
+ item_id = event.item_id
+ if item_id in tool_calls:
+ tool_calls[item_id]["input"] += event.delta
+
+ elif event_type == "response.completed":
+ resp = event.response
+ if response_id is None:
+ response_id = getattr(resp, "id", None)
+ if resp.usage:
+ usage = ChatUsage(
+ input_tokens=resp.usage.input_tokens,
+ output_tokens=resp.usage.output_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=resp.usage,
+ )
+ # Attach reasoning item IDs from the completed response so the
+ # formatter can echo them back in multi-turn history.
+ # The Responses API requires every function_call item to be
+ # accompanied by its preceding reasoning item (see the
+ # function-calling guide). The reasoning item may have an
+ # empty summary when the model does not expose it (e.g.
+ # o1/o4-mini as of 2026-05).
+ for output_item in getattr(resp, "output", []):
+ if getattr(output_item, "type", None) == "reasoning":
+ reasoning_item_id = getattr(output_item, "id", None)
+ if reasoning_item_id:
+ acc_thinking = ThinkingBlock(
+ id=acc_thinking.id,
+ thinking=acc_thinking.thinking,
+ reasoning_item_id=reasoning_item_id,
+ )
+ # Emit the full accumulated state as the final response
+ final_contents: List[
+ TextBlock | ToolCallBlock | ThinkingBlock
+ ] = []
+ if acc_thinking.thinking or getattr(
+ acc_thinking,
+ "reasoning_item_id",
+ None,
+ ):
+ final_contents.append(acc_thinking)
+ if acc_text.text:
+ final_contents.append(acc_text)
+ for tc in tool_calls.values():
+ final_contents.append(
+ ToolCallBlock(
+ id=tc["id"],
+ call_id=tc.get("call_id"),
+ name=tc["name"],
+ input=tc["input"] or "{}",
+ ),
+ )
+ final_kwargs: dict[str, Any] = {
+ "content": final_contents,
+ "is_last": True,
+ "usage": usage,
+ }
+ if response_id:
+ final_kwargs["id"] = response_id
+ yield ChatResponse(**final_kwargs)
+ return
+
+ # Yield incremental delta for non-terminal events
+ if delta_contents:
+ chat_resp_kwargs: dict[str, Any] = {
+ "content": delta_contents,
+ "is_last": False,
+ "usage": usage,
+ }
+ if response_id:
+ chat_resp_kwargs["id"] = response_id
+ yield ChatResponse(**chat_resp_kwargs)
+
+ def _parse_completion_response(
+ self,
+ start_datetime: datetime,
+ response: "Response",
+ ) -> ChatResponse:
+ """Parse the OpenAI Responses API non-streaming response.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`Response`):
+ The OpenAI Responses API response object.
+
+ Returns:
+ `ChatResponse`:
+ A single ``ChatResponse`` with ``is_last=True``.
+ """
+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+ for item in response.output:
+ item_type = getattr(item, "type", None)
+
+ if item_type == "reasoning":
+ reasoning_item_id = getattr(item, "id", None)
+ combined_summary = " ".join(
+ getattr(s, "text", "")
+ for s in getattr(item, "summary", [])
+ if getattr(s, "text", "")
+ )
+ if combined_summary:
+ content_blocks.append(
+ ThinkingBlock(
+ type="thinking",
+ thinking=combined_summary,
+ reasoning_item_id=reasoning_item_id,
+ ),
+ )
+
+ elif item_type == "message":
+ for part in getattr(item, "content", []):
+ if getattr(part, "type", None) == "output_text":
+ content_blocks.append(
+ TextBlock(type="text", text=part.text),
+ )
+
+ elif item_type == "function_call":
+ content_blocks.append(
+ ToolCallBlock(
+ id=getattr(item, "id", ""),
+ call_id=getattr(item, "call_id", None),
+ name=item.name,
+ input=getattr(item, "arguments", "") or "{}",
+ ),
+ )
+
+ usage = None
+ if response.usage:
+ usage = ChatUsage(
+ input_tokens=response.usage.input_tokens,
+ output_tokens=response.usage.output_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=response.usage,
+ )
+
+ resp_kwargs: dict[str, Any] = {
+ "content": content_blocks,
+ "is_last": True,
+ "usage": usage,
+ }
+ response_id = getattr(response, "id", None)
+ if response_id:
+ resp_kwargs["id"] = response_id
+
+ return ChatResponse(**resp_kwargs)
+
+ def _format_tools(
+ self,
+ tools: list[dict] | None,
+ tool_choice: ToolChoice | None,
+ ) -> tuple[list[dict] | None, str | dict | None]:
+ """Format tools and tool_choice for the Responses API.
+
+ Args:
+ tools (`list[dict] | None`):
+ The raw tool schemas.
+ tool_choice (`ToolChoice | None`):
+ The tool choice configuration.
+
+ Returns:
+ `tuple[list[dict] | None, str | dict | None]`:
+ A tuple of ``(formatted_tools, formatted_tool_choice)``
+ ready for the Responses API.
+ """
+ self._validate_tool_choice(tool_choice, tools)
+
+ fmt_tools = None
+ if tools:
+ fmt_tools = [
+ {"type": "function", **tool["function"]} for tool in tools
+ ]
+
+ if not tool_choice:
+ return fmt_tools, None
+
+ if tool_choice not in _TOOL_CHOICE_LITERAL_MODES:
+ return fmt_tools, {"type": "function", "name": tool_choice}
+
+ return fmt_tools, tool_choice
diff --git a/src/agentscope/model/_openai_response/_models/gpt-5.4.yaml b/src/agentscope/model/_openai_response/_models/gpt-5.4.yaml
new file mode 100644
index 000000000..6d99663b0
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/gpt-5.4.yaml
@@ -0,0 +1,22 @@
+name: gpt-5.4
+label: GPT-5.4 (Responses API)
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+
+context_size: 1050000
+output_size: 128000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 128000
+ reasoning_effort:
+ hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/o3.yaml b/src/agentscope/model/_openai_response/_models/o3.yaml
new file mode 100644
index 000000000..a891bd1be
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/o3.yaml
@@ -0,0 +1,24 @@
+name: o3
+label: o3 (Responses API)
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 100000
+ temperature:
+ hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/o4-mini.yaml b/src/agentscope/model/_openai_response/_models/o4-mini.yaml
new file mode 100644
index 000000000..587223a31
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/o4-mini.yaml
@@ -0,0 +1,24 @@
+name: o4-mini
+label: o4-mini (Responses API)
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 100000
+ temperature:
+ hidden: true
diff --git a/src/agentscope/model/_xai/__init__.py b/src/agentscope/model/_xai/__init__.py
new file mode 100644
index 000000000..a41fe21b2
--- /dev/null
+++ b/src/agentscope/model/_xai/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The xAI LLM API modules."""
+
+from ._model import XAICredential, XAIChatModel
+
+__all__ = [
+ "XAICredential",
+ "XAIChatModel",
+]
diff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.py
new file mode 100644
index 000000000..6fc20d234
--- /dev/null
+++ b/src/agentscope/model/_xai/_model.py
@@ -0,0 +1,416 @@
+# -*- coding: utf-8 -*-
+"""The xAI chat model implementation using the official xai_sdk."""
+from datetime import datetime
+from typing import Any, AsyncGenerator, List, Literal, TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import XAICredential
+from ...formatter._xai_formatter import XAIChatFormatter
+from ...message import (
+ TextBlock,
+ ThinkingBlock,
+ ToolCallBlock,
+)
+from ...tool import ToolChoice
+from ...tracing import trace_llm
+
+if TYPE_CHECKING:
+ from xai_sdk import AsyncClient
+ from xai_sdk.chat import Response, Chunk
+else:
+ AsyncClient = Any
+ Response = Any
+ Chunk = Any
+
+
+class XAIChatModel(ChatModelBase):
+ """The xAI chat model using the official ``xai_sdk`` gRPC client.
+
+ This model provides native access to xAI-specific features such as
+ server-side agentic tools (web search, X search, code execution) and
+ reasoning effort control, which are not available through the
+ OpenAI-compatible REST endpoint.
+ """
+
+ class Parameters(BaseModel):
+ """The parameters for the xAI chat model."""
+
+ max_tokens: int | None = Field(
+ default=None,
+ title="Max Tokens",
+ description="The maximum number of tokens for the LLM output.",
+ gt=0,
+ )
+ """The maximum number of tokens to generate."""
+
+ reasoning_effort: Literal["low", "medium", "high"] | None = Field(
+ default=None,
+ title="Reasoning Effort",
+ description=(
+ "Controls the depth of reasoning for models that support "
+ "extended thinking (e.g. ``grok-3-mini``). Set to "
+ "``'low'``, ``'medium'``, or ``'high'`` to enable reasoning "
+ "with the corresponding effort level. ``None`` disables "
+ "reasoning."
+ ),
+ )
+ """Reasoning effort level for xAI reasoning models."""
+
+ temperature: float | None = Field(
+ default=None,
+ title="Temperature",
+ description="The temperature for the LLM output.",
+ ge=0,
+ le=2,
+ )
+ """The sampling temperature."""
+
+ top_p: float | None = Field(
+ default=None,
+ title="Top P",
+ description="The top-p nucleus sampling value.",
+ gt=0,
+ le=1,
+ )
+ """The top-p sampling parameter."""
+
+ type: Literal["xai_chat"] = "xai_chat"
+ """The type of the chat model."""
+
+ def __init__(
+ self,
+ credential: XAICredential,
+ model: str,
+ parameters: "XAIChatModel.Parameters | None" = None,
+ stream: bool = True,
+ max_retries: int = 3,
+ context_size: int = 131072,
+ formatter: XAIChatFormatter | None = None,
+ ) -> None:
+ """Initialize the xAI chat model.
+
+ Args:
+ credential (`XAICredential`):
+ The xAI credential used to authenticate API calls.
+ model (`str`):
+ The xAI model name, e.g. ``grok-3`` or ``grok-3-mini``.
+ parameters (`XAIChatModel.Parameters | None`, defaults to \
+ `None`):
+ The xAI API parameters. When ``None``, the default
+ parameters will be used.
+ stream (`bool`, defaults to `True`):
+ Whether to enable streaming output.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries for the xAI API.
+ context_size (`int`, defaults to `131072`):
+ The model context size used for context compression.
+ formatter (`XAIChatFormatter | None`, defaults to `None`):
+ The formatter that converts ``Msg`` objects to xai_sdk
+ proto messages. When ``None``, an ``XAIChatFormatter``
+ instance will be used.
+ """
+ super().__init__(
+ model=model,
+ stream=stream,
+ max_retries=max_retries,
+ context_size=context_size,
+ )
+ self.credential = credential
+ self.parameters = parameters or self.Parameters()
+ self.formatter = formatter or XAIChatFormatter()
+
+ @trace_llm
+ async def _call_api(
+ self,
+ model_name: str,
+ messages: list[Any],
+ tools: list[dict] | None = None,
+ tool_choice: ToolChoice | None = None,
+ **generate_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Call the xAI API using the official ``xai_sdk`` gRPC client.
+
+ Args:
+ model_name (`str`):
+ The model name to use for this call.
+ messages (`list`):
+ A list of ``Msg`` objects representing the conversation.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas.
+ tool_choice (`ToolChoice | None`, optional):
+ Controls which (if any) tool is called by the model.
+ **generate_kwargs (`Any`):
+ Extra keyword arguments forwarded to the API.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ A ``ChatResponse`` when streaming is disabled, or an async
+ generator of ``ChatResponse`` objects when streaming is
+ enabled.
+ """
+ from xai_sdk import (
+ AsyncClient as XAIAsyncClient,
+ ) # pylint: disable=import-outside-toplevel
+
+ client = XAIAsyncClient(
+ api_key=self.credential.api_key.get_secret_value(),
+ )
+
+ xai_messages = await self.formatter.format(messages)
+
+ xai_tools = self._convert_tools(tools) if tools else None
+ xai_tool_choice = (
+ self._convert_tool_choice(tool_choice, tools)
+ if tool_choice
+ else None
+ )
+
+ create_kwargs: dict[str, Any] = {"model": model_name}
+ if self.parameters.max_tokens is not None:
+ create_kwargs["max_tokens"] = self.parameters.max_tokens
+ if self.parameters.temperature is not None:
+ create_kwargs["temperature"] = self.parameters.temperature
+ if self.parameters.top_p is not None:
+ create_kwargs["top_p"] = self.parameters.top_p
+ if self.parameters.reasoning_effort is not None:
+ create_kwargs[
+ "reasoning_effort"
+ ] = self.parameters.reasoning_effort
+ if xai_tools:
+ create_kwargs["tools"] = xai_tools
+ if xai_tool_choice is not None:
+ create_kwargs["tool_choice"] = xai_tool_choice
+
+ create_kwargs.update(generate_kwargs)
+
+ chat = client.chat.create(**create_kwargs)
+ for xai_msg in xai_messages:
+ chat.append(xai_msg)
+
+ start_datetime = datetime.now()
+
+ if self.stream:
+ return self._parse_stream_response(start_datetime, chat, client)
+
+ try:
+ response = await chat.sample()
+ finally:
+ await client.close()
+
+ return self._parse_completion_response(start_datetime, response)
+
+ def _convert_tools(self, tools: list[dict]) -> list:
+ """Convert AgentScope tool schemas to ``xai_sdk`` ``Tool`` protos.
+
+ Args:
+ tools (`list[dict]`):
+ A list of tool schemas in OpenAI function-calling format.
+
+ Returns:
+ `list`:
+ A list of ``chat_pb2.Tool`` proto objects.
+ """
+ from xai_sdk.chat import tool
+
+ xai_tools = []
+ for t in tools:
+ if t.get("type") == "function" and "function" in t:
+ fn = t["function"]
+ xai_tools.append(
+ tool(
+ name=fn["name"],
+ description=fn.get("description", ""),
+ parameters=fn.get("parameters", {}),
+ ),
+ )
+ return xai_tools
+
+ def _convert_tool_choice(
+ self,
+ tool_choice: ToolChoice | None,
+ tools: list[dict] | None,
+ ) -> Any:
+ """Convert a ``ToolChoice`` value to an ``xai_sdk`` compatible object.
+
+ Args:
+ tool_choice (`ToolChoice | None`):
+ The unified tool-choice parameter (``"auto"``, ``"none"``,
+ ``"required"``, or a specific function name).
+ tools (`list[dict] | None`):
+ The list of available tools, used for validation.
+
+ Returns:
+ `Any`:
+ The ``xai_sdk``-compatible tool-choice value, or ``None``.
+ """
+ from xai_sdk.chat import ( # pylint: disable=import-outside-toplevel
+ required_tool,
+ )
+
+ self._validate_tool_choice(tool_choice, tools)
+
+ if tool_choice is None:
+ return None
+ if tool_choice in ("auto", "none", "required"):
+ return tool_choice
+ return required_tool(tool_choice)
+
+ async def _parse_stream_response(
+ self,
+ start_datetime: datetime,
+ chat: Any,
+ client: Any,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the xAI streaming response from ``xai_sdk``.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ chat (`Any`):
+ The ``xai_sdk`` chat session object.
+ client (`Any`):
+ The ``xai_sdk.AsyncClient`` instance; closed when the
+ generator is exhausted or abandoned.
+
+ Yields:
+ `ChatResponse`:
+ Incremental ``ChatResponse`` objects with ``is_last=False``
+ followed by a final one with ``is_last=True``.
+ """
+ acc_text = TextBlock(text="")
+ acc_thinking = ThinkingBlock(thinking="")
+ last_response = None
+ response_id: str | None = None
+
+ try:
+ async for response, chunk in chat.stream():
+ if response_id is None:
+ response_id = getattr(response, "id", None) or None
+
+ delta_text: str = chunk.content or ""
+ delta_thinking: str = chunk.reasoning_content or ""
+
+ delta_contents: List[TextBlock | ThinkingBlock] = []
+
+ if delta_thinking:
+ acc_thinking.thinking += delta_thinking
+ delta_contents.append(
+ ThinkingBlock(
+ id=acc_thinking.id,
+ thinking=delta_thinking,
+ ),
+ )
+ if delta_text:
+ acc_text.text += delta_text
+ delta_contents.append(
+ TextBlock(id=acc_text.id, text=delta_text),
+ )
+
+ if delta_contents:
+ _kwargs: dict[str, Any] = {
+ "content": delta_contents,
+ "is_last": False,
+ }
+ if response_id:
+ _kwargs["id"] = response_id
+ yield ChatResponse(**_kwargs)
+
+ last_response = response
+
+ finally:
+ await client.close()
+
+ final_contents: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+ if acc_thinking.thinking:
+ final_contents.append(acc_thinking)
+ if acc_text.text:
+ final_contents.append(acc_text)
+
+ if last_response is not None:
+ for tc in last_response.tool_calls or []:
+ final_contents.append(
+ ToolCallBlock(
+ id=tc.id,
+ name=tc.function.name,
+ input=tc.function.arguments,
+ ),
+ )
+
+ usage = None
+ if last_response is not None and last_response.usage is not None:
+ u = last_response.usage
+ usage = ChatUsage(
+ input_tokens=u.prompt_tokens,
+ output_tokens=u.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=u,
+ )
+
+ final_kwargs: dict[str, Any] = {
+ "content": final_contents,
+ "usage": usage,
+ "is_last": True,
+ }
+ if response_id:
+ final_kwargs["id"] = response_id
+ yield ChatResponse(**final_kwargs)
+
+ def _parse_completion_response(
+ self,
+ start_datetime: datetime,
+ response: Any,
+ ) -> ChatResponse:
+ """Parse the xAI non-streaming response from ``xai_sdk``.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`Any`):
+ The ``xai_sdk`` ``Response`` object.
+
+ Returns:
+ `ChatResponse`:
+ A single ``ChatResponse`` with ``is_last=True``.
+ """
+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+ if response.reasoning_content:
+ content_blocks.append(
+ ThinkingBlock(thinking=response.reasoning_content),
+ )
+ if response.content:
+ content_blocks.append(TextBlock(text=response.content))
+
+ for tc in response.tool_calls or []:
+ content_blocks.append(
+ ToolCallBlock(
+ id=tc.id,
+ name=tc.function.name,
+ input=tc.function.arguments,
+ ),
+ )
+
+ usage = None
+ if response.usage is not None:
+ u = response.usage
+ usage = ChatUsage(
+ input_tokens=u.prompt_tokens,
+ output_tokens=u.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ metadata=u,
+ )
+
+ resp_kwargs: dict[str, Any] = {
+ "content": content_blocks,
+ "is_last": True,
+ "usage": usage,
+ }
+ response_id = getattr(response, "id", None)
+ if response_id:
+ resp_kwargs["id"] = response_id
+
+ return ChatResponse(**resp_kwargs)
diff --git a/src/agentscope/model/_xai/_models/grok-3-mini.yaml b/src/agentscope/model/_xai/_models/grok-3-mini.yaml
new file mode 100644
index 000000000..04f100adc
--- /dev/null
+++ b/src/agentscope/model/_xai/_models/grok-3-mini.yaml
@@ -0,0 +1,17 @@
+name: grok-3-mini
+label: Grok 3 Mini
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 131072
+output_size: 16000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 16000
diff --git a/src/agentscope/model/_xai/_models/grok-4.3.yaml b/src/agentscope/model/_xai/_models/grok-4.3.yaml
new file mode 100644
index 000000000..4b712ef44
--- /dev/null
+++ b/src/agentscope/model/_xai/_models/grok-4.3.yaml
@@ -0,0 +1,19 @@
+name: grok-4.3
+label: Grok 4.3
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1000000
+output_size: 30000
+
+parameter_overrides:
+ max_tokens:
+ maximum: 30000
diff --git a/tests/compress_context_test.py b/tests/compress_context_test.py
index 2edb990c3..eed756a24 100644
--- a/tests/compress_context_test.py
+++ b/tests/compress_context_test.py
@@ -469,7 +469,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
async def test_context_compression(self) -> None:
"""Test the context compression logic."""
- model = MockModel(context_length=100)
+ model = MockModel(context_size=100)
agent = Agent(
name="Friday",
system_prompt="".join(["0" for _ in range(20 * 4)]),
diff --git a/tests/formatter_anthropic_test.py b/tests/formatter_anthropic_test.py
new file mode 100644
index 000000000..88936831c
--- /dev/null
+++ b/tests/formatter_anthropic_test.py
@@ -0,0 +1,532 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for AnthropicChatFormatter and
+AnthropicMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+ AnthropicChatFormatter,
+ AnthropicMultiAgentFormatter,
+)
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ Base64Source,
+ ThinkingBlock,
+)
+from agentscope.message._block import ToolResultState
+
+
+class TestAnthropicFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for Anthropic Chat and MultiAgent formatters."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up shared message fixtures and expected ground-truth dicts."""
+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+
+ # ---------------------------------------------------------------
+ # Message fixtures
+ # (No URL images: Anthropic URL handling downloads from the network)
+ # ---------------------------------------------------------------
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content="What is the capital of France?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Germany?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: AnthropicChatFormatter
+ # - No "name" field.
+ # - Content is always a list of {"type": ..., ...} dicts.
+ # - ToolResultBlock forces role to "user".
+ # - ToolCallBlock "input" is a dict (parsed from JSON string).
+ # ---------------------------------------------------------------
+ self.gt_chat = [
+ {
+ "role": "system",
+ "content": [
+ {"type": "text", "text": "You're a helpful assistant."},
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of France?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Germany?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Germany is Berlin.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Japan?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "call_1",
+ "name": "get_capital",
+ "input": {"country": "Japan"},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "call_1",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: AnthropicMultiAgentFormatter
+ # - System: {"role": "system", "content": [{"type": "text", ...}]}
+ # - Agent messages (is_first=True): wrapped in hist_prompt +
+ # <history>...</history>.
+ # - Agent messages (is_first=False): no wrapping at all.
+ # ---------------------------------------------------------------
+ _hist_prompt = (
+ AnthropicMultiAgentFormatter().conversation_history_prompt
+ )
+
+ _conv_text = (
+ "user: What is the capital of France?\n"
+ "assistant: The capital of France is Paris.\n"
+ "user: What is the capital of Germany?\n"
+ "assistant: The capital of Germany is Berlin.\n"
+ "user: What is the capital of Japan?"
+ )
+
+ # is_first=False: no wrapping (Anthropic only wraps on first group)
+ _gt_trailing_asst_nonfirst = {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "assistant: The capital of Japan is Tokyo.",
+ },
+ ],
+ }
+ # is_first=True: full wrapping with hist_prompt
+ self._gt_trailing_asst_first = {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": (
+ _hist_prompt + "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+
+ self._gt_tool_call = {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "call_1",
+ "name": "get_capital",
+ "input": {"country": "Japan"},
+ },
+ ],
+ }
+ self._gt_tool_result = {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "call_1",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ],
+ }
+
+ self.gt_multiagent = [
+ {
+ "role": "system",
+ "content": [
+ {"type": "text", "text": "You're a helpful assistant."},
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": (
+ _hist_prompt
+ + "<history>\n"
+ + _conv_text
+ + "\n</history>"
+ ),
+ },
+ ],
+ },
+ self._gt_tool_call,
+ self._gt_tool_result,
+ _gt_trailing_asst_nonfirst,
+ ]
+
+ # -------------------------------------------------------------------
+ # AnthropicChatFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_chat_formatter(self) -> None:
+ """Chat formatter produces exact output for various subsets."""
+ fmt = AnthropicChatFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_chat, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_chat[1:], res)
+
+ # Without conversation
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],
+ res,
+ )
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
+
+ async def test_chat_formatter_base64_image(self) -> None:
+ """Base64-encoded image is formatted as Anthropic image source."""
+ fmt = AnthropicChatFormatter()
+ msgs = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(type="text", text="What's in this image?"),
+ DataBlock(
+ source=Base64Source(
+ type="base64",
+ data=self.image_b64,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "What's in this image?"},
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": self.image_b64,
+ },
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
+ async def test_chat_formatter_thinking_preserved(self) -> None:
+ """ThinkingBlock is passed back as a thinking content block."""
+ fmt = AnthropicChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="inner thoughts"),
+ TextBlock(type="text", text="reply"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ thinking_blocks = [
+ b for b in res[0]["content"] if b.get("type") == "thinking"
+ ]
+ self.assertEqual(len(thinking_blocks), 1)
+ self.assertEqual(thinking_blocks[0]["thinking"], "inner thoughts")
+ self.assertEqual(thinking_blocks[0]["signature"], "")
+
+ async def test_chat_formatter_tool_result_role_forced_to_user(
+ self,
+ ) -> None:
+ """Anthropic forces tool_result messages to role='user'."""
+ fmt = AnthropicChatFormatter()
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ tool_results = [
+ m
+ for m in res
+ if any(
+ b.get("type") == "tool_result"
+ for b in (m.get("content") or [])
+ )
+ ]
+ self.assertTrue(len(tool_results) > 0)
+ for tr in tool_results:
+ self.assertEqual(tr["role"], "user")
+
+ async def test_chat_formatter_tool_result_with_image(self) -> None:
+ """Tool result containing an image DataBlock inlines the image in the
+ tool_result content without crashing on TextBlock system-reminders."""
+ fmt = AnthropicChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_img",
+ name="get_chart",
+ input="{}",
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_img",
+ name="get_chart",
+ output=[
+ TextBlock(type="text", text="Here is the chart."),
+ DataBlock(
+ source=Base64Source(
+ data=self.image_b64,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ # There should be 2 messages: the tool_call and the tool_result
+ self.assertEqual(len(res), 2)
+ # Find the tool_result message
+ tool_result_msg = next(
+ m
+ for m in res
+ if any(
+ b.get("type") == "tool_result"
+ for b in (m.get("content") or [])
+ )
+ )
+ self.assertEqual(tool_result_msg["role"], "user")
+ tr_content = next(
+ b
+ for b in tool_result_msg["content"]
+ if b.get("type") == "tool_result"
+ )["content"]
+ # The content should have a text part and an image part
+ types = [b.get("type") for b in tr_content]
+ self.assertIn("text", types)
+ self.assertIn("image", types)
+
+ # -------------------------------------------------------------------
+ # AnthropicMultiAgentFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_multiagent_formatter(self) -> None:
+ """MultiAgent formatter produces exact output for various subsets."""
+ fmt = AnthropicMultiAgentFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_multiagent, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_multiagent[1:], res)
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_multiagent[:2], res)
+
+ # System only
+ res = await fmt.format(self.msgs_system)
+ self.assertListEqual([self.gt_multiagent[0]], res)
+
+ # Conversation only
+ res = await fmt.format(self.msgs_conversation)
+ self.assertListEqual([self.gt_multiagent[1]], res)
+
+ # Tools only — is_first=True for trailing assistant
+ res = await fmt.format(self.msgs_tools)
+ self.assertListEqual(
+ [
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # System + tools (no conversation) — same is_first=True
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [
+ self.gt_multiagent[0],
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
diff --git a/tests/formatter_dashscope_test.py b/tests/formatter_dashscope_test.py
new file mode 100644
index 000000000..31235f139
--- /dev/null
+++ b/tests/formatter_dashscope_test.py
@@ -0,0 +1,600 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for DashScopeChatFormatter and
+DashScopeMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+import shortuuid
+
+from agentscope.formatter import (
+ DashScopeChatFormatter,
+ DashScopeMultiAgentFormatter,
+)
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ Base64Source,
+ URLSource,
+ ThinkingBlock,
+)
+from agentscope.message._block import ToolResultState
+
+
+# A fixed short-uuid used to make promote-to-multimodal tests deterministic.
+_FIXED_ID = "TESTID1234567"
+
+
+class TestDashScopeFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for DashScope Chat and MultiAgent formatters."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up shared message fixtures and expected ground-truth dicts."""
+ # --- URL strings ---
+ # Normalise through URLSource so that pydantic URL normalisation is
+ # applied consistently to both input and expected values.
+ _img_src = URLSource(
+ url="https://example.com/image.png",
+ media_type="image/png",
+ )
+ _aud_src = URLSource(
+ url="https://example.com/audio.mp3",
+ media_type="audio/mpeg",
+ )
+ self.image_url = str(_img_src.url)
+ audio_url = str(_aud_src.url)
+
+ # --- Base64 fixtures ---
+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+ self.image_data_uri = f"data:image/png;base64,{self.image_b64}"
+
+ # ---------------------------------------------------------------
+ # Message fixtures
+ # ---------------------------------------------------------------
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ DataBlock(
+ source=URLSource(
+ url=self.image_url,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content=[
+ TextBlock(
+ type="text",
+ text="What is the capital of Germany?",
+ ),
+ DataBlock(
+ source=URLSource(
+ url=audio_url,
+ media_type="audio/mpeg",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+
+ # Messages with ToolResultBlock must use role="assistant" because the
+ # system-role validator rejects non-text blocks.
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: DashScopeChatFormatter
+ # - System/user/assistant content is always a list of dicts.
+ # - Tool-result content is a plain string.
+ # ---------------------------------------------------------------
+ self.gt_chat = [
+ {
+ "role": "system",
+ "content": [{"text": "You're a helpful assistant."}],
+ },
+ {
+ "role": "user",
+ "content": [
+ {"text": "What is the capital of France?"},
+ {"image": self.image_url},
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [{"text": "The capital of France is Paris."}],
+ },
+ {
+ "role": "user",
+ "content": [
+ {"text": "What is the capital of Germany?"},
+ {"audio": audio_url},
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [{"text": "The capital of Germany is Berlin."}],
+ },
+ {
+ "role": "user",
+ "content": [{"text": "What is the capital of Japan?"}],
+ },
+ {
+ "role": "assistant",
+ "content": [],
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ },
+ {
+ "role": "assistant",
+ "content": [{"text": "The capital of Japan is Tokyo."}],
+ },
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: DashScopeMultiAgentFormatter
+ # - System content is a plain string (via get_text_content()).
+ # - Conversation history is collapsed into a single user message.
+ # ---------------------------------------------------------------
+ _hist_prompt = (
+ DashScopeMultiAgentFormatter().conversation_history_prompt
+ )
+
+ # The trailing assistant message ("The capital of Japan is Tokyo.")
+ # is always converted to a user <history> message by the multiagent
+ # formatter. Whether it carries the full history_prompt prefix
+ # depends on whether an "agent_message" group appeared before it:
+ # * is_first=False (conversation preceded the tool sequence):
+ # only <history>...</history>
+ # * is_first=True (no prior agent_message, e.g. tools-only):
+ # full history_prompt + <history>...</history>
+ _gt_trailing_asst_nonfirst = {
+ "role": "user",
+ "content": [
+ {
+ "text": (
+ "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+ self._gt_trailing_asst_first = {
+ "role": "user",
+ "content": [
+ {
+ "text": (
+ _hist_prompt + "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+
+ self._gt_tool_call = {
+ "role": "assistant",
+ "content": [],
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ }
+ self._gt_tool_result = {
+ "role": "tool",
+ "tool_call_id": "call_1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ }
+
+ self.gt_multiagent = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": (
+ _hist_prompt + "<history>\n"
+ "user: What is the capital of France?"
+ ),
+ },
+ {"image": self.image_url},
+ {
+ "text": (
+ "assistant: The capital of France is Paris.\n"
+ "user: What is the capital of Germany?"
+ ),
+ },
+ {"audio": audio_url},
+ {
+ "text": (
+ "assistant: The capital of Germany is Berlin.\n"
+ "user: What is the capital of Japan?\n"
+ "</history>"
+ ),
+ },
+ ],
+ },
+ self._gt_tool_call,
+ self._gt_tool_result,
+ # Trailing assistant message: is_first=False because conversation
+ # preceded the tool sequence.
+ _gt_trailing_asst_nonfirst,
+ ]
+
+ # -------------------------------------------------------------------
+ # DashScopeChatFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_chat_formatter(self) -> None:
+ """Chat formatter produces exact output for various subsets."""
+ fmt = DashScopeChatFormatter()
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.maxDiff = None
+ self.assertListEqual(self.gt_chat, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_chat[1:], res)
+
+ # Without conversation
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],
+ res,
+ )
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
+
+ async def test_chat_formatter_base64_image(self) -> None:
+ """Base64-encoded image is inlined as a data URI."""
+ fmt = DashScopeChatFormatter()
+ msgs = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(type="text", text="What's in this image?"),
+ DataBlock(
+ source=Base64Source(
+ type="base64",
+ data=self.image_b64,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "content": [
+ {"text": "What's in this image?"},
+ {"image": self.image_data_uri},
+ ],
+ },
+ ],
+ res,
+ )
+
+ async def test_chat_formatter_url_image_in_tool_result(self) -> None:
+ """URL images in tool results are promoted to a follow-up user message.
+
+ The textual part of the tool result contains a system-reminder with a
+ unique identifier; the identifier is mocked to be deterministic.
+ """
+ with patch.object(shortuuid, "uuid", return_value=_FIXED_ID):
+ fmt = DashScopeChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_img",
+ name="get_map",
+ input='{"city": "Tokyo"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_img",
+ name="get_map",
+ output=[
+ TextBlock(
+ type="text",
+ text="Here is the map.",
+ ),
+ DataBlock(
+ source=URLSource(
+ url=self.image_url,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+
+ expected_tool_content = (
+ "Here is the map.\n"
+ f"<system-reminder>A(n) image file is returned "
+ f"and will be presented to you with the identifier "
+ f"[{_FIXED_ID}].</system-reminder>"
+ )
+ self.assertEqual(len(res), 3)
+ self.assertEqual(res[0]["role"], "assistant")
+ self.assertEqual(res[1]["role"], "tool")
+ self.assertEqual(res[1]["content"], expected_tool_content)
+ # The promoted multimodal user message
+ self.assertEqual(res[2]["role"], "user")
+ image_blocks = [
+ b for b in res[2]["content"] if b.get("image") == self.image_url
+ ]
+ self.assertEqual(len(image_blocks), 1)
+
+ async def test_chat_formatter_thinking_dropped_without_flag(self) -> None:
+ """ThinkingBlock is silently dropped when application/x-thinking is
+ absent from input_types."""
+ fmt = DashScopeChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="inner thoughts"),
+ TextBlock(type="text", text="reply"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ self.assertNotIn("reasoning_content", res[0])
+
+ async def test_chat_formatter_thinking_becomes_reasoning_content(
+ self,
+ ) -> None:
+ """ThinkingBlock becomes reasoning_content when application/x-thinking
+ is in input_types."""
+ fmt = DashScopeChatFormatter(
+ input_types=["text/plain", "application/x-thinking"],
+ )
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="inner thoughts"),
+ TextBlock(type="text", text="reply"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ self.assertEqual(res[0]["reasoning_content"], "inner thoughts")
+
+ async def test_chat_formatter_multiple_thinking_blocks_joined(
+ self,
+ ) -> None:
+ """Multiple ThinkingBlocks are joined with a newline into a single
+ reasoning_content field."""
+ fmt = DashScopeChatFormatter(
+ input_types=["text/plain", "application/x-thinking"],
+ )
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="part one"),
+ ThinkingBlock(thinking="part two"),
+ TextBlock(type="text", text="answer"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertIn("part one", res[0]["reasoning_content"])
+ self.assertIn("part two", res[0]["reasoning_content"])
+
+ # -------------------------------------------------------------------
+ # DashScopeMultiAgentFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_multiagent_formatter(self) -> None:
+ """MultiAgent formatter produces exact output for various subsets."""
+ fmt = DashScopeMultiAgentFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_multiagent, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_multiagent[1:], res)
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_multiagent[:2], res)
+
+ # System only
+ res = await fmt.format(self.msgs_system)
+ self.assertListEqual([self.gt_multiagent[0]], res)
+
+ # Conversation only
+ res = await fmt.format(self.msgs_conversation)
+ self.assertListEqual([self.gt_multiagent[1]], res)
+
+ # Tools only — no prior agent_message group, so the trailing assistant
+ # is formatted with is_first=True (includes the full history prompt).
+ res = await fmt.format(self.msgs_tools)
+ self.assertListEqual(
+ [
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # System + tools (no conversation) — same is_first=True for the
+ # trailing assistant message.
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [
+ self.gt_multiagent[0],
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
+
+ async def test_multiagent_formatter_thinking_in_tool_sequence(
+ self,
+ ) -> None:
+ """ThinkingBlocks inside a tool sequence are forwarded as
+ reasoning_content when application/x-thinking is in input_types."""
+ fmt = DashScopeMultiAgentFormatter(
+ input_types=["text/plain", "application/x-thinking"],
+ )
+ tc = ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ )
+ tr = ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[TextBlock(type="text", text="Tokyo")],
+ state=ToolResultState.SUCCESS,
+ )
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[ThinkingBlock(thinking="Need to check"), tc],
+ role="assistant",
+ ),
+ Msg(name="tool", content=[tr], role="assistant"),
+ ]
+ res = await fmt.format(msgs)
+ asst_msgs = [m for m in res if m.get("role") == "assistant"]
+ self.assertTrue(len(asst_msgs) > 0)
+ self.assertEqual(asst_msgs[0]["reasoning_content"], "Need to check")
diff --git a/tests/formatter_deepseek_test.py b/tests/formatter_deepseek_test.py
new file mode 100644
index 000000000..d4f697646
--- /dev/null
+++ b/tests/formatter_deepseek_test.py
@@ -0,0 +1,324 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for DeepSeekChatFormatter and
+DeepSeekMultiAgentFormatter, with exact ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+ DeepSeekChatFormatter,
+ DeepSeekMultiAgentFormatter,
+)
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ ThinkingBlock,
+)
+from agentscope.message._block import ToolResultState
+
+
+class TestDeepSeekFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for DeepSeek Chat and MultiAgent formatters."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up shared fixtures and ground-truth dicts."""
+ _hist_prompt = (
+ DeepSeekMultiAgentFormatter().conversation_history_prompt
+ )
+
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content="What is the capital of France?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Germany?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ # --- Chat formatter ground truth ---
+ # DeepSeek content is a plain string (not a list of blocks).
+ # All assistant messages include `reasoning_content` (empty string if
+ # no ThinkingBlock).
+ self.gt_chat = [
+ {"role": "system", "content": "You're a helpful assistant."},
+ {"role": "user", "content": "What is the capital of France?"},
+ {
+ "role": "assistant",
+ "content": "The capital of France is Paris.",
+ "reasoning_content": "",
+ },
+ {"role": "user", "content": "What is the capital of Germany?"},
+ {
+ "role": "assistant",
+ "content": "The capital of Germany is Berlin.",
+ "reasoning_content": "",
+ },
+ {"role": "user", "content": "What is the capital of Japan?"},
+ {
+ "role": "assistant",
+ "content": None,
+ "reasoning_content": "",
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ },
+ {
+ "role": "assistant",
+ "content": "The capital of Japan is Tokyo.",
+ "reasoning_content": "",
+ },
+ ]
+
+ # --- MultiAgent formatter ground truth ---
+ # System content is a plain string.
+ # History is a plain string (not a list) with <history> tags.
+ # The trailing assistant message (is_first=False) is wrapped in a
+ # minimal <history> block without the full prompt prefix.
+ _gt_trailing_asst_nonfirst = {
+ "role": "user",
+ "content": (
+ "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ }
+ self._gt_trailing_asst_first = {
+ "role": "user",
+ "content": (
+ _hist_prompt + "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ }
+ self._gt_tool_call = {
+ "role": "assistant",
+ "content": None,
+ "reasoning_content": "",
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ }
+ self._gt_tool_result = {
+ "role": "tool",
+ "tool_call_id": "call_1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ }
+
+ self.gt_multiagent = [
+ {"role": "system", "content": "You're a helpful assistant."},
+ {
+ "role": "user",
+ "content": (
+ _hist_prompt + "<history>\n"
+ "user: What is the capital of France?\n"
+ "assistant: The capital of France is Paris.\n"
+ "user: What is the capital of Germany?\n"
+ "assistant: The capital of Germany is Berlin.\n"
+ "user: What is the capital of Japan?\n"
+ "</history>"
+ ),
+ },
+ self._gt_tool_call,
+ self._gt_tool_result,
+ _gt_trailing_asst_nonfirst,
+ ]
+
+ # ------------------------------------------------------------------
+ # DeepSeekChatFormatter tests
+ # ------------------------------------------------------------------
+
+ async def test_chat_formatter(self) -> None:
+ """Chat formatter produces exact output for various subsets."""
+ fmt = DeepSeekChatFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_chat, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_chat[1:], res)
+
+ # Without conversation
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],
+ res,
+ )
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)
+
+ # Empty
+ self.assertListEqual([], await fmt.format([]))
+
+ async def test_chat_formatter_reasoning_content_always_present(
+ self,
+ ) -> None:
+ """Every assistant message always has a reasoning_content field."""
+ fmt = DeepSeekChatFormatter()
+ msgs = [Msg(name="assistant", content="Answer", role="assistant")]
+ res = await fmt.format(msgs)
+ self.assertIn("reasoning_content", res[0])
+ self.assertEqual(res[0]["reasoning_content"], "")
+
+ async def test_chat_formatter_thinking_block(self) -> None:
+ """ThinkingBlock is placed into reasoning_content."""
+ fmt = DeepSeekChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="Let me think..."),
+ TextBlock(type="text", text="Answer"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(res[0]["reasoning_content"], "Let me think...")
+ self.assertEqual(res[0]["content"], "Answer")
+
+ # ------------------------------------------------------------------
+ # DeepSeekMultiAgentFormatter tests
+ # ------------------------------------------------------------------
+
+ async def test_multiagent_formatter(self) -> None:
+ """MultiAgent formatter produces exact output for various subsets."""
+ fmt = DeepSeekMultiAgentFormatter()
+ self.maxDiff = None
+
+ # Full
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_multiagent, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_multiagent[1:], res)
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_multiagent[:2], res)
+
+ # System only
+ res = await fmt.format(self.msgs_system)
+ self.assertListEqual([self.gt_multiagent[0]], res)
+
+ # Conversation only
+ res = await fmt.format(self.msgs_conversation)
+ self.assertListEqual([self.gt_multiagent[1]], res)
+
+ # Tools only (is_first=True for trailing assistant)
+ res = await fmt.format(self.msgs_tools)
+ self.assertListEqual(
+ [
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # System + tools (is_first=True for trailing assistant)
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [
+ self.gt_multiagent[0],
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # Empty
+ self.assertListEqual([], await fmt.format([]))
diff --git a/tests/formatter_gemini_test.py b/tests/formatter_gemini_test.py
new file mode 100644
index 000000000..d2162f0aa
--- /dev/null
+++ b/tests/formatter_gemini_test.py
@@ -0,0 +1,396 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for GeminiChatFormatter and
+GeminiMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+ GeminiChatFormatter,
+ GeminiMultiAgentFormatter,
+)
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ Base64Source,
+ ThinkingBlock,
+)
+from agentscope.message._block import ToolResultState
+
+
+class TestGeminiFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for Gemini Chat and MultiAgent formatters."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up shared message fixtures and expected ground-truth dicts."""
+ image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+
+ # ---------------------------------------------------------------
+ # Message fixtures
+ # (Use base64 images: Gemini URL handling downloads from the network)
+ # ---------------------------------------------------------------
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ DataBlock(
+ source=Base64Source(
+ type="base64",
+ data=image_b64,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Germany?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ _inline_img = {
+ "inline_data": {"data": image_b64, "mime_type": "image/png"},
+ }
+
+ # ---------------------------------------------------------------
+ # Ground truth: GeminiChatFormatter
+ # - System message becomes role="user" (no special system role).
+ # - Assistant messages become role="model".
+ # - Content is in "parts" (not "content") as a list of dicts.
+ # - ToolCallBlock becomes "function_call" part.
+ # - ToolResultBlock becomes a separate role="user" message with
+ # "function_response" part.
+ # ---------------------------------------------------------------
+ self.gt_chat = [
+ {
+ "role": "user",
+ "parts": [{"text": "You're a helpful assistant."}],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {"text": "What is the capital of France?"},
+ _inline_img,
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [{"text": "The capital of France is Paris."}],
+ },
+ {
+ "role": "user",
+ "parts": [{"text": "What is the capital of Germany?"}],
+ },
+ {
+ "role": "model",
+ "parts": [{"text": "The capital of Germany is Berlin."}],
+ },
+ {
+ "role": "user",
+ "parts": [{"text": "What is the capital of Japan?"}],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "function_call": {
+ "id": "call_1",
+ "name": "get_capital",
+ "args": {"country": "Japan"},
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "function_response": {
+ "id": "call_1",
+ "name": "get_capital",
+ "response": {
+ "output": "The capital of Japan is Tokyo.",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [{"text": "The capital of Japan is Tokyo."}],
+ },
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: GeminiMultiAgentFormatter
+ # - System message: role="user" (same as chat formatter).
+ # - Agent messages: collapsed into role="user" with parts list.
+ # - Media blocks interleaved (text flushed before each DataBlock).
+ # - is_first=False still wraps with <history> (no hist_prompt
+ # prefix).
+ # ---------------------------------------------------------------
+ _hist_prompt = GeminiMultiAgentFormatter().conversation_history_prompt
+
+ _gt_trailing_asst_nonfirst = {
+ "role": "user",
+ "parts": [
+ {
+ "text": (
+ "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+ self._gt_trailing_asst_first = {
+ "role": "user",
+ "parts": [
+ {
+ "text": (
+ _hist_prompt + "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+
+ self._gt_tool_call = {
+ "role": "model",
+ "parts": [
+ {
+ "function_call": {
+ "id": "call_1",
+ "name": "get_capital",
+ "args": {"country": "Japan"},
+ },
+ },
+ ],
+ }
+ self._gt_tool_result = {
+ "role": "user",
+ "parts": [
+ {
+ "function_response": {
+ "id": "call_1",
+ "name": "get_capital",
+ "response": {
+ "output": "The capital of Japan is Tokyo.",
+ },
+ },
+ },
+ ],
+ }
+
+ self.gt_multiagent = [
+ {
+ "role": "user",
+ "parts": [{"text": "You're a helpful assistant."}],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": (
+ _hist_prompt + "<history>\n"
+ "user: What is the capital of France?"
+ ),
+ },
+ _inline_img,
+ {
+ "text": (
+ "assistant: The capital of France is Paris.\n"
+ "user: What is the capital of Germany?\n"
+ "assistant: The capital of Germany is Berlin.\n"
+ "user: What is the capital of Japan?\n"
+ "</history>"
+ ),
+ },
+ ],
+ },
+ self._gt_tool_call,
+ self._gt_tool_result,
+ _gt_trailing_asst_nonfirst,
+ ]
+
+ # -------------------------------------------------------------------
+ # GeminiChatFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_chat_formatter(self) -> None:
+ """Chat formatter produces exact output for various subsets."""
+ fmt = GeminiChatFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_chat, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_chat[1:], res)
+
+ # Without conversation
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],
+ res,
+ )
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
+
+ async def test_chat_formatter_thinking_preserved(self) -> None:
+ """ThinkingBlock becomes a part with thought=True in Gemini format."""
+ fmt = GeminiChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="inner thoughts"),
+ TextBlock(type="text", text="reply"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ thinking_parts = [
+ p for p in res[0]["parts"] if p.get("thought") is True
+ ]
+ self.assertEqual(len(thinking_parts), 1)
+ self.assertEqual(thinking_parts[0]["text"], "inner thoughts")
+
+ # -------------------------------------------------------------------
+ # GeminiMultiAgentFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_multiagent_formatter(self) -> None:
+ """MultiAgent formatter produces exact output for various subsets."""
+ fmt = GeminiMultiAgentFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_multiagent, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_multiagent[1:], res)
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_multiagent[:2], res)
+
+ # System only
+ res = await fmt.format(self.msgs_system)
+ self.assertListEqual([self.gt_multiagent[0]], res)
+
+ # Conversation only
+ res = await fmt.format(self.msgs_conversation)
+ self.assertListEqual([self.gt_multiagent[1]], res)
+
+ # Tools only — is_first=True for trailing assistant
+ res = await fmt.format(self.msgs_tools)
+ self.assertListEqual(
+ [
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # System + tools — same is_first=True for trailing assistant
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [
+ self.gt_multiagent[0],
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
diff --git a/tests/formatter_kimi_test.py b/tests/formatter_kimi_test.py
new file mode 100644
index 000000000..7045088db
--- /dev/null
+++ b/tests/formatter_kimi_test.py
@@ -0,0 +1,485 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for KimiChatFormatter and
+KimiMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+ KimiChatFormatter,
+ KimiMultiAgentFormatter,
+)
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ Base64Source,
+ URLSource,
+ ThinkingBlock,
+)
+from agentscope.message._block import ToolResultState
+
+
+_FIXED_ID = "TESTID1234567"
+
+
+class TestKimiFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for Kimi Chat and MultiAgent formatters."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up shared message fixtures and expected ground-truth dicts."""
+ _img_src = URLSource(
+ url="https://example.com/image.png",
+ media_type="image/png",
+ )
+ image_url = str(_img_src.url)
+
+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+ self.image_data_uri = f"data:image/png;base64,{self.image_b64}"
+
+ # ---------------------------------------------------------------
+ # Message fixtures (no audio to avoid downloads)
+ # ---------------------------------------------------------------
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ DataBlock(
+ source=URLSource(
+ url=image_url,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Germany?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: KimiChatFormatter
+ # - Same as OpenAI except ALL assistant messages have an extra
+ # "reasoning_content" field (empty string when no ThinkingBlock).
+ # ---------------------------------------------------------------
+ self.gt_chat = [
+ {
+ "role": "system",
+ "name": "system",
+ "content": [
+ {"type": "text", "text": "You're a helpful assistant."},
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {"type": "text", "text": "What is the capital of France?"},
+ {
+ "type": "image_url",
+ "image_url": {"url": image_url},
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ "reasoning_content": "",
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Germany?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Germany is Berlin.",
+ },
+ ],
+ "reasoning_content": "",
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {"type": "text", "text": "What is the capital of Japan?"},
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": None,
+ "reasoning_content": "",
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {"type": "text", "text": "The capital of Japan is Tokyo."},
+ ],
+ "reasoning_content": "",
+ },
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: KimiMultiAgentFormatter
+ # - Same as OpenAI MultiAgent, but tool-sequence assistant messages
+ # carry "reasoning_content": "".
+ # ---------------------------------------------------------------
+ _hist_prompt = KimiMultiAgentFormatter().conversation_history_prompt
+
+ _conv_text = (
+ "user: What is the capital of France?\n"
+ "assistant: The capital of France is Paris.\n"
+ "user: What is the capital of Germany?\n"
+ "assistant: The capital of Germany is Berlin.\n"
+ "user: What is the capital of Japan?"
+ )
+
+ _gt_trailing_asst_nonfirst = {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": (
+ "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+ self._gt_trailing_asst_first = {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": (
+ _hist_prompt + "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+
+ self._gt_tool_call = {
+ "role": "assistant",
+ "name": "assistant",
+ "content": None,
+ "reasoning_content": "",
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ }
+ self._gt_tool_result = {
+ "role": "tool",
+ "tool_call_id": "call_1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ }
+
+ self.gt_multiagent = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": (
+ _hist_prompt
+ + "<history>\n"
+ + _conv_text
+ + "\n</history>"
+ ),
+ },
+ {
+ "type": "image_url",
+ "image_url": {"url": image_url},
+ },
+ ],
+ },
+ self._gt_tool_call,
+ self._gt_tool_result,
+ _gt_trailing_asst_nonfirst,
+ ]
+
+ # -------------------------------------------------------------------
+ # KimiChatFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_chat_formatter(self) -> None:
+ """Chat formatter produces exact output for various subsets."""
+ fmt = KimiChatFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_chat, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_chat[1:], res)
+
+ # Without conversation
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],
+ res,
+ )
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
+
+ async def test_chat_formatter_thinking_to_reasoning_content(
+ self,
+ ) -> None:
+ """ThinkingBlock becomes reasoning_content in Kimi (Preserved
+ Thinking)."""
+ fmt = KimiChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="inner thoughts"),
+ TextBlock(type="text", text="reply"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ self.assertEqual(res[0]["reasoning_content"], "inner thoughts")
+ self.assertEqual(
+ res[0]["content"],
+ [{"type": "text", "text": "reply"}],
+ )
+
+ async def test_chat_formatter_assistant_always_has_reasoning_content(
+ self,
+ ) -> None:
+ """All assistant messages always have reasoning_content (even when
+ empty)."""
+ fmt = KimiChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content="Hello!",
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ self.assertIn("reasoning_content", res[0])
+ self.assertEqual(res[0]["reasoning_content"], "")
+
+ async def test_chat_formatter_base64_image(self) -> None:
+ """Base64-encoded image is inlined as a data URI."""
+ fmt = KimiChatFormatter()
+ msgs = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(type="text", text="What's in this image?"),
+ DataBlock(
+ source=Base64Source(
+ type="base64",
+ data=self.image_b64,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {"type": "text", "text": "What's in this image?"},
+ {
+ "type": "image_url",
+ "image_url": {"url": self.image_data_uri},
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
+ # -------------------------------------------------------------------
+ # KimiMultiAgentFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_multiagent_formatter(self) -> None:
+ """MultiAgent formatter produces exact output for various subsets."""
+ fmt = KimiMultiAgentFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_multiagent, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_multiagent[1:], res)
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_multiagent[:2], res)
+
+ # System only
+ res = await fmt.format(self.msgs_system)
+ self.assertListEqual([self.gt_multiagent[0]], res)
+
+ # Conversation only
+ res = await fmt.format(self.msgs_conversation)
+ self.assertListEqual([self.gt_multiagent[1]], res)
+
+ # Tools only — is_first=True for trailing assistant
+ res = await fmt.format(self.msgs_tools)
+ self.assertListEqual(
+ [
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # System + tools — same is_first=True
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [
+ self.gt_multiagent[0],
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
diff --git a/tests/formatter_ollama_test.py b/tests/formatter_ollama_test.py
new file mode 100644
index 000000000..9567ac09e
--- /dev/null
+++ b/tests/formatter_ollama_test.py
@@ -0,0 +1,309 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for OllamaChatFormatter and
+OllamaMultiAgentFormatter, with exact ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.formatter import OllamaChatFormatter, OllamaMultiAgentFormatter
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ Base64Source,
+)
+from agentscope.message._block import ToolResultState
+
+
+class TestOllamaFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for Ollama Chat and MultiAgent formatters."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up shared fixtures and ground-truth dicts."""
+ _hist_prompt = OllamaMultiAgentFormatter().conversation_history_prompt
+
+ # Base64 image fixture
+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content="What is the capital of France?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Germany?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ # --- Chat formatter ground truth ---
+ # Ollama content is always a plain string.
+ # Tool calls use dict arguments (not JSON string).
+ self.gt_chat = [
+ {"role": "system", "content": "You're a helpful assistant."},
+ {"role": "user", "content": "What is the capital of France?"},
+ {
+ "role": "assistant",
+ "content": "The capital of France is Paris.",
+ },
+ {"role": "user", "content": "What is the capital of Germany?"},
+ {
+ "role": "assistant",
+ "content": "The capital of Germany is Berlin.",
+ },
+ {"role": "user", "content": "What is the capital of Japan?"},
+ {
+ "role": "assistant",
+ "content": "",
+ "tool_calls": [
+ {
+ "function": {
+ "name": "get_capital",
+ "arguments": {"country": "Japan"},
+ },
+ },
+ ],
+ },
+ {"role": "tool", "content": "The capital of Japan is Tokyo."},
+ {"role": "assistant", "content": "The capital of Japan is Tokyo."},
+ ]
+
+ # --- MultiAgent formatter ground truth ---
+ # System content is a plain string.
+ # History is a plain string with format "name:\ntext" per message.
+ # For is_first=False, there are NO <history> tags (only in
+ # is_first=True).
+ _conv_text = (
+ "user:\nWhat is the capital of France?\n"
+ "assistant:\nThe capital of France is Paris.\n"
+ "user:\nWhat is the capital of Germany?\n"
+ "assistant:\nThe capital of Germany is Berlin.\n"
+ "user:\nWhat is the capital of Japan?"
+ )
+ _gt_trailing_asst_nonfirst = {
+ "role": "user",
+ "content": "assistant:\nThe capital of Japan is Tokyo.",
+ }
+ self._gt_trailing_asst_first = {
+ "role": "user",
+ "content": (
+ _hist_prompt + "<history>\n"
+ "assistant:\nThe capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ }
+ self._gt_tool_call = {
+ "role": "assistant",
+ "content": "",
+ "tool_calls": [
+ {
+ "function": {
+ "name": "get_capital",
+ "arguments": {"country": "Japan"},
+ },
+ },
+ ],
+ }
+ self._gt_tool_result = {
+ "role": "tool",
+ "content": "The capital of Japan is Tokyo.",
+ }
+
+ self.gt_multiagent = [
+ {"role": "system", "content": "You're a helpful assistant."},
+ {
+ "role": "user",
+ "content": (
+ _hist_prompt + "<history>\n" + _conv_text + "\n</history>"
+ ),
+ },
+ self._gt_tool_call,
+ self._gt_tool_result,
+ _gt_trailing_asst_nonfirst,
+ ]
+
+ # ------------------------------------------------------------------
+ # OllamaChatFormatter tests
+ # ------------------------------------------------------------------
+
+ async def test_chat_formatter(self) -> None:
+ """Chat formatter produces exact output for various subsets."""
+ fmt = OllamaChatFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_chat, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_chat[1:], res)
+
+ # Without conversation
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],
+ res,
+ )
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)
+
+ # Empty
+ self.assertListEqual([], await fmt.format([]))
+
+ async def test_chat_formatter_tool_call_arguments_are_dict(self) -> None:
+ """Ollama requires tool call arguments as a dict, not a JSON string."""
+ fmt = OllamaChatFormatter()
+ tc = ToolCallBlock(id="c1", name="search", input='{"q": "weather"}')
+ res = await fmt.format(
+ [Msg(name="assistant", content=[tc], role="assistant")],
+ )
+ args = res[0]["tool_calls"][0]["function"]["arguments"]
+ self.assertIsInstance(args, dict)
+ self.assertEqual(args["q"], "weather")
+
+ async def test_chat_formatter_base64_image(self) -> None:
+ """Base64 image is placed in the 'images' list as a raw base64
+ string."""
+ fmt = OllamaChatFormatter()
+ msgs = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(type="text", text="What is this?"),
+ DataBlock(
+ source=Base64Source(
+ type="base64",
+ data=self.image_b64,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ self.assertEqual(res[0]["content"], "What is this?")
+ self.assertEqual(res[0]["images"], [self.image_b64])
+
+ # ------------------------------------------------------------------
+ # OllamaMultiAgentFormatter tests
+ # ------------------------------------------------------------------
+
+ async def test_multiagent_formatter(self) -> None:
+ """MultiAgent formatter produces exact output for various subsets."""
+ fmt = OllamaMultiAgentFormatter()
+ self.maxDiff = None
+
+ # Full
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_multiagent, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_multiagent[1:], res)
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_multiagent[:2], res)
+
+ # System only
+ res = await fmt.format(self.msgs_system)
+ self.assertListEqual([self.gt_multiagent[0]], res)
+
+ # Conversation only
+ res = await fmt.format(self.msgs_conversation)
+ self.assertListEqual([self.gt_multiagent[1]], res)
+
+ # Tools only (is_first=True for trailing assistant)
+ res = await fmt.format(self.msgs_tools)
+ self.assertListEqual(
+ [
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # System + tools (is_first=True for trailing assistant)
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [
+ self.gt_multiagent[0],
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # Empty
+ self.assertListEqual([], await fmt.format([]))
diff --git a/tests/formatter_openai_chat_test.py b/tests/formatter_openai_chat_test.py
new file mode 100644
index 000000000..266a540e9
--- /dev/null
+++ b/tests/formatter_openai_chat_test.py
@@ -0,0 +1,532 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for OpenAIChatFormatter and
+OpenAIMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+import shortuuid
+
+from agentscope.formatter import (
+ OpenAIChatFormatter,
+ OpenAIMultiAgentFormatter,
+)
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ Base64Source,
+ URLSource,
+ ThinkingBlock,
+)
+from agentscope.message._block import ToolResultState
+
+
+_FIXED_ID = "TESTID1234567"
+
+
+class TestOpenAIFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for OpenAI Chat and MultiAgent formatters."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up shared message fixtures and expected ground-truth dicts."""
+ _img_src = URLSource(
+ url="https://example.com/image.png",
+ media_type="image/png",
+ )
+ self.image_url = str(_img_src.url)
+
+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+ self.image_data_uri = f"data:image/png;base64,{self.image_b64}"
+
+ # ---------------------------------------------------------------
+ # Message fixtures
+ # (No audio in conversation: OpenAI URL audio requires a download)
+ # ---------------------------------------------------------------
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ DataBlock(
+ source=URLSource(
+ url=self.image_url,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Germany?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: OpenAIChatFormatter
+ # - Content is a list of {"type": ..., ...} dicts.
+ # - Tool-result content is a plain string.
+ # - Messages have a "name" field.
+ # ---------------------------------------------------------------
+ self.gt_chat = [
+ {
+ "role": "system",
+ "name": "system",
+ "content": [
+ {"type": "text", "text": "You're a helpful assistant."},
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {"type": "text", "text": "What is the capital of France?"},
+ {
+ "type": "image_url",
+ "image_url": {"url": self.image_url},
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Germany?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Germany is Berlin.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {"type": "text", "text": "What is the capital of Japan?"},
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: OpenAIMultiAgentFormatter
+ # - System content is a plain string.
+ # - All conversation text is collapsed into a single text block,
+ # with media blocks appended after.
+ # - No "name" field on the user wrapper message.
+ # ---------------------------------------------------------------
+ _hist_prompt = OpenAIMultiAgentFormatter().conversation_history_prompt
+
+ _conv_text = (
+ "user: What is the capital of France?\n"
+ "assistant: The capital of France is Paris.\n"
+ "user: What is the capital of Germany?\n"
+ "assistant: The capital of Germany is Berlin.\n"
+ "user: What is the capital of Japan?"
+ )
+
+ _gt_trailing_asst_nonfirst = {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": (
+ "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+ self._gt_trailing_asst_first = {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": (
+ _hist_prompt + "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+
+ self._gt_tool_call = {
+ "role": "assistant",
+ "name": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "call_1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ }
+ self._gt_tool_result = {
+ "role": "tool",
+ "tool_call_id": "call_1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ }
+
+ self.gt_multiagent = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": (
+ _hist_prompt
+ + "<history>\n"
+ + _conv_text
+ + "\n</history>"
+ ),
+ },
+ {
+ "type": "image_url",
+ "image_url": {"url": self.image_url},
+ },
+ ],
+ },
+ self._gt_tool_call,
+ self._gt_tool_result,
+ _gt_trailing_asst_nonfirst,
+ ]
+
+ # -------------------------------------------------------------------
+ # OpenAIChatFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_chat_formatter(self) -> None:
+ """Chat formatter produces exact output for various subsets."""
+ fmt = OpenAIChatFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_chat, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_chat[1:], res)
+
+ # Without conversation
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],
+ res,
+ )
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
+
+ async def test_chat_formatter_base64_image(self) -> None:
+ """Base64-encoded image is inlined as a data URI."""
+ fmt = OpenAIChatFormatter()
+ msgs = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(type="text", text="What's in this image?"),
+ DataBlock(
+ source=Base64Source(
+ type="base64",
+ data=self.image_b64,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {"type": "text", "text": "What's in this image?"},
+ {
+ "type": "image_url",
+ "image_url": {"url": self.image_data_uri},
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
+ async def test_chat_formatter_thinking_dropped(self) -> None:
+ """ThinkingBlock is silently dropped by OpenAI formatter."""
+ fmt = OpenAIChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="inner thoughts"),
+ TextBlock(type="text", text="reply"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ self.assertNotIn("reasoning_content", res[0])
+ self.assertEqual(
+ res[0]["content"],
+ [{"type": "text", "text": "reply"}],
+ )
+
+ async def test_chat_formatter_url_image_in_tool_result(self) -> None:
+ """URL images in tool results are promoted to a follow-up user
+ message."""
+ with patch.object(shortuuid, "uuid", return_value=_FIXED_ID):
+ fmt = OpenAIChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_img",
+ name="get_map",
+ input='{"city": "Tokyo"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_img",
+ name="get_map",
+ output=[
+ TextBlock(
+ type="text",
+ text="Here is the map.",
+ ),
+ DataBlock(
+ source=URLSource(
+ url=self.image_url,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+
+ expected_tool_content = (
+ "Here is the map.\n"
+ f"<system-reminder>A(n) image file is returned "
+ f"and will be presented to you with the identifier "
+ f"[{_FIXED_ID}].</system-reminder>"
+ )
+ self.assertEqual(len(res), 3)
+ self.assertEqual(res[0]["role"], "assistant")
+ self.assertEqual(res[1]["role"], "tool")
+ self.assertEqual(res[1]["content"], expected_tool_content)
+ # The promoted multimodal user message
+ self.assertEqual(res[2]["role"], "user")
+ image_blocks = [
+ b
+ for b in res[2]["content"]
+ if b.get("type") == "image_url"
+ and b["image_url"]["url"] == self.image_url
+ ]
+ self.assertEqual(len(image_blocks), 1)
+
+ # -------------------------------------------------------------------
+ # OpenAIMultiAgentFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_multiagent_formatter(self) -> None:
+ """MultiAgent formatter produces exact output for various subsets."""
+ fmt = OpenAIMultiAgentFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_multiagent, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_multiagent[1:], res)
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_multiagent[:2], res)
+
+ # System only
+ res = await fmt.format(self.msgs_system)
+ self.assertListEqual([self.gt_multiagent[0]], res)
+
+ # Conversation only
+ res = await fmt.format(self.msgs_conversation)
+ self.assertListEqual([self.gt_multiagent[1]], res)
+
+ # Tools only — is_first=True for the trailing assistant message
+ res = await fmt.format(self.msgs_tools)
+ self.assertListEqual(
+ [
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # System + tools (no conversation) — same is_first=True
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [
+ self.gt_multiagent[0],
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
diff --git a/tests/formatter_openai_response_test.py b/tests/formatter_openai_response_test.py
new file mode 100644
index 000000000..c7c51f1f7
--- /dev/null
+++ b/tests/formatter_openai_response_test.py
@@ -0,0 +1,543 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for OpenAIResponseFormatter and
+OpenAIResponseMultiAgentFormatter, following the reference test style with
+exact ground-truth comparisons.
+
+Key differences from OpenAI Chat formatter:
+ - Text content type is "input_text" (not "text").
+ - Image content type is "input_image" with flat "image_url" string.
+ - Tool calls become top-level "function_call" items (not nested in a msg).
+ - Tool results become top-level "function_call_output" items.
+ - ThinkingBlock: only echoed when it has a "reasoning_item_id" attribute.
+"""
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+import shortuuid
+
+from agentscope.formatter import (
+ OpenAIResponseFormatter,
+ OpenAIResponseMultiAgentFormatter,
+)
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ DataBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ Base64Source,
+ URLSource,
+ ThinkingBlock,
+)
+from agentscope.message._block import ToolResultState
+
+
+_FIXED_ID = "TESTID1234567"
+
+
+class TestOpenAIResponseFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for OpenAI Responses API formatters."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up shared message fixtures and expected ground-truth dicts."""
+ _img_src = URLSource(
+ url="https://example.com/image.png",
+ media_type="image/png",
+ )
+ self.image_url = str(_img_src.url)
+
+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+ self.image_data_uri = f"data:image/png;base64,{self.image_b64}"
+
+ # ---------------------------------------------------------------
+ # Message fixtures (no audio to avoid downloads)
+ # ---------------------------------------------------------------
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ DataBlock(
+ source=URLSource(
+ url=self.image_url,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Germany?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: OpenAIResponseFormatter
+ # - Text: {"type": "input_text", "text": ...}
+ # - Image: {"type": "input_image", "image_url": url_string}
+ # - ToolCallBlock → top-level {"type": "function_call", ...} item
+ # - ToolResultBlock → top-level {"type": "function_call_output", ...}
+ # - No "name" field on messages.
+ # ---------------------------------------------------------------
+ self.gt_chat = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "What is the capital of France?",
+ },
+ {"type": "input_image", "image_url": self.image_url},
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "What is the capital of Germany?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "The capital of Germany is Berlin.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "What is the capital of Japan?",
+ },
+ ],
+ },
+ {
+ "type": "function_call",
+ "id": "call_1",
+ "call_id": "call_1",
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ {
+ "type": "function_call_output",
+ "call_id": "call_1",
+ "output": "The capital of Japan is Tokyo.",
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ]
+
+ # ---------------------------------------------------------------
+ # Ground truth: OpenAIResponseMultiAgentFormatter
+ # - System: {"role": "system", "content": plain_string}
+ # - Conversation history: input_text with history wrapping.
+ # - Tool sequences use OpenAIResponseFormatter (function_call /
+ # function_call_output top-level items).
+ # ---------------------------------------------------------------
+ _hist_prompt = (
+ OpenAIResponseMultiAgentFormatter().conversation_history_prompt
+ )
+
+ _conv_text = (
+ "user: What is the capital of France?\n"
+ "assistant: The capital of France is Paris.\n"
+ "user: What is the capital of Germany?\n"
+ "assistant: The capital of Germany is Berlin.\n"
+ "user: What is the capital of Japan?"
+ )
+
+ _gt_trailing_asst_nonfirst = {
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": (
+ "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+ self._gt_trailing_asst_first = {
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": (
+ _hist_prompt + "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>"
+ ),
+ },
+ ],
+ }
+
+ self._gt_tool_call = {
+ "type": "function_call",
+ "id": "call_1",
+ "call_id": "call_1",
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ }
+ self._gt_tool_result = {
+ "type": "function_call_output",
+ "call_id": "call_1",
+ "output": "The capital of Japan is Tokyo.",
+ }
+
+ self.gt_multiagent = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": (
+ _hist_prompt
+ + "<history>\n"
+ + _conv_text
+ + "\n</history>"
+ ),
+ },
+ {"type": "input_image", "image_url": self.image_url},
+ ],
+ },
+ self._gt_tool_call,
+ self._gt_tool_result,
+ _gt_trailing_asst_nonfirst,
+ ]
+
+ # -------------------------------------------------------------------
+ # OpenAIResponseFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_chat_formatter(self) -> None:
+ """Chat formatter produces exact output for various subsets."""
+ fmt = OpenAIResponseFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_chat, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_chat[1:], res)
+
+ # Without conversation
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],
+ res,
+ )
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
+
+ async def test_chat_formatter_base64_image(self) -> None:
+ """Base64-encoded image becomes an input_image item with data URI."""
+ fmt = OpenAIResponseFormatter()
+ msgs = [
+ Msg(
+ name="user",
+ content=[
+ TextBlock(type="text", text="What's in this image?"),
+ DataBlock(
+ source=Base64Source(
+ type="base64",
+ data=self.image_b64,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ role="user",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertListEqual(
+ [
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "What's in this image?",
+ },
+ {
+ "type": "input_image",
+ "image_url": self.image_data_uri,
+ },
+ ],
+ },
+ ],
+ res,
+ )
+
+ async def test_chat_formatter_thinking_dropped_without_reasoning_item_id(
+ self,
+ ) -> None:
+ """ThinkingBlock without reasoning_item_id is silently skipped."""
+ fmt = OpenAIResponseFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="inner thoughts"),
+ TextBlock(type="text", text="reply"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ self.assertEqual(len(res), 1)
+ self.assertEqual(res[0]["role"], "assistant")
+ parts = res[0]["content"]
+ self.assertEqual(len(parts), 1)
+ self.assertEqual(parts[0]["type"], "input_text")
+
+ async def test_chat_formatter_thinking_echoed_with_reasoning_item_id(
+ self,
+ ) -> None:
+ """ThinkingBlock with reasoning_item_id is echoed as a reasoning
+ item."""
+ fmt = OpenAIResponseFormatter()
+ thinking = ThinkingBlock(thinking="my reasoning")
+ thinking.reasoning_item_id = "rs_001"
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[thinking, TextBlock(type="text", text="reply")],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ reasoning_items = [r for r in res if r.get("type") == "reasoning"]
+ self.assertEqual(len(reasoning_items), 1)
+ self.assertEqual(reasoning_items[0]["id"], "rs_001")
+ self.assertEqual(
+ reasoning_items[0]["summary"],
+ [{"type": "summary_text", "text": "my reasoning"}],
+ )
+
+ async def test_chat_formatter_url_image_in_tool_result(self) -> None:
+ """URL images in tool results are promoted to a follow-up user
+ message."""
+ with patch.object(shortuuid, "uuid", return_value=_FIXED_ID):
+ fmt = OpenAIResponseFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_img",
+ name="get_map",
+ input='{"city": "Tokyo"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_img",
+ name="get_map",
+ output=[
+ TextBlock(
+ type="text",
+ text="Here is the map.",
+ ),
+ DataBlock(
+ source=URLSource(
+ url=self.image_url,
+ media_type="image/png",
+ ),
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+
+ self.assertEqual(len(res), 3)
+ # function_call
+ self.assertEqual(res[0]["type"], "function_call")
+ # function_call_output with reminder text
+ self.assertEqual(res[1]["type"], "function_call_output")
+ self.assertIn("Here is the map.", res[1]["output"])
+ # promoted user message with the image
+ self.assertEqual(res[2]["role"], "user")
+ image_parts = [
+ p
+ for p in res[2]["content"]
+ if p.get("type") == "input_image"
+ and p.get("image_url") == self.image_url
+ ]
+ self.assertEqual(len(image_parts), 1)
+
+ # -------------------------------------------------------------------
+ # OpenAIResponseMultiAgentFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_multiagent_formatter(self) -> None:
+ """MultiAgent formatter produces exact output for various subsets."""
+ fmt = OpenAIResponseMultiAgentFormatter()
+ self.maxDiff = None
+
+ # Full history
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.gt_multiagent, res)
+
+ # Without system
+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+ self.assertListEqual(self.gt_multiagent[1:], res)
+
+ # Without tools
+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+ self.assertListEqual(self.gt_multiagent[:2], res)
+
+ # System only
+ res = await fmt.format(self.msgs_system)
+ self.assertListEqual([self.gt_multiagent[0]], res)
+
+ # Conversation only
+ res = await fmt.format(self.msgs_conversation)
+ self.assertListEqual([self.gt_multiagent[1]], res)
+
+ # Tools only — is_first=True for trailing assistant
+ res = await fmt.format(self.msgs_tools)
+ self.assertListEqual(
+ [
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # System + tools — same is_first=True
+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+ self.assertListEqual(
+ [
+ self.gt_multiagent[0],
+ self._gt_tool_call,
+ self._gt_tool_result,
+ self._gt_trailing_asst_first,
+ ],
+ res,
+ )
+
+ # Empty
+ res = await fmt.format([])
+ self.assertListEqual([], res)
diff --git a/tests/formatter_xai_test.py b/tests/formatter_xai_test.py
new file mode 100644
index 000000000..3a0aa9ad3
--- /dev/null
+++ b/tests/formatter_xai_test.py
@@ -0,0 +1,347 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for XAIChatFormatter and
+XAIMultiAgentFormatter (xAI), following the reference test style.
+
+Because these formatters return xai_sdk protobuf Message objects (not plain
+dicts), a lightweight xai_sdk stub is built at module load so that tests run
+without the real package. Assertions check mock object attributes
+(role, args, kwargs, tool_calls, etc.) rather than plain-dict equality.
+"""
+import sys
+from typing import Any
+from types import ModuleType
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.formatter import XAIChatFormatter, XAIMultiAgentFormatter
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ ThinkingBlock,
+ ToolResultState,
+)
+
+# ---------------------------------------------------------------------------
+# Build a lightweight xai_sdk stub so tests run without the real package.
+# ---------------------------------------------------------------------------
+
+
+def _build_xai_sdk_stub() -> None:
+ if "xai_sdk" in sys.modules:
+ return
+
+ chat_pb2 = ModuleType("xai_sdk.chat.chat_pb2")
+
+ class _EnumHelper:
+ _mapping = {
+ "ROLE_ASSISTANT": 2,
+ "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL": 1,
+ }
+
+ def Value(self, name: str) -> int:
+ """Return the integer value for the given enum name."""
+ return self._mapping.get(name, 0)
+
+ chat_pb2.MessageRole = _EnumHelper()
+ chat_pb2.ToolCallType = _EnumHelper()
+
+ class _RepeatedField(list):
+ def __init__(self, factory: Any) -> None:
+ super().__init__()
+ self._factory = factory
+
+ def add(self) -> Any:
+ """Add a new item using the factory and return it."""
+ item = self._factory()
+ self.append(item)
+ return item
+
+ class _FunctionSpec:
+ name: str = ""
+ arguments: str = ""
+
+ class _ToolCallProto:
+ id: str = ""
+ type: int = 0
+ function = _FunctionSpec()
+
+ class _ContentPart:
+ text: str = ""
+
+ class _MessageProto:
+ def __init__(self) -> None:
+ self.role = 0
+ self.content = _RepeatedField(_ContentPart)
+ self.tool_calls = _RepeatedField(_ToolCallProto)
+
+ chat_pb2.Message = _MessageProto
+
+ xai_chat = ModuleType("xai_sdk.chat")
+ xai_chat.chat_pb2 = chat_pb2
+ xai_chat.user = lambda *args: MagicMock(role="user", args=args)
+ xai_chat.assistant = lambda *args: MagicMock(role="assistant", args=args)
+ xai_chat.system = lambda *args: MagicMock(role="system", args=args)
+ xai_chat.tool_result = lambda *args, **kw: MagicMock(
+ role="tool",
+ args=args,
+ kwargs=kw,
+ )
+ xai_chat.image = lambda url: MagicMock(type="image", url=url)
+
+ xai_sdk = ModuleType("xai_sdk")
+ xai_sdk.chat = xai_chat
+ xai_sdk.AsyncClient = MagicMock()
+
+ sys.modules["xai_sdk"] = xai_sdk
+ sys.modules["xai_sdk.chat"] = xai_chat
+ sys.modules["xai_sdk.chat.chat_pb2"] = chat_pb2
+
+
+_build_xai_sdk_stub()
+
+
+class TestXAIFormatter(IsolatedAsyncioTestCase):
+ """Comprehensive tests for XAI Chat and MultiAgent formatters.
+
+ The formatter returns proto/mock objects rather than dicts, so assertions
+ inspect mock attributes (role, args, kwargs, tool_calls, etc.).
+ """
+
+ async def asyncSetUp(self) -> None:
+ self.msgs_system = [
+ Msg(
+ name="system",
+ content="You're a helpful assistant.",
+ role="system",
+ ),
+ ]
+
+ self.msgs_conversation = [
+ Msg(
+ name="user",
+ content="What is the capital of France?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of France is Paris.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Germany?",
+ role="user",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Germany is Berlin.",
+ role="assistant",
+ ),
+ Msg(
+ name="user",
+ content="What is the capital of Japan?",
+ role="user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ name="assistant",
+ content=[
+ ToolCallBlock(
+ id="call_1",
+ name="get_capital",
+ input='{"country": "Japan"}',
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="tool",
+ content=[
+ ToolResultBlock(
+ id="call_1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ ),
+ ],
+ role="assistant",
+ ),
+ Msg(
+ name="assistant",
+ content="The capital of Japan is Tokyo.",
+ role="assistant",
+ ),
+ ]
+
+ self._hist_prompt = (
+ XAIMultiAgentFormatter().conversation_history_prompt
+ )
+
+ # -------------------------------------------------------------------
+ # XAIChatFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_chat_formatter_system_message(self) -> None:
+ """System message becomes a system() proto."""
+ fmt = XAIChatFormatter()
+ res = await fmt.format(self.msgs_system)
+ self.assertEqual(len(res), 1)
+ self.assertEqual(res[0].role, "system")
+ self.assertIn("You're a helpful assistant.", res[0].args)
+
+ async def test_chat_formatter_user_assistant(self) -> None:
+ """User and assistant text messages are passed through correctly."""
+ fmt = XAIChatFormatter()
+ res = await fmt.format(self.msgs_conversation)
+ roles = [m.role for m in res]
+ self.assertEqual(roles.count("user"), 3)
+ self.assertEqual(roles.count("assistant"), 2)
+
+ async def test_chat_formatter_tool_call(self) -> None:
+ """Assistant tool call becomes a _MessageProto with tool_calls set."""
+ fmt = XAIChatFormatter()
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ # Find the tool call proto (has tool_calls list, role=ROLE_ASSISTANT=2)
+ tool_call_msgs = [
+ m
+ for m in res
+ if hasattr(m, "tool_calls") and len(m.tool_calls) > 0
+ ]
+ self.assertEqual(len(tool_call_msgs), 1)
+ tc = tool_call_msgs[0].tool_calls[0]
+ self.assertEqual(tc.id, "call_1")
+ self.assertEqual(tc.function.name, "get_capital")
+ self.assertIn('"country"', tc.function.arguments)
+
+ async def test_chat_formatter_tool_result(self) -> None:
+ """Tool result becomes a tool_result() proto with the right id."""
+ fmt = XAIChatFormatter()
+ res = await fmt.format(self.msgs_tools)
+ tool_msgs = [m for m in res if m.role == "tool"]
+ self.assertEqual(len(tool_msgs), 1)
+ self.assertEqual(
+ tool_msgs[0].kwargs.get("tool_call_id"),
+ "call_1",
+ )
+ self.assertIn(
+ "The capital of Japan is Tokyo.",
+ tool_msgs[0].args,
+ )
+
+ async def test_chat_formatter_thinking_dropped(self) -> None:
+ """ThinkingBlock is silently ignored in user/assistant xAI
+ messages."""
+ fmt = XAIChatFormatter()
+ msgs = [
+ Msg(
+ name="assistant",
+ content=[
+ ThinkingBlock(thinking="inner thoughts"),
+ TextBlock(type="text", text="reply"),
+ ],
+ role="assistant",
+ ),
+ ]
+ res = await fmt.format(msgs)
+ # thinking block is silently skipped for assistant text path
+ self.assertEqual(len(res), 1)
+ self.assertEqual(res[0].role, "assistant")
+
+ async def test_chat_formatter_empty(self) -> None:
+ """Empty input returns empty list."""
+ fmt = XAIChatFormatter()
+ res = await fmt.format([])
+ self.assertListEqual([], res)
+
+ # -------------------------------------------------------------------
+ # XAIMultiAgentFormatter tests
+ # -------------------------------------------------------------------
+
+ async def test_multiagent_formatter_system_message(self) -> None:
+ """System message is passed through as a system() proto."""
+ fmt = XAIMultiAgentFormatter()
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertEqual(res[0].role, "system")
+ self.assertIn("You're a helpful assistant.", res[0].args)
+
+ async def test_multiagent_formatter_conversation_history(self) -> None:
+ """Non-tool agent messages are collapsed into a user() history
+ proto."""
+ fmt = XAIMultiAgentFormatter()
+ res = await fmt.format(self.msgs_conversation)
+ self.assertEqual(len(res), 1)
+ self.assertEqual(res[0].role, "user")
+ hist_text = res[0].args[0]
+ self.assertIn("<history>", hist_text)
+ self.assertIn("</history>", hist_text)
+ self.assertIn("user: What is the capital of France?", hist_text)
+ self.assertIn("assistant: The capital of France is Paris.", hist_text)
+
+ async def test_multiagent_formatter_first_group_has_hist_prompt(
+ self,
+ ) -> None:
+ """First agent message group includes the conversation history
+ prompt."""
+ fmt = XAIMultiAgentFormatter()
+ res = await fmt.format(self.msgs_conversation)
+ hist_text = res[0].args[0]
+ self.assertTrue(hist_text.startswith(self._hist_prompt))
+
+ async def test_multiagent_formatter_full_history(self) -> None:
+ """Full history produces system + conv_history + tool_call +
+ tool_result + trailing."""
+ fmt = XAIMultiAgentFormatter()
+ res = await fmt.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ roles = [m.role for m in res]
+ self.assertIn("system", roles)
+ self.assertIn("user", roles)
+ self.assertIn("tool", roles)
+
+ async def test_multiagent_formatter_tools_only_is_first(self) -> None:
+ """When only tools are given, trailing agent uses is_first=True
+ history."""
+ fmt = XAIMultiAgentFormatter()
+ res = await fmt.format(self.msgs_tools)
+ # tool_call proto, tool_result proto, trailing user history
+ trailing = [m for m in res if m.role == "user"]
+ self.assertEqual(len(trailing), 1)
+ hist_text = trailing[0].args[0]
+ self.assertIn(self._hist_prompt, hist_text)
+ self.assertIn("assistant: The capital of Japan is Tokyo.", hist_text)
+
+ async def test_multiagent_formatter_nonfirst_trailing_no_hist_prompt(
+ self,
+ ) -> None:
+ """Trailing agent after a conversation group uses is_first=False
+ (no prompt)."""
+ fmt = XAIMultiAgentFormatter()
+ res = await fmt.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ user_msgs = [m for m in res if m.role == "user"]
+ # First is conversation history (is_first=True), last is trailing
+ # (is_first=False)
+ trailing_text = user_msgs[-1].args[0]
+ self.assertNotIn(self._hist_prompt, trailing_text)
+ self.assertIn("<history>", trailing_text)
+
+ async def test_multiagent_formatter_empty(self) -> None:
+ """Empty input returns empty list."""
+ fmt = XAIMultiAgentFormatter()
+ res = await fmt.format([])
+ self.assertListEqual([], res)
diff --git a/tests/model_anthropic_test.py b/tests/model_anthropic_test.py
new file mode 100644
index 000000000..b1b31e2b3
--- /dev/null
+++ b/tests/model_anthropic_test.py
@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for AnthropicChatModel response parsing.
+
+Formatter tests have been moved to tests/formatter_anthropic_test.py.
+"""
+import json
+from typing import Any
+from datetime import datetime
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import AnthropicChatModel
+from agentscope.credential import AnthropicCredential
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return AnthropicChatModel(
+ credential=AnthropicCredential(api_key="test"),
+ model="claude-opus-4-5",
+ stream=False,
+ context_size=200_000,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for AnthropicChatModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_anthropic_response(
+ self,
+ text: Any = None,
+ tool_calls: Any = None,
+ thinking: Any = None,
+ ) -> "MagicMock":
+ """Build a mock Anthropic API response object."""
+ blocks = []
+ if thinking:
+ b = MagicMock()
+ b.type = "thinking"
+ b.thinking = thinking
+ b.signature = ""
+ blocks.append(b)
+ if text:
+ b = MagicMock()
+ b.type = "text"
+ b.text = text
+ blocks.append(b)
+ if tool_calls:
+ for tc in tool_calls:
+ b = MagicMock()
+ b.type = "tool_use"
+ b.id = tc["id"]
+ b.name = tc["name"]
+ b.input = tc["input"]
+ blocks.append(b)
+
+ resp = MagicMock()
+ resp.id = "msg-1"
+ resp.content = blocks
+ resp.usage.input_tokens = 10
+ resp.usage.output_tokens = 5
+ return resp
+
+ async def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_anthropic_response(text="Hello!")
+ result = await self.model._parse_anthropic_completion_response(
+ self.start,
+ resp,
+ )
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(texts[0].text, "Hello!")
+
+ async def test_parse_tool_call_response(self) -> None:
+ """Parsing a tool-call response creates a ToolCallBlock."""
+ resp = self._mock_anthropic_response(
+ tool_calls=[
+ {
+ "id": "call-1",
+ "name": "get_weather",
+ "input": {"city": "Beijing"},
+ },
+ ],
+ )
+ result = await self.model._parse_anthropic_completion_response(
+ self.start,
+ resp,
+ )
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(tcs[0].id, "call-1")
+ self.assertEqual(tcs[0].name, "get_weather")
+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")
+
+ async def test_parse_thinking_response(self) -> None:
+ """Parsing a response with thinking creates a ThinkingBlock."""
+ resp = self._mock_anthropic_response(
+ thinking="Let me think...",
+ text="Answer",
+ )
+ result = await self.model._parse_anthropic_completion_response(
+ self.start,
+ resp,
+ )
+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]
+ self.assertEqual(thinkings[0].thinking, "Let me think...")
+
+ async def test_response_id_set(self) -> None:
+ """The response ID from the API is stored in the ChatResponse."""
+ resp = self._mock_anthropic_response(text="Hi")
+ result = await self.model._parse_anthropic_completion_response(
+ self.start,
+ resp,
+ )
+ self.assertEqual(result.id, "msg-1")
diff --git a/tests/model_dashscope_test.py b/tests/model_dashscope_test.py
new file mode 100644
index 000000000..d3e4b1e08
--- /dev/null
+++ b/tests/model_dashscope_test.py
@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for DashScopeChatModel response parsing.
+
+Formatter tests have been moved to tests/formatter_dashscope_test.py.
+"""
+import json
+from typing import Any
+from datetime import datetime
+from http import HTTPStatus
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import TextBlock, ToolCallBlock
+from agentscope.model import DashScopeChatModel
+from agentscope.credential import DashScopeCredential
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return DashScopeChatModel(
+ credential=DashScopeCredential(api_key="test"),
+ model="qwen3-max",
+ stream=False,
+ multimodality=True,
+ max_retries=3,
+ context_size=int(1500),
+ parameters=DashScopeChatModel.Parameters(
+ max_tokens=1000,
+ thinking_enable=True,
+ thinking_budget=100,
+ ),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for DashScopeChatModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_response(
+ self,
+ content: Any = None,
+ tool_calls: Any = None,
+ ) -> "MagicMock":
+ """Build a minimal DashScope GenerationResponse mock."""
+ message = {}
+ if content is not None:
+ message["content"] = content
+ if tool_calls is not None:
+ message["tool_calls"] = tool_calls
+
+ msg_mock = MagicMock()
+ msg_mock.get = lambda key, default=None: message.get(key, default)
+
+ resp = MagicMock()
+ resp.status_code = HTTPStatus.OK
+ resp.output.choices[0].message = msg_mock
+ resp.request_id = "req-1"
+ resp.usage.input_tokens = 10
+ resp.usage.output_tokens = 5
+ return resp
+
+ async def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_response(content="Hello!")
+ result = await self.model._parse_dashscope_generation_response(
+ self.start,
+ resp,
+ )
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(texts[0].text, "Hello!")
+
+ async def test_parse_tool_call_response(self) -> None:
+ """Parsing a tool-call response creates a ToolCallBlock."""
+ tool_calls = [
+ {
+ "id": "call-1",
+ "function": {
+ "name": "get_weather",
+ "arguments": '{"city":"Beijing"}',
+ },
+ },
+ ]
+ resp = self._mock_response(tool_calls=tool_calls)
+ result = await self.model._parse_dashscope_generation_response(
+ self.start,
+ resp,
+ )
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(len(tcs), 1)
+ self.assertEqual(tcs[0].id, "call-1")
+ self.assertEqual(tcs[0].name, "get_weather")
+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")
+
+ async def test_parse_response_with_status_error(self) -> None:
+ """Non-OK status raises RuntimeError."""
+ resp = self._mock_response(content="text")
+ resp.status_code = HTTPStatus.BAD_REQUEST
+ with self.assertRaises(RuntimeError):
+ await self.model._parse_dashscope_generation_response(
+ self.start,
+ resp,
+ )
diff --git a/tests/model_deepseek_test.py b/tests/model_deepseek_test.py
new file mode 100644
index 000000000..f775e72b0
--- /dev/null
+++ b/tests/model_deepseek_test.py
@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for DeepSeekChatModel response parsing.
+
+Formatter tests have been moved to tests/formatter_deepseek_test.py.
+"""
+from typing import Any
+from datetime import datetime
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import DeepSeekChatModel
+from agentscope.credential import DeepSeekCredential
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return DeepSeekChatModel(
+ credential=DeepSeekCredential(api_key="test"),
+ model="deepseek-v4-pro",
+ stream=False,
+ context_size=65_536,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestDeepSeekModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for DeepSeekChatModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_completion(
+ self,
+ text: Any = None,
+ tool_calls: Any = None,
+ reasoning: Any = None,
+ ) -> "MagicMock":
+ """Build a mock DeepSeek API completion response object."""
+ msg = MagicMock()
+ msg.content = text
+ setattr(msg, "reasoning_content", reasoning)
+ msg.tool_calls = None
+
+ if tool_calls:
+ tc_mocks = []
+ for tc in tool_calls:
+ m = MagicMock()
+ m.id = tc["id"]
+ m.function.name = tc["name"]
+ m.function.arguments = tc["arguments"]
+ tc_mocks.append(m)
+ msg.tool_calls = tc_mocks
+
+ choice = MagicMock()
+ choice.message = msg
+
+ resp = MagicMock()
+ resp.id = "deepseek-1"
+ resp.choices = [choice]
+ resp.usage.prompt_tokens = 10
+ resp.usage.completion_tokens = 5
+ return resp
+
+ def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_completion(text="Hello!")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(texts[0].text, "Hello!")
+
+ def test_parse_tool_call_response(self) -> None:
+ """Parsing a tool-call response creates a ToolCallBlock."""
+ resp = self._mock_completion(
+ tool_calls=[
+ {
+ "id": "call-1",
+ "name": "get_weather",
+ "arguments": '{"city":"Beijing"}',
+ },
+ ],
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(len(tcs), 1)
+ self.assertEqual(tcs[0].id, "call-1")
+ self.assertEqual(tcs[0].name, "get_weather")
+
+ def test_parse_thinking_response(self) -> None:
+ """Parsing a response with reasoning creates a ThinkingBlock."""
+ resp = self._mock_completion(
+ text="Answer",
+ reasoning="Let me think...",
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]
+ self.assertEqual(len(thinkings), 1)
+ self.assertEqual(thinkings[0].thinking, "Let me think...")
+
+ def test_response_id_set(self) -> None:
+ """The response ID from the API is stored in the ChatResponse."""
+ resp = self._mock_completion(text="Hi")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertEqual(result.id, "deepseek-1")
diff --git a/tests/model_gemini_test.py b/tests/model_gemini_test.py
new file mode 100644
index 000000000..53736994f
--- /dev/null
+++ b/tests/model_gemini_test.py
@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for GeminiChatModel response parsing.
+
+Formatter tests have been moved to tests/formatter_gemini_test.py.
+"""
+import json
+from typing import Any
+from datetime import datetime
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import GeminiChatModel
+from agentscope.credential import GeminiCredential
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return GeminiChatModel(
+ credential=GeminiCredential(api_key="test"),
+ model="gemini-2.5-flash",
+ stream=False,
+ context_size=1_048_576,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestGeminiModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for GeminiChatModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_response(
+ self,
+ text: Any = None,
+ function_calls: Any = None,
+ thought: Any = None,
+ ) -> "MagicMock":
+ """Build a mock Gemini API response object."""
+ parts = []
+ if thought:
+ p = MagicMock()
+ p.text = thought
+ p.thought = True
+ p.function_call = None
+ p.thought_signature = None
+ parts.append(p)
+ if text:
+ p = MagicMock()
+ p.text = text
+ p.thought = False
+ p.function_call = None
+ p.thought_signature = None
+ parts.append(p)
+ if function_calls:
+ for fc in function_calls:
+ p = MagicMock()
+ p.text = None
+ p.thought = False
+ p.thought_signature = None
+ p.function_call.name = fc["name"]
+ p.function_call.args = fc["args"]
+ p.function_call.id = fc.get("id", "call-1")
+ parts.append(p)
+
+ resp = MagicMock()
+ resp.candidates = [MagicMock()]
+ resp.candidates[0].content.parts = parts
+ resp.usage_metadata = MagicMock()
+ resp.usage_metadata.prompt_token_count = 10
+ resp.usage_metadata.candidates_token_count = 5
+ return resp
+
+ def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_response(text="Hello!")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(texts[0].text, "Hello!")
+
+ def test_parse_tool_call_response(self) -> None:
+ """Parsing a function_call response creates a ToolCallBlock."""
+ resp = self._mock_response(
+ function_calls=[
+ {
+ "name": "get_weather",
+ "args": {"city": "Beijing"},
+ "id": "call-1",
+ },
+ ],
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(len(tcs), 1)
+ self.assertEqual(tcs[0].name, "get_weather")
+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")
+
+ def test_parse_thinking_response(self) -> None:
+ """Parsing a response with thought creates a ThinkingBlock."""
+ resp = self._mock_response(thought="Let me think...", text="Answer")
+ result = self.model._parse_completion_response(self.start, resp)
+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]
+ self.assertEqual(len(thinkings), 1)
+ self.assertEqual(thinkings[0].thinking, "Let me think...")
diff --git a/tests/model_kimi_test.py b/tests/model_kimi_test.py
new file mode 100644
index 000000000..8dc98adbe
--- /dev/null
+++ b/tests/model_kimi_test.py
@@ -0,0 +1,115 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for KimiChatModel response parsing.
+
+Formatter tests have been moved to tests/formatter_kimi_test.py.
+"""
+import json
+from typing import Any
+from datetime import datetime
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import KimiChatModel
+from agentscope.credential import KimiCredential
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return KimiChatModel(
+ credential=KimiCredential(api_key="test"),
+ model="kimi-k2-5",
+ stream=False,
+ context_size=131_072,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestKimiModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for KimiChatModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_completion(
+ self,
+ text: Any = None,
+ tool_calls: Any = None,
+ reasoning: Any = None,
+ ) -> "MagicMock":
+ """Build a mock Kimi API completion response object."""
+ msg = MagicMock()
+ msg.content = text
+ setattr(msg, "reasoning_content", reasoning)
+ msg.tool_calls = None
+
+ if tool_calls:
+ tc_mocks = []
+ for tc in tool_calls:
+ m = MagicMock()
+ m.id = tc["id"]
+ m.function.name = tc["name"]
+ m.function.arguments = tc["arguments"]
+ tc_mocks.append(m)
+ msg.tool_calls = tc_mocks
+
+ choice = MagicMock()
+ choice.message = msg
+
+ resp = MagicMock()
+ resp.id = "kimi-1"
+ resp.choices = [choice]
+ resp.usage.prompt_tokens = 10
+ resp.usage.completion_tokens = 5
+ return resp
+
+ def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_completion(text="Hello!")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(texts[0].text, "Hello!")
+
+ def test_parse_tool_call_response(self) -> None:
+ """Parsing a tool-call response creates a ToolCallBlock."""
+ resp = self._mock_completion(
+ tool_calls=[
+ {
+ "id": "call-1",
+ "name": "get_weather",
+ "arguments": '{"city":"Beijing"}',
+ },
+ ],
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(len(tcs), 1)
+ self.assertEqual(tcs[0].id, "call-1")
+ self.assertEqual(tcs[0].name, "get_weather")
+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")
+
+ def test_parse_thinking_response(self) -> None:
+ """Parsing a response with reasoning creates a ThinkingBlock."""
+ resp = self._mock_completion(text="Answer", reasoning="Thinking...")
+ result = self.model._parse_completion_response(self.start, resp)
+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]
+ self.assertEqual(len(thinkings), 1)
+ self.assertEqual(thinkings[0].thinking, "Thinking...")
+
+ def test_response_id_set(self) -> None:
+ """The response ID from the API is stored in the ChatResponse."""
+ resp = self._mock_completion(text="Hi")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertEqual(result.id, "kimi-1")
diff --git a/tests/model_ollama_test.py b/tests/model_ollama_test.py
new file mode 100644
index 000000000..c8637bce6
--- /dev/null
+++ b/tests/model_ollama_test.py
@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OllamaChatModel response parsing.
+
+Formatter tests have been moved to tests/formatter_ollama_test.py.
+"""
+import json
+from typing import Any
+from datetime import datetime
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import OllamaChatModel
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return OllamaChatModel(
+ model="qwen3:8b",
+ stream=False,
+ context_size=40_960,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestOllamaModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for OllamaChatModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_response(
+ self,
+ content: Any = None,
+ tool_calls: Any = None,
+ thinking: Any = None,
+ ) -> "MagicMock":
+ """Build a mock Ollama API response object."""
+ msg = MagicMock()
+ msg.content = content or ""
+ setattr(msg, "thinking", thinking)
+
+ if tool_calls:
+ tc_mocks = []
+ for tc in tool_calls:
+ m = MagicMock()
+ m.function.name = tc["name"]
+ m.function.arguments = tc["args"]
+ tc_mocks.append(m)
+ msg.tool_calls = tc_mocks
+ else:
+ msg.tool_calls = None
+
+ resp = MagicMock()
+ resp.message = msg
+ resp.prompt_eval_count = 10
+ resp.eval_count = 5
+ setattr(resp, "id", "ollama-1")
+ return resp
+
+ async def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_response(content="Hello!")
+ result = await self.model._parse_completion_response(self.start, resp)
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(texts[0].text, "Hello!")
+
+ async def test_parse_tool_call_response(self) -> None:
+ """Parsing a tool-call response creates a ToolCallBlock."""
+ resp = self._mock_response(
+ tool_calls=[
+ {"name": "get_weather", "args": {"city": "Beijing"}},
+ ],
+ )
+ result = await self.model._parse_completion_response(self.start, resp)
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(len(tcs), 1)
+ self.assertEqual(tcs[0].name, "get_weather")
+ self.assertIn("city", json.loads(tcs[0].input))
+
+ async def test_parse_thinking_response(self) -> None:
+ """Parsing a response with thinking creates a ThinkingBlock."""
+ resp = self._mock_response(
+ content="Answer",
+ thinking="Let me think...",
+ )
+ result = await self.model._parse_completion_response(self.start, resp)
+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]
+ self.assertEqual(thinkings[0].thinking, "Let me think...")
diff --git a/tests/model_openai_chat_test.py b/tests/model_openai_chat_test.py
new file mode 100644
index 000000000..62d731865
--- /dev/null
+++ b/tests/model_openai_chat_test.py
@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OpenAIChatModel response parsing.
+
+Formatter tests have been moved to tests/formatter_openai_chat_test.py.
+"""
+import json
+from typing import Any
+from datetime import datetime
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import OpenAIChatModel
+from agentscope.credential import OpenAICredential
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return OpenAIChatModel(
+ credential=OpenAICredential(api_key="test"),
+ model="gpt-4o",
+ stream=False,
+ context_size=128_000,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestOpenAIChatModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for OpenAIChatModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_completion(
+ self,
+ text: Any = None,
+ tool_calls: Any = None,
+ reasoning: Any = None,
+ ) -> "MagicMock":
+ """Build a minimal ChatCompletion mock."""
+ msg = MagicMock()
+ msg.content = text
+ msg.tool_calls = None
+ setattr(msg, "reasoning_content", reasoning)
+ setattr(msg, "reasoning", None)
+
+ if tool_calls:
+ tc_mocks = []
+ for tc in tool_calls:
+ m = MagicMock()
+ m.id = tc["id"]
+ m.function.name = tc["name"]
+ m.function.arguments = tc["arguments"]
+ tc_mocks.append(m)
+ msg.tool_calls = tc_mocks
+
+ choice = MagicMock()
+ choice.message = msg
+ choice.delta = msg
+
+ resp = MagicMock()
+ resp.id = "resp-1"
+ resp.choices = [choice]
+ resp.usage.prompt_tokens = 10
+ resp.usage.completion_tokens = 5
+ return resp
+
+ def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_completion(text="Hello!")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(len(texts), 1)
+ self.assertEqual(texts[0].text, "Hello!")
+
+ def test_parse_tool_call_response(self) -> None:
+ """Parsing a tool-call response creates a ToolCallBlock."""
+ resp = self._mock_completion(
+ tool_calls=[
+ {
+ "id": "call-1",
+ "name": "get_weather",
+ "arguments": '{"city":"Beijing"}',
+ },
+ ],
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertTrue(result.is_last)
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(len(tcs), 1)
+ self.assertEqual(tcs[0].id, "call-1")
+ self.assertEqual(tcs[0].name, "get_weather")
+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")
+
+ def test_parse_thinking_response(self) -> None:
+ """Parsing a response with reasoning creates a ThinkingBlock."""
+ resp = self._mock_completion(
+ text="Answer",
+ reasoning="Let me think...",
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]
+ self.assertEqual(len(thinkings), 1)
+ self.assertEqual(thinkings[0].thinking, "Let me think...")
+
+ def test_response_id_set(self) -> None:
+ """The response ID from the API is stored in the ChatResponse."""
+ resp = self._mock_completion(text="Hi")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertEqual(result.id, "resp-1")
diff --git a/tests/model_openai_response_test.py b/tests/model_openai_response_test.py
new file mode 100644
index 000000000..fe6edfb66
--- /dev/null
+++ b/tests/model_openai_response_test.py
@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OpenAIResponseModel response parsing.
+
+Formatter tests have been moved to tests/formatter_openai_response_test.py.
+"""
+import json
+from typing import Any
+from datetime import datetime
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import OpenAIResponseModel
+from agentscope.credential import OpenAICredential
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return OpenAIResponseModel(
+ credential=OpenAICredential(api_key="test"),
+ model="o4-mini",
+ stream=False,
+ context_size=200_000,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestOpenAIResponseModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for OpenAIResponseModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_response(
+ self,
+ text: Any = None,
+ function_calls: Any = None,
+ reasoning_summary: Any = None,
+ reasoning_id: str = "rs_test123",
+ ) -> "MagicMock":
+ """Build a mock OpenAI Responses API response object."""
+ output = []
+
+ if reasoning_summary:
+ reasoning_item = MagicMock()
+ reasoning_item.type = "reasoning"
+ reasoning_item.id = reasoning_id
+ summary_mock = MagicMock()
+ summary_mock.text = reasoning_summary
+ reasoning_item.summary = [summary_mock]
+ output.append(reasoning_item)
+
+ if text:
+ msg_item = MagicMock()
+ msg_item.type = "message"
+ part = MagicMock()
+ part.type = "output_text"
+ part.text = text
+ msg_item.content = [part]
+ output.append(msg_item)
+
+ if function_calls:
+ for fc in function_calls:
+ fc_item = MagicMock()
+ fc_item.type = "function_call"
+ fc_item.id = fc["id"]
+ fc_item.call_id = fc["call_id"]
+ fc_item.name = fc["name"]
+ fc_item.arguments = fc["arguments"]
+ output.append(fc_item)
+
+ resp = MagicMock()
+ resp.id = "resp-openai-1"
+ resp.output = output
+ resp.usage.input_tokens = 10
+ resp.usage.output_tokens = 5
+ return resp
+
+ def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_response(text="Hello!")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(texts[0].text, "Hello!")
+
+ def test_parse_tool_call_response(self) -> None:
+ """Parsing a function_call response creates a ToolCallBlock."""
+ resp = self._mock_response(
+ function_calls=[
+ {
+ "id": "fc_abc123",
+ "call_id": "call-1",
+ "name": "get_weather",
+ "arguments": '{"city":"Beijing"}',
+ },
+ ],
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(len(tcs), 1)
+ self.assertEqual(tcs[0].id, "fc_abc123")
+ self.assertEqual(tcs[0].call_id, "call-1")
+ self.assertEqual(tcs[0].name, "get_weather")
+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")
+
+ def test_parse_reasoning_response(self) -> None:
+ """Parsing a reasoning item creates a ThinkingBlock with item id."""
+ resp = self._mock_response(
+ reasoning_summary="Thinking step...",
+ text="Answer",
+ reasoning_id="rs_abc999",
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]
+ self.assertEqual(len(thinkings), 1)
+ self.assertEqual(thinkings[0].thinking, "Thinking step...")
+ self.assertEqual(
+ getattr(thinkings[0], "reasoning_item_id", None),
+ "rs_abc999",
+ )
+
+ def test_response_id_set(self) -> None:
+ """The response ID from the API is stored in the ChatResponse."""
+ resp = self._mock_response(text="Hi")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertEqual(result.id, "resp-openai-1")
diff --git a/tests/model_xai_test.py b/tests/model_xai_test.py
new file mode 100644
index 000000000..d3328ced4
--- /dev/null
+++ b/tests/model_xai_test.py
@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for XAIChatModel (xAI) response parsing.
+
+Formatter tests have been moved to tests/formatter_xai_test.py.
+"""
+import json
+import sys
+from typing import Any
+from datetime import datetime
+from types import ModuleType
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.message import (
+ TextBlock,
+ ToolCallBlock,
+ ThinkingBlock,
+)
+from agentscope.model import XAIChatModel
+from agentscope.credential import XAICredential
+
+
+# ---------------------------------------------------------------------------
+# Build a lightweight xai_sdk stub so tests run without the real package.
+# ---------------------------------------------------------------------------
+
+
+def _build_xai_sdk_stub() -> None:
+ """Register stub modules for xai_sdk so imports don't fail."""
+ if "xai_sdk" in sys.modules:
+ return
+
+ # chat_pb2 stub -----------------------------------------------------------
+ chat_pb2 = ModuleType("xai_sdk.chat.chat_pb2")
+
+ class _EnumHelper:
+ """Helper that makes .Value() return an integer."""
+
+ _mapping = {
+ "ROLE_ASSISTANT": 2,
+ "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL": 1,
+ }
+
+ def Value(self, name: str) -> int:
+ """Return the integer value for the given enum name."""
+ return self._mapping.get(name, 0)
+
+ chat_pb2.MessageRole = _EnumHelper()
+ chat_pb2.ToolCallType = _EnumHelper()
+
+ class _RepeatedField(list):
+ """Minimal repeated proto field that supports .add()."""
+
+ def __init__(self, factory: Any) -> None:
+ super().__init__()
+ self._factory = factory
+
+ def add(self) -> Any:
+ """Add a new item using the factory and return it."""
+ item = self._factory()
+ self.append(item)
+ return item
+
+ class _FunctionSpec:
+ name: str = ""
+ arguments: str = ""
+
+ class _ToolCallProto:
+ id: str = ""
+ type: int = 0
+ function = _FunctionSpec()
+
+ class _ContentPart:
+ text: str = ""
+
+ class _MessageProto:
+ def __init__(self) -> None:
+ self.role = 0
+ self.content = _RepeatedField(_ContentPart)
+ self.tool_calls = _RepeatedField(_ToolCallProto)
+
+ chat_pb2.Message = _MessageProto
+
+ # xai_sdk.chat stub -------------------------------------------------------
+ xai_chat = ModuleType("xai_sdk.chat")
+ xai_chat.chat_pb2 = chat_pb2
+ xai_chat.user = lambda *args: MagicMock(role="user", args=args)
+ xai_chat.assistant = lambda *args: MagicMock(role="assistant", args=args)
+ xai_chat.system = lambda *args: MagicMock(role="system", args=args)
+ xai_chat.tool_result = lambda *args, **kw: MagicMock(
+ role="tool",
+ args=args,
+ kwargs=kw,
+ )
+ xai_chat.image = lambda url: MagicMock(type="image", url=url)
+
+ # xai_sdk stub ------------------------------------------------------------
+ xai_sdk = ModuleType("xai_sdk")
+ xai_sdk.chat = xai_chat
+ xai_sdk.AsyncClient = MagicMock()
+
+ sys.modules["xai_sdk"] = xai_sdk
+ sys.modules["xai_sdk.chat"] = xai_chat
+ sys.modules["xai_sdk.chat.chat_pb2"] = chat_pb2
+
+
+_build_xai_sdk_stub()
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model() -> Any:
+ return XAIChatModel(
+ credential=XAICredential(api_key="test"),
+ model="grok-3",
+ stream=False,
+ context_size=131_072,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Model response parsing tests
+# ---------------------------------------------------------------------------
+
+
+class TestXAIModelParsing(IsolatedAsyncioTestCase):
+ """Unit tests for XAIChatModel response parsing."""
+
+ def setUp(self) -> None:
+ """Set up a fresh model instance and start time."""
+ self.model = _make_model()
+ self.start = datetime.now()
+
+ def _mock_response(
+ self,
+ text: Any = None,
+ tool_calls: Any = None,
+ reasoning: Any = None,
+ ) -> "MagicMock":
+ """Build a mock xAI API response object."""
+ resp = MagicMock()
+ resp.id = "xai-resp-1"
+ resp.content = text or ""
+ resp.reasoning_content = reasoning or ""
+ resp.tool_calls = None
+ resp.usage = None
+
+ if tool_calls:
+ tc_mocks = []
+ for tc in tool_calls:
+ m = MagicMock()
+ m.id = tc["id"]
+ m.function.name = tc["name"]
+ m.function.arguments = tc["arguments"]
+ tc_mocks.append(m)
+ resp.tool_calls = tc_mocks
+
+ return resp
+
+ def test_parse_text_response(self) -> None:
+ """Parsing a text response creates a TextBlock."""
+ resp = self._mock_response(text="Hello!")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertTrue(result.is_last)
+ texts = [b for b in result.content if isinstance(b, TextBlock)]
+ self.assertEqual(texts[0].text, "Hello!")
+
+ def test_parse_tool_call_response(self) -> None:
+ """Parsing a tool call response creates a ToolCallBlock."""
+ resp = self._mock_response(
+ tool_calls=[
+ {
+ "id": "call-1",
+ "name": "get_weather",
+ "arguments": '{"city":"Beijing"}',
+ },
+ ],
+ )
+ result = self.model._parse_completion_response(self.start, resp)
+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]
+ self.assertEqual(len(tcs), 1)
+ self.assertEqual(tcs[0].id, "call-1")
+ self.assertEqual(tcs[0].name, "get_weather")
+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")
+
+ def test_parse_thinking_response(self) -> None:
+ """Parsing a response with reasoning creates a ThinkingBlock."""
+ resp = self._mock_response(text="Answer", reasoning="Let me think...")
+ result = self.model._parse_completion_response(self.start, resp)
+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]
+ self.assertEqual(len(thinkings), 1)
+ self.assertEqual(thinkings[0].thinking, "Let me think...")
+
+ def test_response_id_set(self) -> None:
+ """The response ID from the API is stored in the ChatResponse."""
+ resp = self._mock_response(text="Hi")
+ result = self.model._parse_completion_response(self.start, resp)
+ self.assertEqual(result.id, "xai-resp-1")
diff --git a/tests/utils.py b/tests/utils.py
index 90fada666..dc8356cee 100644
--- a/tests/utils.py
+++ b/tests/utils.py
@@ -4,10 +4,8 @@ from typing import Any, AsyncGenerator, Type
from pydantic import BaseModel
-from agentscope.formatter import DashScopeChatFormatter
from agentscope.message import Msg
-from agentscope.model import ChatModelBase, ChatResponse
-from agentscope.model._model_response import StructuredResponse
+from agentscope.model import ChatModelBase, ChatResponse, StructuredResponse
class AnyString:
@@ -25,18 +23,20 @@ class AnyString:
class MockModel(ChatModelBase):
"""A mock model for testing."""
- def __init__(self, context_length: int = 10000) -> None:
+ def __init__(
+ self,
+ model: str = "mock-model",
+ context_size: int = 1000,
+ mock_chat_responses: list | None = None,
+ mock_structured_response: Any = None,
+ ) -> None:
"""Initialize the mock model."""
super().__init__(
- model_name="mock-model",
- stream=True,
- context_length=context_length,
- max_retries=0,
- fallback_model_name=None,
- formatter=DashScopeChatFormatter(),
+ model=model,
+ context_size=context_size,
)
- self.mock_chat_responses = []
- self.mock_structured_response = None
+ self.mock_chat_responses = mock_chat_responses or []
+ self.mock_structured_response = mock_structured_response
self.cnt = 0
def set_responses(