Skip to content

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

feat(model): add client_kwargs in chat model modules (#1659)

qbcb9e363416acf
diff --git a/src/agentscope/credential/_xai.py b/src/agentscope/credential/_xai.py
index c1f67357a..ec0df6447 100644
--- a/src/agentscope/credential/_xai.py
+++ b/src/agentscope/credential/_xai.py
@@ -25,6 +25,16 @@ class XAICredential(CredentialBase):
)
"""The xAI API key."""
+ api_host: str = Field(
+ default="api.x.ai",
+ title="API Host",
+ description=(
+ "The xAI API host (without scheme). Override to point at a "
+ "compatible/self-hosted endpoint."
+ ),
+ )
+ """The xAI API host."""
+
@classmethod
def get_chat_model_class(cls) -> Type["ChatModelBase"]:
"""Return the XAIChatModel class."""
diff --git a/src/agentscope/model/_anthropic/_model.py b/src/agentscope/model/_anthropic/_model.py
index b84232be1..208b378a1 100644
--- a/src/agentscope/model/_anthropic/_model.py
+++ b/src/agentscope/model/_anthropic/_model.py
@@ -2,12 +2,12 @@
"""The Anthropic chat model implementation."""
from collections import OrderedDict
from datetime import datetime
-from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
from pydantic import BaseModel, Field
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
-from .._model_response import ChatResponse
+from .._model_response import ChatResponse, StructuredResponse
from .._model_usage import ChatUsage
from ...credential import AnthropicCredential
from ...formatter import FormatterBase, AnthropicChatFormatter
@@ -63,6 +63,7 @@ class AnthropicChatModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 200000,
formatter: FormatterBase | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the Anthropic chat model.
@@ -85,6 +86,10 @@ class AnthropicChatModel(ChatModelBase):
The formatter that converts ``Msg`` objects to the format
required by the Anthropic API. When ``None``, an
``AnthropicChatFormatter`` instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to
+ ``anthropic.AsyncAnthropic`` (e.g. ``timeout``,
+ ``default_headers``, ``http_client``, ``auth_token``).
"""
super().__init__(
credential=credential,
@@ -95,6 +100,7 @@ class AnthropicChatModel(ChatModelBase):
context_size=context_size,
)
self.formatter = formatter or AnthropicChatFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -130,8 +136,11 @@ class AnthropicChatModel(ChatModelBase):
import anthropic
client = anthropic.AsyncAnthropic(
- api_key=self.credential.api_key.get_secret_value(),
- base_url=self.credential.base_url,
+ **{
+ "api_key": self.credential.api_key.get_secret_value(),
+ "base_url": self.credential.base_url,
+ **self.client_kwargs,
+ },
)
# Anthropic requires max_tokens; fall back to a safe default when
@@ -485,3 +494,56 @@ class AnthropicChatModel(ChatModelBase):
"required": {"type": "any"},
}
return fmt_tools, type_mapping[mode]
+
+ async def _call_api_with_structured_output(
+ self,
+ model_name: str,
+ messages: list[Msg],
+ structured_model: Type[BaseModel] | dict,
+ tool_choice: ToolChoice | None = None,
+ **kwargs: Any,
+ ) -> StructuredResponse:
+ """Anthropic-specific override for structured output.
+
+ Anthropic's extended thinking mode only supports
+ ``tool_choice={"type": "auto"}`` or ``{"type": "none"}``; any
+ forcing form (``"any"`` or a specific tool) raises an API error.
+ When ``thinking_enable`` is on we default ``tool_choice`` to
+ ``"auto"`` and rely on the base class's injected system-reminder
+ prompt to guide the model. When thinking is disabled, this falls
+ through to the base implementation (force the structured-output
+ tool).
+
+ See:
+ https://platform.claude.com/docs/en/build-with-claude/extended-thinking#extended-thinking-with-tool-use
+
+ Args:
+ model_name (`str`):
+ The model name to use for this call.
+ messages (`list[Msg]`):
+ The context for the LLM to generate the structured output.
+ structured_model (`Type[BaseModel] | dict`):
+ A Pydantic model class or a JSON schema dict describing the
+ required output structure.
+ tool_choice (`ToolChoice | None`, defaults to `None`):
+ The tool_choice forwarded to ``_call_api``. When ``None``
+ and thinking mode is enabled, it is downgraded to
+ ``ToolChoice(mode="auto")``; otherwise the base default
+ (force the structured-output tool) is used.
+ **kwargs (`Any`):
+ Additional keyword arguments forwarded to ``_call_api``.
+
+ Returns:
+ `StructuredResponse`:
+ The structured response whose ``content`` is the validated
+ output dict matching ``structured_model``.
+ """
+ if tool_choice is None and self.parameters.thinking_enable:
+ tool_choice = ToolChoice(mode="auto")
+ return await super()._call_api_with_structured_output(
+ model_name=model_name,
+ messages=messages,
+ structured_model=structured_model,
+ tool_choice=tool_choice,
+ **kwargs,
+ )
diff --git a/src/agentscope/model/_dashscope/_model.py b/src/agentscope/model/_dashscope/_model.py
index f3d7fe0e9..2ed3316f4 100644
--- a/src/agentscope/model/_dashscope/_model.py
+++ b/src/agentscope/model/_dashscope/_model.py
@@ -104,6 +104,7 @@ class DashScopeChatModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 131072,
formatter: FormatterBase | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the DashScope chat model.
@@ -126,6 +127,9 @@ class DashScopeChatModel(ChatModelBase):
The formatter that converts ``Msg`` objects to the format
required by the DashScope API. When ``None``, a
``DashScopeChatFormatter`` instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to ``openai.AsyncClient``
+ (e.g. ``timeout``, ``default_headers``, ``http_client``).
"""
super().__init__(
credential=credential,
@@ -136,6 +140,7 @@ class DashScopeChatModel(ChatModelBase):
context_size=context_size,
)
self.formatter = formatter or DashScopeChatFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -164,8 +169,11 @@ class DashScopeChatModel(ChatModelBase):
import openai
client = openai.AsyncClient(
- api_key=self.credential.api_key.get_secret_value(),
- base_url=self.credential.base_url,
+ **{
+ "api_key": self.credential.api_key.get_secret_value(),
+ "base_url": self.credential.base_url,
+ **self.client_kwargs,
+ },
)
formatted_messages = await self.formatter.format(messages)
@@ -534,6 +542,8 @@ class DashScopeChatModel(ChatModelBase):
injected system-reminder prompt to guide the model. When thinking
is disabled, this falls through to the base implementation.
+ See: https://help.aliyun.com/en/model-studio/qwen-function-calling
+
Args:
model_name (`str`):
The model name to use for this call.
diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.py
index d05a84bb2..f869f164f 100644
--- a/src/agentscope/model/_deepseek/_model.py
+++ b/src/agentscope/model/_deepseek/_model.py
@@ -84,6 +84,7 @@ class DeepSeekChatModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 65536,
formatter: FormatterBase | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the DeepSeek chat model.
@@ -106,6 +107,9 @@ class DeepSeekChatModel(ChatModelBase):
The formatter that converts ``Msg`` objects to the format
required by the DeepSeek API. When ``None``, a
``DeepSeekChatFormatter`` instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to ``openai.AsyncClient``
+ (e.g. ``timeout``, ``default_headers``, ``http_client``).
"""
super().__init__(
credential=credential,
@@ -116,6 +120,7 @@ class DeepSeekChatModel(ChatModelBase):
context_size=context_size,
)
self.formatter = formatter or DeepSeekChatFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -148,8 +153,11 @@ class DeepSeekChatModel(ChatModelBase):
import openai
client = openai.AsyncClient(
- api_key=self.credential.api_key.get_secret_value(),
- base_url=self.credential.base_url,
+ **{
+ "api_key": self.credential.api_key.get_secret_value(),
+ "base_url": self.credential.base_url,
+ **self.client_kwargs,
+ },
)
formatted_messages = await self.formatter.format(messages)
diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.py
index d93dcade0..1790ce008 100644
--- a/src/agentscope/model/_gemini/_model.py
+++ b/src/agentscope/model/_gemini/_model.py
@@ -130,6 +130,7 @@ class GeminiChatModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 1048576,
formatter: FormatterBase | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the Gemini chat model.
@@ -152,6 +153,10 @@ class GeminiChatModel(ChatModelBase):
The formatter that converts ``Msg`` objects to the format
required by the Gemini API. When ``None``, a
``GeminiChatFormatter`` instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to ``google.genai.Client``
+ (e.g. ``vertexai``, ``project``, ``location``,
+ ``credentials``, ``http_options``).
"""
super().__init__(
credential=credential,
@@ -162,6 +167,7 @@ class GeminiChatModel(ChatModelBase):
context_size=context_size,
)
self.formatter = formatter or GeminiChatFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -194,7 +200,10 @@ class GeminiChatModel(ChatModelBase):
from google import genai
client = genai.Client(
- api_key=self.credential.api_key.get_secret_value(),
+ **{
+ "api_key": self.credential.api_key.get_secret_value(),
+ **self.client_kwargs,
+ },
)
formatted_messages = await self.formatter.format(messages)
diff --git a/src/agentscope/model/_moonshot/_model.py b/src/agentscope/model/_moonshot/_model.py
index fc23f996e..c38d7fe66 100644
--- a/src/agentscope/model/_moonshot/_model.py
+++ b/src/agentscope/model/_moonshot/_model.py
@@ -73,6 +73,7 @@ class MoonshotChatModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 131072,
formatter: FormatterBase | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the Moonshot AI chat model.
@@ -95,6 +96,9 @@ class MoonshotChatModel(ChatModelBase):
The formatter that converts ``Msg`` objects to the format
required by the API. When ``None``, a
``MoonshotChatFormatter`` instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to ``openai.AsyncClient``
+ (e.g. ``timeout``, ``default_headers``, ``http_client``).
"""
super().__init__(
credential=credential,
@@ -105,6 +109,7 @@ class MoonshotChatModel(ChatModelBase):
context_size=context_size,
)
self.formatter = formatter or MoonshotChatFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -137,8 +142,11 @@ class MoonshotChatModel(ChatModelBase):
import openai
client = openai.AsyncClient(
- api_key=self.credential.api_key.get_secret_value(),
- base_url=self.credential.base_url,
+ **{
+ "api_key": self.credential.api_key.get_secret_value(),
+ "base_url": self.credential.base_url,
+ **self.client_kwargs,
+ },
)
formatted_messages = await self.formatter.format(messages)
diff --git a/src/agentscope/model/_ollama/_model.py b/src/agentscope/model/_ollama/_model.py
index cc7f13344..93eec45e7 100644
--- a/src/agentscope/model/_ollama/_model.py
+++ b/src/agentscope/model/_ollama/_model.py
@@ -62,6 +62,7 @@ class OllamaChatModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 32768,
formatter: FormatterBase | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the Ollama chat model.
@@ -85,6 +86,10 @@ class OllamaChatModel(ChatModelBase):
The formatter that converts ``Msg`` objects to the format
required by the Ollama API. When ``None``, an
``OllamaChatFormatter`` instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to ``ollama.AsyncClient``
+ and onward to the underlying ``httpx.AsyncClient``
+ (e.g. ``timeout``, ``headers``, ``verify``).
"""
resolved_credential = credential or OllamaCredential()
@@ -98,6 +103,7 @@ class OllamaChatModel(ChatModelBase):
)
self.formatter = formatter or OllamaChatFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -129,7 +135,12 @@ class OllamaChatModel(ChatModelBase):
"""
import ollama
- client = ollama.AsyncClient(host=self.credential.host)
+ client = ollama.AsyncClient(
+ **{
+ "host": self.credential.host,
+ **self.client_kwargs,
+ },
+ )
formatted_messages = await self.formatter.format(messages)
diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.py
index ccef80ae5..9741b0465 100644
--- a/src/agentscope/model/_openai_chat/_model.py
+++ b/src/agentscope/model/_openai_chat/_model.py
@@ -99,6 +99,7 @@ class OpenAIChatModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 128000,
formatter: FormatterBase | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the OpenAI chat model.
@@ -121,6 +122,9 @@ class OpenAIChatModel(ChatModelBase):
The formatter that converts ``Msg`` objects to the format
required by the OpenAI API. When ``None``, an
``OpenAIChatFormatter`` instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to ``openai.AsyncClient``
+ (e.g. ``timeout``, ``default_headers``, ``http_client``).
"""
super().__init__(
credential=credential,
@@ -131,6 +135,7 @@ class OpenAIChatModel(ChatModelBase):
context_size=context_size,
)
self.formatter = formatter or OpenAIChatFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -163,9 +168,12 @@ class OpenAIChatModel(ChatModelBase):
import openai
client = openai.AsyncClient(
- api_key=self.credential.api_key.get_secret_value(),
- organization=self.credential.organization,
- base_url=self.credential.base_url,
+ **{
+ "api_key": self.credential.api_key.get_secret_value(),
+ "organization": self.credential.organization,
+ "base_url": self.credential.base_url,
+ **self.client_kwargs,
+ },
)
formatted_messages = await self.formatter.format(messages)
diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.py
index d17040f5a..e4aed9809 100644
--- a/src/agentscope/model/_openai_response/_model.py
+++ b/src/agentscope/model/_openai_response/_model.py
@@ -88,6 +88,7 @@ class OpenAIResponseModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 200000,
formatter: FormatterBase | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the OpenAI Responses API chat model.
@@ -110,6 +111,9 @@ class OpenAIResponseModel(ChatModelBase):
The formatter that converts ``Msg`` objects to the format
required by the OpenAI Responses API. When ``None``, an
``OpenAIResponseFormatter`` instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to ``openai.AsyncClient``
+ (e.g. ``timeout``, ``default_headers``, ``http_client``).
"""
super().__init__(
credential=credential,
@@ -120,6 +124,7 @@ class OpenAIResponseModel(ChatModelBase):
context_size=context_size,
)
self.formatter = formatter or OpenAIResponseFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -152,9 +157,12 @@ class OpenAIResponseModel(ChatModelBase):
import openai
client = openai.AsyncClient(
- api_key=self.credential.api_key.get_secret_value(),
- organization=self.credential.organization,
- base_url=self.credential.base_url,
+ **{
+ "api_key": self.credential.api_key.get_secret_value(),
+ "organization": self.credential.organization,
+ "base_url": self.credential.base_url,
+ **self.client_kwargs,
+ },
)
formatted_messages = await self.formatter.format(messages)
diff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.py
index e998b8ff7..9e360ae40 100644
--- a/src/agentscope/model/_xai/_model.py
+++ b/src/agentscope/model/_xai/_model.py
@@ -98,6 +98,7 @@ class XAIChatModel(ChatModelBase):
max_retries: int = 3,
context_size: int = 131072,
formatter: XAIChatFormatter | None = None,
+ client_kwargs: dict[str, Any] | None = None,
) -> None:
"""Initialize the xAI chat model.
@@ -120,6 +121,12 @@ class XAIChatModel(ChatModelBase):
The formatter that converts ``Msg`` objects to xai_sdk
proto messages. When ``None``, an ``XAIChatFormatter``
instance will be used.
+ client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+ Extra keyword arguments forwarded to ``xai_sdk.AsyncClient``
+ (e.g. ``timeout``, ``metadata``, ``channel_options``). Keys
+ that overlap with credential-derived arguments (such as
+ ``api_key`` or ``api_host``) take precedence over the
+ credential values.
"""
super().__init__(
credential=credential,
@@ -130,6 +137,7 @@ class XAIChatModel(ChatModelBase):
context_size=context_size,
)
self.formatter = formatter or XAIChatFormatter()
+ self.client_kwargs = client_kwargs or {}
async def _call_api(
self,
@@ -162,7 +170,11 @@ class XAIChatModel(ChatModelBase):
from xai_sdk import AsyncClient
client = AsyncClient(
- api_key=self.credential.api_key.get_secret_value(),
+ **{
+ "api_key": self.credential.api_key.get_secret_value(),
+ "api_host": self.credential.api_host,
+ **self.client_kwargs,
+ },
)
xai_messages = await self.formatter.format(messages)