Skip to content

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

feat(model): add opt-in content-block error normalization (#3324)

qbc051c7a77e456
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index 71a38bc1d..a4ffaeab9 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -72,7 +72,11 @@ from ..event import (
UserInterruptEvent,
HintBlockEvent,
)
-from ..exception import AgentOrientedException
+from ..exception import (
+ AgentOrientedException,
+ ContentBlockedError,
+ ContentBlockedPhase,
+)
from ..model import (
ChatResponse,
ChatUsage,
@@ -455,6 +459,10 @@ class Agent:
await self.compress_context(context_config=context_config)
except Exception as e: # pylint: disable=broad-exception-caught
+ if isinstance(e, ContentBlockedError) and (
+ e.partial_output or e.requires_review
+ ):
+ raise
return ToolChunk(
content=[TextBlock(text=f"Context compression failed: {e}")],
state=ToolResultState.ERROR,
@@ -630,6 +638,10 @@ class Agent:
)
except Exception as error:
+ if isinstance(error, ContentBlockedError) and (
+ error.partial_output or error.requires_review
+ ):
+ raise
if context_overflow:
logger.warning(
"Failed to compress context, which may be caused by "
@@ -668,6 +680,11 @@ class Agent:
structured_model=cfg.summary_schema,
)
except Exception as retry_error:
+ if isinstance(retry_error, ContentBlockedError) and (
+ retry_error.partial_output
+ or retry_error.requires_review
+ ):
+ raise
error = retry_error
if res is None:
@@ -3397,7 +3414,7 @@ class Agent:
try:
# Apply middleware to wrap the actual model() call
if not self._model_call_middlewares:
- return await model(
+ result = await model(
messages=messages,
tools=tools,
tool_choice=tool_choice,
@@ -3445,9 +3462,27 @@ class Agent:
next_handler=next_handler,
)
- return await execute_chain()
+ result = await execute_chain()
+
+ if inspect.isasyncgen(result):
+ return self._observe_model_stream(result, model)
+ return result
except Exception as e:
last_exception = e
+ if isinstance(e, ContentBlockedError):
+ # Custom models or middleware may consume a stream
+ # before returning. Honor any reported output rather
+ # than replaying a partially delivered response.
+ if e.partial_output or e.requires_review:
+ raise
+ if e.phase != ContentBlockedPhase.OUTPUT:
+ message = (
+ f"Model {model.model} blocked content for "
+ f"agent {self.name}; skipping retries with "
+ f"the same payload."
+ )
+ logger.warning(message)
+ break
# Only log a "Retrying" message when there's actually a
# next attempt left for this model. When ``max_retries=0``
# or the last retry has been used, the outer loop either
@@ -3471,12 +3506,42 @@ class Agent:
)
if last_exception:
+ if isinstance(last_exception, ContentBlockedError):
+ raise last_exception
raise last_exception from None
raise RuntimeError(
"Model call failed after retries, but no exception was raised.",
)
+ async def _observe_model_stream(
+ self,
+ stream: AsyncGenerator[ChatResponse, None],
+ model: ChatModelBase,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Observe a returned model stream without replaying model calls.
+
+ Yield chunks unchanged. Log and re-raise content-block errors that
+ occur during consumption. At this point
+ the agent's model-selection loop has returned, so this wrapper does
+ not retry or switch fallback models, even before the first chunk.
+ Always close the delegated stream when iteration exits, including
+ on error or explicit closure of this wrapper.
+ """
+ try:
+ async for chunk in stream:
+ yield chunk
+ except ContentBlockedError:
+ message = (
+ f"Model {model.model} blocked content for agent {self.name} "
+ f"during stream consumption; Agent-level retries and "
+ f"fallback model switching are not attempted."
+ )
+ logger.warning(message)
+ raise
+ finally:
+ await stream.aclose()
+
def _update_tool_call_state(
self,
tool_call_id: str,
diff --git a/src/agentscope/exception/__init__.py b/src/agentscope/exception/__init__.py
index 8313c1828..160c13dbe 100644
--- a/src/agentscope/exception/__init__.py
+++ b/src/agentscope/exception/__init__.py
@@ -5,7 +5,11 @@ from ._base import (
AgentOrientedException,
DeveloperOrientedException,
)
-from ._model import StructuredOutputError
+from ._model import (
+ ContentBlockedError,
+ ContentBlockedPhase,
+ StructuredOutputError,
+)
from ._tool import (
ToolInterruptedError,
ToolNotFoundError,
@@ -16,6 +20,8 @@ from ._tool import (
__all__ = [
"AgentOrientedException",
"DeveloperOrientedException",
+ "ContentBlockedError",
+ "ContentBlockedPhase",
"StructuredOutputError",
"ToolInterruptedError",
"ToolNotFoundError",
diff --git a/src/agentscope/exception/_model.py b/src/agentscope/exception/_model.py
index 4866c235a..9effb90fd 100644
--- a/src/agentscope/exception/_model.py
+++ b/src/agentscope/exception/_model.py
@@ -1,8 +1,71 @@
# -*- coding: utf-8 -*-
"""The model related exceptions."""
+from enum import StrEnum
+
from ._base import DeveloperOrientedException
+class ContentBlockedPhase(StrEnum):
+ """The phase in which a model provider blocked content."""
+
+ INPUT = "input"
+ """The provider rejected the model input."""
+
+ OUTPUT = "output"
+ """The provider blocked the generated model output."""
+
+ UNKNOWN = "unknown"
+ """The provider did not identify the blocked phase."""
+
+
+class ContentBlockedError(DeveloperOrientedException):
+ """Raised when a model provider blocks input or output content.
+
+ The normalized fields let agent-level recovery logic handle different
+ provider protocols without depending on their SDK exception classes.
+ """
+
+ def __init__(
+ self,
+ message: str,
+ *,
+ phase: ContentBlockedPhase = ContentBlockedPhase.UNKNOWN,
+ provider: str | None = None,
+ original_code: str | None = None,
+ request_id: str | None = None,
+ partial_output: bool = False,
+ requires_review: bool = False,
+ ) -> None:
+ """Initialize a normalized content-blocked error.
+
+ Args:
+ message (`str`):
+ The provider error message.
+ phase (`ContentBlockedPhase`):
+ The request phase in which content was blocked.
+ provider (`str | None`):
+ The provider identifier.
+ original_code (`str | None`):
+ The original provider error or finish code.
+ request_id (`str | None`):
+ The provider request identifier, when available.
+ partial_output (`bool`):
+ Whether model output was emitted before the block signal.
+ requires_review (`bool`, defaults to `False`):
+ Whether the provider requires review before further actions.
+ Adapters set this flag from explicit provider signals. The
+ agent must not automatically retry or switch fallback models
+ when it is set.
+ """
+ super().__init__(message)
+ self.phase = phase
+ self.provider = provider
+ self.original_code = original_code
+ self.request_id = request_id
+ self.partial_output = partial_output
+ self.requires_review = requires_review
+
+
class StructuredOutputError(DeveloperOrientedException):
"""Raised when the model fails to produce a valid structured output,
e.g. it does not call the structured-output tool, returns an empty
diff --git a/src/agentscope/model/_anthropic/_model.py b/src/agentscope/model/_anthropic/_model.py
index cd2dd1194..615c6b2cf 100644
--- a/src/agentscope/model/_anthropic/_model.py
+++ b/src/agentscope/model/_anthropic/_model.py
@@ -12,6 +12,7 @@ from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ..._utils._common import _generate_id
from ...credential import AnthropicCredential
+from ...exception import ContentBlockedError, ContentBlockedPhase
from ...formatter import FormatterBase, AnthropicChatFormatter
from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
from ...tool import ToolChoice
@@ -44,6 +45,8 @@ def _total_input_tokens(usage: Any) -> int:
class AnthropicChatModel(ChatModelBase):
"""The Anthropic chat model."""
+ _content_block_provider = "anthropic"
+
type: Literal["anthropic_chat"] = "anthropic_chat"
"""The type of the chat model."""
@@ -128,6 +131,7 @@ class AnthropicChatModel(ChatModelBase):
context_size: int = 200000,
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
+ raise_on_refusal: bool = False,
) -> None:
"""Initialize the Anthropic chat model.
@@ -156,6 +160,9 @@ class AnthropicChatModel(ChatModelBase):
Extra keyword arguments forwarded to
``anthropic.AsyncAnthropic`` (e.g. ``timeout``,
``default_headers``, ``http_client``, ``auth_token``).
+ raise_on_refusal (`bool`, defaults to `False`):
+ Whether an explicit provider refusal should raise a
+ ``ContentBlockedError`` instead of remaining normal output.
"""
super().__init__(
credential=credential,
@@ -165,6 +172,7 @@ class AnthropicChatModel(ChatModelBase):
max_retries=max_retries,
retry_delay=retry_delay,
context_size=context_size,
+ raise_on_refusal=raise_on_refusal,
)
self.formatter = formatter or AnthropicChatFormatter()
self.client_kwargs = client_kwargs or {}
@@ -368,6 +376,21 @@ class AnthropicChatModel(ChatModelBase):
A single ``ChatResponse`` with ``is_last=True`` containing
the extracted content blocks and usage.
"""
+ if (
+ self.raise_on_refusal
+ and getattr(response, "stop_reason", None) == "refusal"
+ ):
+ stop_details = getattr(response, "stop_details", None)
+ explanation = getattr(stop_details, "explanation", None)
+ raise ContentBlockedError(
+ explanation
+ or f"{self._content_block_provider} refused the response.",
+ phase=ContentBlockedPhase.OUTPUT,
+ provider=self._content_block_provider,
+ original_code="refusal",
+ request_id=getattr(response, "id", None),
+ )
+
content_blocks: List[ThinkingBlock | TextBlock | ToolCallBlock] = []
if hasattr(response, "content") and response.content:
@@ -487,6 +510,7 @@ class AnthropicChatModel(ChatModelBase):
tool_call_mapping: dict = OrderedDict()
# The indexes of the tool calls that received argument text
tool_call_with_input: set[int] = set()
+ has_output = False
async with response as stream:
async for event in stream:
@@ -611,6 +635,31 @@ class AnthropicChatModel(ChatModelBase):
)
elif event.type == "message_delta":
+ if (
+ self.raise_on_refusal
+ and getattr(event.delta, "stop_reason", None)
+ == "refusal"
+ ):
+ stop_details = getattr(
+ event.delta,
+ "stop_details",
+ None,
+ )
+ explanation = getattr(
+ stop_details,
+ "explanation",
+ None,
+ )
+ raise ContentBlockedError(
+ explanation
+ or f"{self._content_block_provider} refused "
+ f"the response.",
+ phase=ContentBlockedPhase.OUTPUT,
+ provider=self._content_block_provider,
+ original_code="refusal",
+ request_id=response_id,
+ partial_output=has_output,
+ )
if event.usage and usage:
usage.output_tokens = event.usage.output_tokens or 0
# Update cumulative counts before adding cache tokens.
@@ -648,6 +697,7 @@ class AnthropicChatModel(ChatModelBase):
).total_seconds()
if delta_res.content:
+ has_output = True
delta_res.usage = usage
yield delta_res
diff --git a/src/agentscope/model/_base.py b/src/agentscope/model/_base.py
index 2a61e247d..d22d4e7ed 100644
--- a/src/agentscope/model/_base.py
+++ b/src/agentscope/model/_base.py
@@ -17,7 +17,11 @@ from ._utils import _StreamAccumulator
from .._logging import logger
from .._utils._common import _json_loads_with_repair
from ..credential import CredentialBase
-from ..exception import StructuredOutputError, ToolJSONDecodeError
+from ..exception import (
+ ContentBlockedError,
+ StructuredOutputError,
+ ToolJSONDecodeError,
+)
from ..message import (
Msg,
TextBlock,
@@ -68,6 +72,8 @@ class ChatModelBase:
max_retries: int = 3,
retry_delay: float = 1.0,
context_size: int = 32768,
+ raise_on_refusal: bool = False,
+ raise_on_content_filter: bool = False,
) -> None:
"""Initialize the chat model base.
@@ -88,6 +94,22 @@ class ChatModelBase:
Seconds to sleep between retry attempts.
context_size (`int`, defaults to `32768`):
The model context size used for context compression.
+ raise_on_refusal (`bool`, defaults to `False`):
+ Whether a provider's explicit refusal signal should raise a
+ ``ContentBlockedError`` instead of remaining normal output.
+ raise_on_content_filter (`bool`, defaults to `False`):
+ Opt in to content-filter exceptions and SDK error
+ normalization, including structured-output calls. When
+ disabled, preserve legacy parsing and SDK exceptions.
+ This does not change the provider's filtering policy.
+
+ Content-block exceptions do not use this model's SDK retry budget.
+ Before a result or stream is returned, Agent may retry OUTPUT blocks
+ within ``ModelConfig.max_retries`` if no output was emitted and no
+ review is required. After a stream is returned, consumption errors
+ are surfaced without Agent retries or fallback-model switching,
+ even before the first chunk. This boundary depends on when the error
+ occurs, not just whether ``stream`` is enabled.
"""
self.credential = credential
self.model = model
@@ -96,6 +118,8 @@ class ChatModelBase:
self.max_retries = max_retries
self.retry_delay = retry_delay
self.context_size = context_size
+ self.raise_on_refusal = raise_on_refusal
+ self.raise_on_content_filter = raise_on_content_filter
@classmethod
def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
@@ -108,6 +132,32 @@ class ChatModelBase:
"""
return ()
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Normalize a provider exception before retry classification.
+
+ Provider implementations can override this hook to translate SDK
+ exceptions into AgentScope exceptions such as
+ :class:`~agentscope.exception.ContentBlockedError`. Returning the
+ original exception preserves the default behavior.
+
+ The hook is used for ordinary calls, stream-consumption failures,
+ and structured-output calls. Return an exception rather than raising
+ it here: the caller classifies retries or structured-output fallback
+ and chains a replacement exception when raising it. Stream failures
+ are normalized without retrying inside the model stream wrapper.
+ This hook does not invoke agent recovery middleware.
+
+ Args:
+ error (`Exception`):
+ The exception raised by the provider SDK.
+
+ Returns:
+ `Exception`:
+ A normalized exception, or the original object unchanged
+ when the provider signal is not recognized.
+ """
+ return error
+
def _get_disable_thinking_kwargs(self) -> dict:
"""Return kwargs that disable thinking for this provider.
@@ -226,16 +276,19 @@ class ChatModelBase:
)
except Exception as e:
- if not isinstance(e, retryable):
+ normalized_error = self._normalize_exception(e)
+ if not isinstance(normalized_error, retryable):
+ if normalized_error is not e:
+ raise normalized_error from e
raise
- last_error = e
+ last_error = normalized_error
if attempt < self.max_retries:
logger.warning(
"Attempt %d failed for model %s: %s. "
"Retrying in %.1fs...",
attempt + 1,
self.model,
- str(e),
+ str(normalized_error),
self.retry_delay,
)
await asyncio.sleep(self.retry_delay)
@@ -264,6 +317,7 @@ class ChatModelBase:
# For backward compatibility
yield_acc_res = True
acc_res = _StreamAccumulator()
+ emitted = False
try:
async for chunk in res:
if not chunk.is_last:
@@ -281,10 +335,18 @@ class ChatModelBase:
continue
else:
yield_acc_res = False
+ emitted = True
yield chunk
except asyncio.CancelledError:
acc_res.finished_reason = FinishedReason.INTERRUPTED
yield_acc_res = True
+ except Exception as e:
+ normalized_error = self._normalize_exception(e)
+ if isinstance(normalized_error, ContentBlockedError):
+ normalized_error.partial_output |= emitted
+ if normalized_error is not e:
+ raise normalized_error from e
+ raise
finally:
# Closing this wrapper does not close the delegated iterator.
# Wait for provider cleanup before ``aclose`` returns.
@@ -561,10 +623,11 @@ class ChatModelBase:
# CancelledError / KeyboardInterrupt derive from
# BaseException and are not caught here, so they
# propagate as expected.
+ normalized_error = self._normalize_exception(e)
if first_error is None:
- first_error = e
- last_error = e
- if isinstance(e, retryable):
+ first_error = normalized_error
+ last_error = normalized_error
+ if isinstance(normalized_error, retryable):
# Transient error: retry the same strategy. A
# different strategy hits the same endpoint, so
# switching would not help a rate limit or timeout.
@@ -574,13 +637,17 @@ class ChatModelBase:
"failed: %s. Retrying in %.1fs...",
attempt + 1,
self.model,
- e,
+ normalized_error,
self.retry_delay,
)
await asyncio.sleep(self.retry_delay)
continue
- raise # retries exhausted -> give up
- if not isinstance(e, fallback):
+ if normalized_error is not e:
+ raise normalized_error from e
+ raise
+ if not isinstance(normalized_error, fallback):
+ if normalized_error is not e:
+ raise normalized_error from e
raise
# Structured-output compatibility failure: try the next
# strategy.
@@ -589,7 +656,7 @@ class ChatModelBase:
"Trying next.",
name,
self.model,
- e,
+ normalized_error,
)
break
diff --git a/src/agentscope/model/_content_block.py b/src/agentscope/model/_content_block.py
new file mode 100644
index 000000000..2ecb5513c
--- /dev/null
+++ b/src/agentscope/model/_content_block.py
@@ -0,0 +1,174 @@
+# -*- coding: utf-8 -*-
+"""Helpers for normalizing provider content-block errors."""
+from collections.abc import Mapping
+from typing import Any
+
+from ..exception import ContentBlockedError, ContentBlockedPhase
+
+
+def _as_mapping(value: Any) -> Mapping[str, Any] | None:
+ """Convert SDK response objects to a mapping when possible."""
+ if isinstance(value, Mapping):
+ return value
+ model_dump = getattr(value, "model_dump", None)
+ if callable(model_dump):
+ dumped = model_dump()
+ if isinstance(dumped, Mapping):
+ return dumped
+ return None
+
+
+def _get_error_field(error: Exception, field: str) -> Any:
+ """Read an error field from common OpenAI-compatible SDK shapes."""
+ body = _as_mapping(getattr(error, "body", None))
+ if body is not None:
+ nested = _as_mapping(body.get("error"))
+ if nested is not None and nested.get(field) is not None:
+ return nested[field]
+ if body.get(field) is not None:
+ return body[field]
+ return getattr(error, field, None)
+
+
+def _get_request_id(error: Exception) -> str | None:
+ """Extract a request identifier from an SDK exception."""
+ request_id = getattr(error, "request_id", None)
+ if request_id is not None:
+ return str(request_id)
+
+ response = getattr(error, "response", None)
+ headers = getattr(response, "headers", None)
+ if headers is None:
+ return None
+ for header in ("x-request-id", "request-id"):
+ value = headers.get(header)
+ if value is not None:
+ return str(value)
+ return None
+
+
+def _normalize_openai_compatible_content_error(
+ error: Exception,
+ *,
+ provider: str,
+ blocked_codes: set[str],
+ phase: ContentBlockedPhase,
+ code_field: str = "code",
+) -> ContentBlockedError | None:
+ """Build an error from an explicitly recognized provider code.
+
+ Args:
+ error (`Exception`):
+ The SDK exception. Fields are read from nested ``body.error``,
+ then ``body``, then exception attributes, in that order.
+ provider (`str`):
+ Provider identifier to include in the normalized error.
+ blocked_codes (`set[str]`):
+ Recognized codes, already case-folded for comparison.
+ phase (`ContentBlockedPhase`):
+ The phase assigned by the adapter, or UNKNOWN if ambiguous.
+ code_field (`str`, defaults to `"code"`):
+ The structured field identifying the error. Use ``"type"``
+ only for providers whose payload uses that field.
+
+ Returns:
+ `ContentBlockedError | None`:
+ A new error retaining the original code's casing and available
+ request ID, or ``None`` for absent or unrecognized codes. Error
+ text and HTTP status alone never determine a match.
+
+ This helper returns rather than raises the error. The calling model
+ layer is responsible for chaining it to the original SDK exception.
+ """
+ code = _get_error_field(error, code_field)
+ if code is None:
+ return None
+ original_code = str(code)
+ if original_code.casefold() not in blocked_codes:
+ return None
+
+ message = _get_error_field(error, "message")
+ return ContentBlockedError(
+ str(message) if message is not None else str(error),
+ phase=phase,
+ provider=provider,
+ original_code=original_code,
+ request_id=_get_request_id(error),
+ )
+
+
+def _enum_name(value: Any) -> str | None:
+ """Return a stable uppercase name for SDK enum-like values."""
+ if value is None:
+ return None
+ raw_value = getattr(value, "name", None)
+ if raw_value is None:
+ raw_value = getattr(value, "value", value)
+ return str(raw_value).rsplit(".", maxsplit=1)[-1].upper()
+
+
+def _openai_compatible_response_block_error(
+ choice: Any,
+ *,
+ provider: str,
+ request_id: str | None,
+ partial_output: bool = False,
+ include_refusal: bool = False,
+ include_content_filter: bool = True,
+) -> ContentBlockedError | None:
+ """Build an output-block error from one Chat Completions choice.
+
+ Args:
+ choice (`Any`):
+ An SDK response or stream choice exposing ``finish_reason`` and
+ optionally ``message`` or ``delta`` attributes.
+ provider (`str`):
+ Provider identifier for the normalized error.
+ request_id (`str | None`):
+ The identifier obtained by the caller from the response.
+ partial_output (`bool`, defaults to `False`):
+ Whether output preceded this signal. Copied to the error;
+ this helper does not track stream consumption itself.
+ include_refusal (`bool`, defaults to `False`):
+ Also recognize a non-empty explicit refusal string in ``delta``
+ or, if absent, ``message``. Content-filter finish reasons are
+ controlled separately by ``include_content_filter``.
+ include_content_filter (`bool`, defaults to `True`):
+ Whether to recognize a content-filter finish reason. Adapters
+ pass their explicit opt-in; refusal handling is independent.
+
+ Returns:
+ `ContentBlockedError | None`:
+ An OUTPUT-phase error, or ``None`` when no supported signal is
+ found. Ordinary response text is never scanned for refusals.
+ """
+ finish_reason = _enum_name(getattr(choice, "finish_reason", None))
+ if include_content_filter and finish_reason == "CONTENT_FILTER":
+ return ContentBlockedError(
+ f"{provider} blocked the generated content.",
+ phase=ContentBlockedPhase.OUTPUT,
+ provider=provider,
+ original_code="content_filter",
+ request_id=request_id,
+ partial_output=partial_output,
+ )
+
+ if include_refusal:
+ content = getattr(choice, "delta", None)
+ if content is None:
+ content = getattr(choice, "message", None)
+ refusal = getattr(content, "refusal", None)
+ if isinstance(refusal, str) and refusal:
+ return ContentBlockedError(
+ (
+ f"{provider} refused the response."
+ if getattr(choice, "delta", None) is not None
+ else refusal
+ ),
+ phase=ContentBlockedPhase.OUTPUT,
+ provider=provider,
+ original_code="refusal",
+ request_id=request_id,
+ partial_output=partial_output,
+ )
+ return None
diff --git a/src/agentscope/model/_dashscope/_model.py b/src/agentscope/model/_dashscope/_model.py
index d9b524def..b21a60eaf 100644
--- a/src/agentscope/model/_dashscope/_model.py
+++ b/src/agentscope/model/_dashscope/_model.py
@@ -11,9 +11,14 @@ from pydantic import BaseModel, Field
from ..._utils._audio import _build_streaming_wav_header
from ..._utils._common import _generate_id
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._content_block import (
+ _normalize_openai_compatible_content_error,
+ _openai_compatible_response_block_error,
+)
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...credential import DashScopeCredential
+from ...exception import ContentBlockedPhase
from ...formatter import FormatterBase, DashScopeChatFormatter
from ...message import (
Msg,
@@ -125,6 +130,7 @@ class DashScopeChatModel(ChatModelBase):
context_size: int = 131072,
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
+ raise_on_content_filter: bool = False,
) -> None:
"""Initialize the DashScope chat model.
@@ -152,6 +158,10 @@ class DashScopeChatModel(ChatModelBase):
client_kwargs (`dict[str, Any] | None`, defaults to `None`):
Extra keyword arguments forwarded to ``openai.AsyncClient``
(e.g. ``timeout``, ``default_headers``, ``http_client``).
+ raise_on_content_filter (`bool`, defaults to `False`):
+ Raise ``ContentBlockedError`` for supported filter signals.
+ Disabled by default. See ``ChatModelBase.__init__`` for
+ compatibility, structured-output, and stream retry limits.
"""
super().__init__(
credential=credential,
@@ -161,6 +171,7 @@ class DashScopeChatModel(ChatModelBase):
max_retries=max_retries,
retry_delay=retry_delay,
context_size=context_size,
+ raise_on_content_filter=raise_on_content_filter,
)
self.formatter = formatter or DashScopeChatFormatter()
self.client_kwargs = client_kwargs or {}
@@ -192,6 +203,21 @@ class DashScopeChatModel(ChatModelBase):
return (openai.BadRequestError,)
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Normalize structured DashScope data-inspection errors."""
+ if not self.raise_on_content_filter:
+ return error
+ normalized = _normalize_openai_compatible_content_error(
+ error,
+ provider="dashscope",
+ blocked_codes={
+ "datainspectionfailed",
+ "data_inspection_failed",
+ },
+ phase=ContentBlockedPhase.UNKNOWN,
+ )
+ return normalized or error
+
async def _call_api(
self,
model_name: str,
@@ -311,6 +337,7 @@ class DashScopeChatModel(ChatModelBase):
audio_id = _generate_id()
# The mapping from index to tool call id
tool_call_mapping: dict = OrderedDict()
+ has_output = False
async with response as stream:
async for chunk in stream:
@@ -345,6 +372,15 @@ class DashScopeChatModel(ChatModelBase):
continue
choice = chunk.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="dashscope",
+ request_id=response_id,
+ partial_output=has_output,
+ )
+ if blocked_error is not None:
+ raise blocked_error
delta = choice.delta
# Thinking
@@ -429,6 +465,7 @@ class DashScopeChatModel(ChatModelBase):
if delta_res.content or usage:
delta_res.usage = usage
+ has_output = has_output or bool(delta_res.content)
yield delta_res
def _parse_completion_response(
@@ -453,6 +490,14 @@ class DashScopeChatModel(ChatModelBase):
if response.choices:
choice = response.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="dashscope",
+ request_id=getattr(response, "id", None),
+ )
+ if blocked_error is not None:
+ raise blocked_error
reasoning = getattr(choice.message, "reasoning_content", None)
if isinstance(reasoning, str) and reasoning:
content_blocks.append(ThinkingBlock(thinking=reasoning))
diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.py
index 66cb47641..387de8304 100644
--- a/src/agentscope/model/_deepseek/_model.py
+++ b/src/agentscope/model/_deepseek/_model.py
@@ -7,6 +7,9 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
from pydantic import BaseModel, Field
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._content_block import (
+ _openai_compatible_response_block_error,
+)
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ..._utils._common import _generate_id
@@ -86,6 +89,7 @@ class DeepSeekChatModel(ChatModelBase):
context_size: int = 65536,
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
+ raise_on_content_filter: bool = False,
) -> None:
"""Initialize the DeepSeek chat model.
@@ -113,6 +117,10 @@ class DeepSeekChatModel(ChatModelBase):
client_kwargs (`dict[str, Any] | None`, defaults to `None`):
Extra keyword arguments forwarded to ``openai.AsyncClient``
(e.g. ``timeout``, ``default_headers``, ``http_client``).
+ raise_on_content_filter (`bool`, defaults to `False`):
+ Raise ``ContentBlockedError`` for supported filter signals.
+ Disabled by default. See ``ChatModelBase.__init__`` for
+ compatibility, structured-output, and stream retry limits.
"""
super().__init__(
credential=credential,
@@ -122,6 +130,7 @@ class DeepSeekChatModel(ChatModelBase):
max_retries=max_retries,
retry_delay=retry_delay,
context_size=context_size,
+ raise_on_content_filter=raise_on_content_filter,
)
self.formatter = formatter or DeepSeekChatFormatter()
self.client_kwargs = client_kwargs or {}
@@ -260,6 +269,7 @@ class DeepSeekChatModel(ChatModelBase):
thinking_id: str = _generate_id()
# The mapping from index to tool call id
tool_call_mapping: dict = OrderedDict()
+ has_output = False
async with response as stream:
async for chunk in stream:
@@ -299,6 +309,15 @@ class DeepSeekChatModel(ChatModelBase):
continue
choice = chunk.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="deepseek",
+ request_id=response_id,
+ partial_output=has_output,
+ )
+ if blocked_error is not None:
+ raise blocked_error
delta = choice.delta
# Thinking block
@@ -339,6 +358,7 @@ class DeepSeekChatModel(ChatModelBase):
)
if delta_res.content or usage:
+ has_output = has_output or bool(delta_res.content)
delta_res.usage = usage
yield delta_res
@@ -363,6 +383,14 @@ class DeepSeekChatModel(ChatModelBase):
if response.choices:
choice = response.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="deepseek",
+ request_id=getattr(response, "id", None),
+ )
+ if blocked_error is not None:
+ raise blocked_error
reasoning = getattr(choice.message, "reasoning_content", None)
if isinstance(reasoning, str) and reasoning:
content_blocks.append(ThinkingBlock(thinking=reasoning))
diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.py
index 1163c2c7f..f04859a28 100644
--- a/src/agentscope/model/_gemini/_model.py
+++ b/src/agentscope/model/_gemini/_model.py
@@ -9,9 +9,11 @@ from pydantic import BaseModel, Field
from ..._utils._common import _generate_id, _flatten_json_schema
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._content_block import _enum_name
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...credential import GeminiCredential
+from ...exception import ContentBlockedError, ContentBlockedPhase
from ...formatter import FormatterBase, GeminiChatFormatter
from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
from ...tool import ToolChoice
@@ -22,6 +24,75 @@ else:
GenerateContentResponse = Any
+_GEMINI_PROMPT_BLOCK_REASONS = frozenset(
+ {
+ "SAFETY",
+ "BLOCKLIST",
+ "PROHIBITED_CONTENT",
+ "IMAGE_SAFETY",
+ },
+)
+_GEMINI_OUTPUT_BLOCK_REASONS = frozenset(
+ {
+ "SAFETY",
+ "BLOCKLIST",
+ "PROHIBITED_CONTENT",
+ "SPII",
+ "IMAGE_SAFETY",
+ },
+)
+
+
+def _gemini_content_block_error(
+ response: Any,
+ *,
+ partial_output: bool = False,
+) -> ContentBlockedError | None:
+ """Build an error from explicit Gemini prompt or candidate signals.
+
+ Inspect recognized ``prompt_feedback.block_reason`` values first
+ (INPUT phase), then the first candidate's ``finish_reason`` (OUTPUT
+ phase). Return ``None`` for other reasons or absent signals; neither
+ generated text nor safety ratings alone determine a match.
+
+ Accept a complete response or a streamed chunk. Copy ``response_id``
+ when present and the caller's ``partial_output`` flag, which indicates
+ output emitted before this signal. No stream tracking or retry occurs
+ inside this helper.
+ """
+ request_id = getattr(response, "response_id", None)
+ prompt_feedback = getattr(response, "prompt_feedback", None)
+ block_reason = _enum_name(
+ getattr(prompt_feedback, "block_reason", None),
+ )
+ if block_reason in _GEMINI_PROMPT_BLOCK_REASONS:
+ message = getattr(prompt_feedback, "block_reason_message", None)
+ return ContentBlockedError(
+ message or f"Gemini blocked the prompt: {block_reason}.",
+ phase=ContentBlockedPhase.INPUT,
+ provider="gemini",
+ original_code=block_reason,
+ request_id=request_id,
+ partial_output=partial_output,
+ )
+
+ candidates = getattr(response, "candidates", None) or []
+ if candidates:
+ finish_reason = _enum_name(
+ getattr(candidates[0], "finish_reason", None),
+ )
+ if finish_reason in _GEMINI_OUTPUT_BLOCK_REASONS:
+ return ContentBlockedError(
+ f"Gemini blocked the response: {finish_reason}.",
+ phase=ContentBlockedPhase.OUTPUT,
+ provider="gemini",
+ original_code=finish_reason,
+ request_id=request_id,
+ partial_output=partial_output,
+ )
+ return None
+
+
def _is_null_schema(schema: Any) -> bool:
"""Return whether a schema represents only JSON null."""
return isinstance(schema, dict) and schema.get("type") in (
@@ -198,6 +269,7 @@ class GeminiChatModel(ChatModelBase):
context_size: int = 1048576,
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
+ raise_on_content_filter: bool = False,
) -> None:
"""Initialize the Gemini chat model.
@@ -226,6 +298,10 @@ class GeminiChatModel(ChatModelBase):
Extra keyword arguments forwarded to ``google.genai.Client``
(e.g. ``vertexai``, ``project``, ``location``,
``credentials``, ``http_options``).
+ raise_on_content_filter (`bool`, defaults to `False`):
+ Raise ``ContentBlockedError`` for supported filter signals.
+ Disabled by default. See ``ChatModelBase.__init__`` for
+ compatibility, structured-output, and stream retry limits.
"""
super().__init__(
credential=credential,
@@ -235,6 +311,7 @@ class GeminiChatModel(ChatModelBase):
max_retries=max_retries,
retry_delay=retry_delay,
context_size=context_size,
+ raise_on_content_filter=raise_on_content_filter,
)
self.formatter = formatter or GeminiChatFormatter()
self.client_kwargs = client_kwargs or {}
@@ -364,6 +441,7 @@ class GeminiChatModel(ChatModelBase):
response_id: str = _generate_id()
text_id: str = _generate_id()
thinking_id: str = _generate_id()
+ has_output = False
async for chunk in response:
# Capture response_id from the first chunk that carries it
@@ -377,6 +455,16 @@ class GeminiChatModel(ChatModelBase):
response_id = getattr(chunk, "response_id", None) or response_id
delta_res.id = response_id
+ if self.raise_on_content_filter:
+ blocked_error = _gemini_content_block_error(
+ chunk,
+ partial_output=has_output,
+ )
+ if blocked_error is not None:
+ if blocked_error.request_id is None:
+ blocked_error.request_id = response_id
+ raise blocked_error
+
if (
chunk.candidates
and chunk.candidates[0].content
@@ -420,6 +508,7 @@ class GeminiChatModel(ChatModelBase):
usage = self._extract_usage(chunk.usage_metadata, start_datetime)
if delta_res.content or usage:
+ has_output = has_output or bool(delta_res.content)
delta_res.usage = usage
yield delta_res
@@ -440,6 +529,11 @@ class GeminiChatModel(ChatModelBase):
`ChatResponse`:
A single ``ChatResponse`` with ``is_last=True``.
"""
+ if self.raise_on_content_filter:
+ blocked_error = _gemini_content_block_error(response)
+ if blocked_error is not None:
+ raise blocked_error
+
content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
if (
diff --git a/src/agentscope/model/_minimax/_model.py b/src/agentscope/model/_minimax/_model.py
index 306a9c977..5402c5509 100644
--- a/src/agentscope/model/_minimax/_model.py
+++ b/src/agentscope/model/_minimax/_model.py
@@ -13,6 +13,8 @@ from ...formatter import FormatterBase, MiniMaxChatFormatter
class MiniMaxChatModel(AnthropicChatModel):
"""Chat model for MiniMax's Anthropic-compatible API."""
+ _content_block_provider = "minimax"
+
type: Literal["minimax_chat"] = "minimax_chat"
"""The type of the chat model."""
@@ -51,6 +53,7 @@ class MiniMaxChatModel(AnthropicChatModel):
context_size: int = 1_000_000,
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
+ raise_on_refusal: bool = False,
) -> None:
"""Initialize the MiniMax chat model.
@@ -74,6 +77,9 @@ class MiniMaxChatModel(AnthropicChatModel):
The formatter used to serialize messages.
client_kwargs (`dict[str, Any] | None`, defaults to `None`):
Extra arguments forwarded to ``anthropic.AsyncAnthropic``.
+ raise_on_refusal (`bool`, defaults to `False`):
+ Whether an explicit MiniMax refusal should raise a
+ ``ContentBlockedError`` instead of remaining normal output.
"""
super().__init__(
credential=credential,
@@ -85,6 +91,7 @@ class MiniMaxChatModel(AnthropicChatModel):
context_size=context_size,
formatter=formatter or MiniMaxChatFormatter(),
client_kwargs=client_kwargs,
+ raise_on_refusal=raise_on_refusal,
)
def _build_thinking_config(
diff --git a/src/agentscope/model/_moonshot/_model.py b/src/agentscope/model/_moonshot/_model.py
index 03c35c8a7..89338940a 100644
--- a/src/agentscope/model/_moonshot/_model.py
+++ b/src/agentscope/model/_moonshot/_model.py
@@ -7,10 +7,15 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
from pydantic import BaseModel, Field
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._content_block import (
+ _normalize_openai_compatible_content_error,
+ _openai_compatible_response_block_error,
+)
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ..._utils._common import _generate_id
from ...credential import MoonshotCredential
+from ...exception import ContentBlockedPhase
from ...formatter import FormatterBase, MoonshotChatFormatter
from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
from ...tool import ToolChoice
@@ -103,6 +108,7 @@ class MoonshotChatModel(ChatModelBase):
context_size: int = 131072,
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
+ raise_on_content_filter: bool = False,
) -> None:
"""Initialize the Moonshot AI chat model.
@@ -131,6 +137,10 @@ class MoonshotChatModel(ChatModelBase):
client_kwargs (`dict[str, Any] | None`, defaults to `None`):
Extra keyword arguments forwarded to ``openai.AsyncClient``
(e.g. ``timeout``, ``default_headers``, ``http_client``).
+ raise_on_content_filter (`bool`, defaults to `False`):
+ Raise ``ContentBlockedError`` for supported filter signals.
+ Disabled by default. See ``ChatModelBase.__init__`` for
+ compatibility, structured-output, and stream retry limits.
"""
super().__init__(
credential=credential,
@@ -140,6 +150,7 @@ class MoonshotChatModel(ChatModelBase):
max_retries=max_retries,
retry_delay=retry_delay,
context_size=context_size,
+ raise_on_content_filter=raise_on_content_filter,
)
self.formatter = formatter or MoonshotChatFormatter()
self.client_kwargs = client_kwargs or {}
@@ -171,6 +182,19 @@ class MoonshotChatModel(ChatModelBase):
return (openai.BadRequestError,)
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Normalize explicit Moonshot content-filter errors."""
+ if not self.raise_on_content_filter:
+ return error
+ normalized = _normalize_openai_compatible_content_error(
+ error,
+ provider="moonshot",
+ blocked_codes={"content_filter"},
+ phase=ContentBlockedPhase.UNKNOWN,
+ code_field="type",
+ )
+ return normalized or error
+
async def _call_api(
self,
model_name: str,
@@ -311,6 +335,7 @@ class MoonshotChatModel(ChatModelBase):
thinking_id: str = _generate_id()
# The mapping from index to tool call id
tool_call_mapping: dict = OrderedDict()
+ has_output = False
async with response as stream:
async for chunk in stream:
@@ -353,6 +378,15 @@ class MoonshotChatModel(ChatModelBase):
continue
choice = chunk.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="moonshot",
+ request_id=response_id,
+ partial_output=has_output,
+ )
+ if blocked_error is not None:
+ raise blocked_error
delta = choice.delta
# Thinking
@@ -393,6 +427,7 @@ class MoonshotChatModel(ChatModelBase):
)
if delta_res.content or usage:
+ has_output = has_output or bool(delta_res.content)
delta_res.usage = usage
yield delta_res
@@ -417,6 +452,14 @@ class MoonshotChatModel(ChatModelBase):
if response.choices:
choice = response.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="moonshot",
+ request_id=getattr(response, "id", None),
+ )
+ if blocked_error is not None:
+ raise blocked_error
reasoning = getattr(choice.message, "reasoning_content", None)
if reasoning:
content_blocks.append(ThinkingBlock(thinking=reasoning))
diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.py
index 111462425..c16d90c41 100644
--- a/src/agentscope/model/_openai_chat/_model.py
+++ b/src/agentscope/model/_openai_chat/_model.py
@@ -14,9 +14,14 @@ from ..._utils._audio import (
)
from ..._utils._common import _generate_id, _flatten_json_schema
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._content_block import (
+ _normalize_openai_compatible_content_error,
+ _openai_compatible_response_block_error,
+)
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...credential import OpenAICredential
+from ...exception import ContentBlockedPhase
from ...formatter import FormatterBase, OpenAIChatFormatter
from ...message import (
Msg,
@@ -129,6 +134,8 @@ class OpenAIChatModel(ChatModelBase):
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
+ raise_on_refusal: bool = False,
+ raise_on_content_filter: bool = False,
) -> None:
"""Initialize the OpenAI chat model.
@@ -159,6 +166,13 @@ class OpenAIChatModel(ChatModelBase):
extra_body (`dict[str, Any] | None`, defaults to `None`):
Additional request body fields forwarded to
OpenAI-compatible APIs.
+ raise_on_refusal (`bool`, defaults to `False`):
+ Whether an explicit OpenAI refusal should raise a
+ ``ContentBlockedError`` instead of remaining normal output.
+ raise_on_content_filter (`bool`, defaults to `False`):
+ Raise ``ContentBlockedError`` for supported filter signals.
+ Disabled by default. See ``ChatModelBase.__init__`` for
+ compatibility, structured-output, and stream retry limits.
"""
super().__init__(
credential=credential,
@@ -168,6 +182,8 @@ class OpenAIChatModel(ChatModelBase):
max_retries=max_retries,
retry_delay=retry_delay,
context_size=context_size,
+ raise_on_content_filter=raise_on_content_filter,
+ raise_on_refusal=raise_on_refusal,
)
self.formatter = formatter or OpenAIChatFormatter()
self.client_kwargs = client_kwargs or {}
@@ -201,6 +217,18 @@ class OpenAIChatModel(ChatModelBase):
return (openai.BadRequestError,)
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Normalize structured OpenAI content-filter errors."""
+ if not self.raise_on_content_filter:
+ return error
+ normalized = _normalize_openai_compatible_content_error(
+ error,
+ provider="openai",
+ blocked_codes={"content_filter"},
+ phase=ContentBlockedPhase.INPUT,
+ )
+ return normalized or error
+
async def _call_api(
self,
model_name: str,
@@ -346,6 +374,7 @@ class OpenAIChatModel(ChatModelBase):
audio_id: str = _generate_id()
# The mapping from index to (tool call id, tool call name)
tool_call_mapping: dict = OrderedDict()
+ has_output = False
async with response as stream:
async for chunk in stream:
@@ -383,6 +412,16 @@ class OpenAIChatModel(ChatModelBase):
continue
choice = chunk.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="openai",
+ request_id=response_id,
+ partial_output=has_output,
+ include_refusal=self.raise_on_refusal,
+ )
+ if blocked_error is not None:
+ raise blocked_error
delta = choice.delta
# Thinking
@@ -397,6 +436,9 @@ class OpenAIChatModel(ChatModelBase):
# Text
delta_text = getattr(delta, "content", None) or ""
+ refusal = getattr(delta, "refusal", None)
+ if not delta_text and isinstance(refusal, str):
+ delta_text = refusal
# Audio (delta.audio.data / delta.audio.transcript). Omni
# models deliver text via ``delta.audio.transcript`` rather
@@ -466,6 +508,7 @@ class OpenAIChatModel(ChatModelBase):
if delta_res.content or usage:
delta_res.usage = usage
+ has_output = has_output or bool(delta_res.content)
yield delta_res
def _parse_completion_response(
@@ -495,6 +538,15 @@ class OpenAIChatModel(ChatModelBase):
if response.choices:
choice = response.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="openai",
+ request_id=getattr(response, "id", None),
+ include_refusal=self.raise_on_refusal,
+ )
+ if blocked_error is not None:
+ raise blocked_error
reasoning = getattr(choice.message, "reasoning_content", None)
if not isinstance(reasoning, str):
reasoning = getattr(choice.message, "reasoning", None)
@@ -504,6 +556,14 @@ class OpenAIChatModel(ChatModelBase):
if choice.message.content:
content_blocks.append(TextBlock(text=choice.message.content))
+ refusal = getattr(choice.message, "refusal", None)
+ if (
+ not choice.message.content
+ and isinstance(refusal, str)
+ and refusal
+ ):
+ content_blocks.append(TextBlock(text=refusal))
+
# Extract audio output (message.audio.data /
# message.audio.transcript)
audio_obj = getattr(choice.message, "audio", None)
diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.py
index 78f493315..8bfb13e5f 100644
--- a/src/agentscope/model/_openai_response/_model.py
+++ b/src/agentscope/model/_openai_response/_model.py
@@ -9,9 +9,14 @@ from pydantic import BaseModel, Field
from ..._utils._common import _generate_id
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._content_block import (
+ _enum_name,
+ _normalize_openai_compatible_content_error,
+)
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...credential import OpenAICredential
+from ...exception import ContentBlockedError, ContentBlockedPhase
from ...formatter import FormatterBase, OpenAIResponseFormatter
from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
from ...tool import ToolChoice
@@ -27,6 +32,106 @@ else:
# kwargs accepted by Chat Completions but NOT by the Responses API.
_RESPONSES_UNSUPPORTED_KWARGS = frozenset({"modalities", "audio"})
+_RESPONSE_REVIEW_ERROR_CODES = frozenset(
+ {
+ "BIO_POLICY",
+ "MISALIGNMENT_POLICY_VIOLATION",
+ },
+)
+_RESPONSE_BLOCK_ERROR_CODES = _RESPONSE_REVIEW_ERROR_CODES | {
+ "IMAGE_CONTENT_POLICY_VIOLATION",
+}
+
+
+def _openai_response_error(
+ error: Any,
+ *,
+ request_id: str | None,
+ partial_output: bool = False,
+) -> ContentBlockedError | None:
+ """Build an error from a recognized Responses API safety code.
+
+ Return ``None`` for a missing or unrecognized ``error.code``; do not
+ classify error text. The returned error has UNKNOWN phase because the
+ code alone does not establish whether input or output was blocked.
+ Copy the caller's ``request_id`` and ``partial_output`` flag unchanged;
+ the latter indicates output emitted before this signal. Mark policy
+ review stops explicitly; the shared exception does not classify codes.
+ """
+ code = _enum_name(getattr(error, "code", None))
+ if code not in _RESPONSE_BLOCK_ERROR_CODES:
+ return None
+ message = getattr(error, "message", None)
+ return ContentBlockedError(
+ message or f"OpenAI blocked the response: {code}.",
+ phase=ContentBlockedPhase.UNKNOWN,
+ provider="openai",
+ original_code=code.casefold(),
+ request_id=request_id,
+ partial_output=partial_output,
+ requires_review=code in _RESPONSE_REVIEW_ERROR_CODES,
+ )
+
+
+def _openai_response_block_error(
+ response: Any,
+ *,
+ partial_output: bool = False,
+ include_refusal: bool = False,
+ include_content_filter: bool = True,
+) -> ContentBlockedError | None:
+ """Build an error from explicit signals on a full Responses object.
+
+ Inspect the content-filter incomplete reason, then the safety error
+ object, then refusal content parts when ``include_refusal=True``.
+ Content filters and safety codes require ``include_content_filter``.
+ They do not depend on the refusal option. Ordinary
+ response text is never scanned for refusal phrases.
+
+ Return ``None`` if no supported signal is present. Otherwise use the
+ response ID and copy ``partial_output``, which the caller sets if output
+ was emitted before this signal. This helper does not consume a stream
+ or raise the returned error.
+ """
+ request_id = getattr(response, "id", None)
+ details = getattr(response, "incomplete_details", None)
+ reason = _enum_name(getattr(details, "reason", None))
+ if include_content_filter and reason == "CONTENT_FILTER":
+ return ContentBlockedError(
+ "OpenAI filtered the generated response.",
+ phase=ContentBlockedPhase.OUTPUT,
+ provider="openai",
+ original_code="content_filter",
+ request_id=request_id,
+ partial_output=partial_output,
+ )
+
+ error = _openai_response_error(
+ getattr(response, "error", None),
+ request_id=request_id,
+ partial_output=partial_output,
+ )
+ if include_content_filter and error is not None:
+ return error
+
+ if include_refusal:
+ for item in getattr(response, "output", []) or []:
+ if getattr(item, "type", None) != "message":
+ continue
+ for part in getattr(item, "content", []) or []:
+ if getattr(part, "type", None) != "refusal":
+ continue
+ refusal = getattr(part, "refusal", None)
+ return ContentBlockedError(
+ refusal or "OpenAI refused to generate the response.",
+ phase=ContentBlockedPhase.OUTPUT,
+ provider="openai",
+ original_code="refusal",
+ request_id=request_id,
+ partial_output=partial_output,
+ )
+
+ return None
def _dump_reasoning_item(item: Any) -> dict[str, Any]:
@@ -119,6 +224,8 @@ class OpenAIResponseModel(ChatModelBase):
context_size: int = 200000,
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
+ raise_on_refusal: bool = False,
+ raise_on_content_filter: bool = False,
) -> None:
"""Initialize the OpenAI Responses API chat model.
@@ -146,6 +253,13 @@ class OpenAIResponseModel(ChatModelBase):
client_kwargs (`dict[str, Any] | None`, defaults to `None`):
Extra keyword arguments forwarded to ``openai.AsyncClient``
(e.g. ``timeout``, ``default_headers``, ``http_client``).
+ raise_on_refusal (`bool`, defaults to `False`):
+ Whether an explicit OpenAI refusal should raise a
+ ``ContentBlockedError`` instead of remaining normal output.
+ raise_on_content_filter (`bool`, defaults to `False`):
+ Raise ``ContentBlockedError`` for supported filter signals.
+ Disabled by default. See ``ChatModelBase.__init__`` for
+ compatibility, structured-output, and stream retry limits.
"""
super().__init__(
credential=credential,
@@ -155,6 +269,8 @@ class OpenAIResponseModel(ChatModelBase):
max_retries=max_retries,
retry_delay=retry_delay,
context_size=context_size,
+ raise_on_content_filter=raise_on_content_filter,
+ raise_on_refusal=raise_on_refusal,
)
self.formatter = formatter or OpenAIResponseFormatter()
self.client_kwargs = client_kwargs or {}
@@ -181,6 +297,26 @@ class OpenAIResponseModel(ChatModelBase):
) -> tuple[Type[Exception], ...]:
return (openai.BadRequestError,)
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Normalize structured OpenAI Responses content-filter errors."""
+ if not self.raise_on_content_filter:
+ return error
+ normalized = _normalize_openai_compatible_content_error(
+ error,
+ provider="openai",
+ blocked_codes={
+ code.casefold() for code in _RESPONSE_BLOCK_ERROR_CODES
+ },
+ phase=ContentBlockedPhase.UNKNOWN,
+ )
+ if normalized is not None:
+ normalized.requires_review = (
+ _enum_name(normalized.original_code)
+ in _RESPONSE_REVIEW_ERROR_CODES
+ )
+ return normalized
+ return error
+
async def _call_api(
self,
model_name: str,
@@ -293,10 +429,25 @@ class OpenAIResponseModel(ChatModelBase):
tool_call_mapping: dict = OrderedDict()
# The item ids of the function calls that received argument text
tool_calls_with_input: set[str] = set()
+ has_output = False
async with response as stream:
async for event in stream:
event_type = event.type
+ if event_type in {
+ "response.failed",
+ "response.incomplete",
+ "response.completed",
+ }:
+ blocked_error = _openai_response_block_error(
+ event.response,
+ include_content_filter=self.raise_on_content_filter,
+ partial_output=has_output,
+ include_refusal=self.raise_on_refusal,
+ )
+ if blocked_error is not None:
+ raise blocked_error
+
# The SDK doesn't raise on these events, so surface them here
if event_type in ("response.failed", "error"):
error = (
@@ -304,12 +455,33 @@ class OpenAIResponseModel(ChatModelBase):
if event_type == "response.failed"
else event
)
+ if event_type == "error" and self.raise_on_content_filter:
+ blocked_error = _openai_response_error(
+ error,
+ request_id=response_id,
+ partial_output=has_output,
+ )
+ if blocked_error is not None:
+ raise blocked_error
raise openai.APIError(
message=error.message if error else "Response failed",
request=stream.response.request,
body=error.model_dump() if error else None,
)
+ if (
+ event_type == "response.refusal.delta"
+ and self.raise_on_refusal
+ ):
+ raise ContentBlockedError(
+ "OpenAI refused to generate the response.",
+ phase=ContentBlockedPhase.OUTPUT,
+ provider="openai",
+ original_code="refusal",
+ request_id=response_id,
+ partial_output=has_output,
+ )
+
delta_res = ChatResponse(
content=[],
is_last=False,
@@ -449,6 +621,7 @@ class OpenAIResponseModel(ChatModelBase):
)
if delta_res.content or usage:
+ has_output = has_output or bool(delta_res.content)
delta_res.usage = usage
yield delta_res
@@ -469,6 +642,14 @@ class OpenAIResponseModel(ChatModelBase):
`ChatResponse`:
A single ``ChatResponse`` with ``is_last=True``.
"""
+ blocked_error = _openai_response_block_error(
+ response,
+ include_content_filter=self.raise_on_content_filter,
+ include_refusal=self.raise_on_refusal,
+ )
+ if blocked_error is not None:
+ raise blocked_error
+
content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
for item in response.output:
diff --git a/src/agentscope/model/_volcengine/_model.py b/src/agentscope/model/_volcengine/_model.py
index 49246cc14..4a7d8b2b5 100644
--- a/src/agentscope/model/_volcengine/_model.py
+++ b/src/agentscope/model/_volcengine/_model.py
@@ -8,10 +8,15 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
from pydantic import BaseModel, Field
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._content_block import (
+ _normalize_openai_compatible_content_error,
+ _openai_compatible_response_block_error,
+)
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ..._utils._common import _generate_id
from ...credential import VolcengineCredential
+from ...exception import ContentBlockedPhase
from ...formatter import FormatterBase, VolcengineChatFormatter
from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
from ...tool import ToolChoice
@@ -88,6 +93,7 @@ class VolcengineChatModel(ChatModelBase):
context_size: int = 256000,
formatter: FormatterBase | None = None,
client_kwargs: dict[str, Any] | None = None,
+ raise_on_content_filter: bool = False,
) -> None:
"""Initialize the Volcengine Ark chat model.
@@ -116,6 +122,10 @@ class VolcengineChatModel(ChatModelBase):
client_kwargs (`dict[str, Any] | None`, defaults to `None`):
Extra keyword arguments forwarded to ``openai.AsyncClient``
(e.g. ``timeout``, ``default_headers``, ``http_client``).
+ raise_on_content_filter (`bool`, defaults to `False`):
+ Raise ``ContentBlockedError`` for supported filter signals.
+ Disabled by default. See ``ChatModelBase.__init__`` for
+ compatibility, structured-output, and stream retry limits.
"""
super().__init__(
credential=credential,
@@ -125,6 +135,7 @@ class VolcengineChatModel(ChatModelBase):
max_retries=max_retries,
retry_delay=retry_delay,
context_size=context_size,
+ raise_on_content_filter=raise_on_content_filter,
)
self.formatter = formatter or VolcengineChatFormatter()
self.client_kwargs = client_kwargs or {}
@@ -156,6 +167,38 @@ class VolcengineChatModel(ChatModelBase):
return (openai.BadRequestError,)
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Normalize explicit Volcengine content-filter errors."""
+ if not self.raise_on_content_filter:
+ return error
+ for phase, codes in (
+ (
+ ContentBlockedPhase.INPUT,
+ {
+ "sensitivecontentdetected",
+ "sensitivecontentdetected.severeviolation",
+ "sensitivecontentdetected.violence",
+ "inputtextsensitivecontentdetected",
+ "inputtextsensitivecontentdetected.policyviolation",
+ "inputimagesensitivecontentdetected",
+ "inputimagesensitivecontentdetected.policyviolation",
+ },
+ ),
+ (
+ ContentBlockedPhase.OUTPUT,
+ {"outputtextsensitivecontentdetected"},
+ ),
+ ):
+ normalized = _normalize_openai_compatible_content_error(
+ error,
+ provider="volcengine",
+ blocked_codes=codes,
+ phase=phase,
+ )
+ if normalized is not None:
+ return normalized
+ return error
+
async def _call_api(
self,
model_name: str,
@@ -263,6 +306,7 @@ class VolcengineChatModel(ChatModelBase):
thinking_id: str = _generate_id()
# The mapping from index to tool call id
tool_call_mapping: dict = OrderedDict()
+ has_output = False
async with response as stream:
async for chunk in stream:
@@ -302,6 +346,15 @@ class VolcengineChatModel(ChatModelBase):
continue
choice = chunk.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="volcengine",
+ request_id=response_id,
+ partial_output=has_output,
+ )
+ if blocked_error is not None:
+ raise blocked_error
delta = choice.delta
# Thinking block
@@ -342,6 +395,7 @@ class VolcengineChatModel(ChatModelBase):
)
if delta_res.content or usage:
+ has_output = has_output or bool(delta_res.content)
delta_res.usage = usage
yield delta_res
@@ -366,6 +420,14 @@ class VolcengineChatModel(ChatModelBase):
if response.choices:
choice = response.choices[0]
+ blocked_error = _openai_compatible_response_block_error(
+ choice,
+ include_content_filter=self.raise_on_content_filter,
+ provider="volcengine",
+ request_id=getattr(response, "id", None),
+ )
+ if blocked_error is not None:
+ raise blocked_error
reasoning = getattr(choice.message, "reasoning_content", None)
if isinstance(reasoning, str) and reasoning:
content_blocks.append(ThinkingBlock(thinking=reasoning))
diff --git a/tests/agent_content_block_test.py b/tests/agent_content_block_test.py
new file mode 100644
index 000000000..85e5fbd51
--- /dev/null
+++ b/tests/agent_content_block_test.py
@@ -0,0 +1,288 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for content-block errors without recovery middleware."""
+from copy import deepcopy
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import MockModel
+
+from agentscope.agent import Agent, InjectionConfig, ModelConfig
+from agentscope.exception import ContentBlockedError, ContentBlockedPhase
+from agentscope.message import Msg, TextBlock, UserMsg
+from agentscope.model import ChatResponse
+
+
+class _TrackingModel(MockModel):
+ """Record model inputs to verify unchanged request retries."""
+
+ def __init__(self) -> None:
+ """Initialize the recorded model inputs."""
+ super().__init__()
+ self.received_messages: list[list[Msg]] = []
+
+ async def _call_api(self, *args: Any, **kwargs: Any) -> Any:
+ """Record the input before returning a deterministic response."""
+ self.received_messages.append(deepcopy(kwargs["messages"]))
+ return await super()._call_api(*args, **kwargs)
+
+
+class _NormalizingModel(MockModel):
+ """Translate simulated SDK errors into normalized input blocks."""
+
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Return a content block with the original error's message."""
+ return ContentBlockedError(
+ f"{error}",
+ phase=ContentBlockedPhase.INPUT,
+ )
+
+
+def _response(text: str, *, is_last: bool = True) -> ChatResponse:
+ """Build a deterministic response for whole and streamed calls."""
+ return ChatResponse(
+ content=[TextBlock(id="text-1", text=text)],
+ is_last=is_last,
+ )
+
+
+class AgentContentBlockTest(IsolatedAsyncioTestCase):
+ """Verify phase-aware retry, stream observation, and error identity."""
+
+ def _agent(self, model: MockModel, *, retries: int = 0) -> Agent:
+ """Build an agent without any middleware."""
+ return Agent(
+ name="test-agent",
+ system_prompt="test",
+ model=model,
+ model_config=ModelConfig(max_retries=retries),
+ injection_config=InjectionConfig(inject_runtime_state=False),
+ )
+
+ def test_error_exposes_normalized_fields(self) -> None:
+ """Errors expose the complete provider-independent structure."""
+ error = ContentBlockedError(
+ "blocked",
+ phase=ContentBlockedPhase.INPUT,
+ provider="test",
+ original_code="blocked_input",
+ request_id="request-1",
+ partial_output=True,
+ )
+ self.assertEqual(
+ vars(error),
+ {
+ "message": "blocked",
+ "phase": ContentBlockedPhase.INPUT,
+ "provider": "test",
+ "original_code": "blocked_input",
+ "request_id": "request-1",
+ "partial_output": True,
+ "requires_review": False,
+ },
+ )
+
+ def test_review_flag_is_not_inferred_from_provider_codes(self) -> None:
+ """Only explicit adapter decisions set the provider-neutral flag."""
+ for provider, code in (
+ ("openai", "bio_policy"),
+ ("openai", "misalignment_policy_violation"),
+ ("custom", "review_required"),
+ ):
+ with self.subTest(provider=provider, code=code):
+ default = ContentBlockedError(
+ "blocked",
+ provider=provider,
+ original_code=code,
+ )
+ explicit = ContentBlockedError(
+ "blocked",
+ provider=provider,
+ original_code=code,
+ requires_review=True,
+ )
+ self.assertEqual(
+ (default.requires_review, explicit.requires_review),
+ (False, True),
+ )
+
+ async def test_model_normalization_preserves_cause(self) -> None:
+ """Both immediate and streamed SDK errors preserve their cause."""
+ for streamed in (False, True):
+ with self.subTest(streamed=streamed):
+ original = RuntimeError("provider error")
+ model = _NormalizingModel()
+ if streamed:
+ model.set_responses([[original]])
+ else:
+ model.set_responses([original])
+ with self.assertRaises(ContentBlockedError) as caught:
+ result = await model(messages=[])
+ if streamed:
+ async for _ in result:
+ pass
+ self.assertEqual(
+ (caught.exception.__cause__, model.cnt),
+ (original, 1),
+ )
+
+ async def test_phase_controls_same_payload_retries(self) -> None:
+ """Only OUTPUT blocks can resample an unchanged request."""
+ for phase in ContentBlockedPhase:
+ with self.subTest(phase=phase):
+ error = ContentBlockedError("blocked", phase=phase)
+ model = _TrackingModel()
+ success = _response("success")
+ model.set_responses([error, success])
+ agent = self._agent(model, retries=1)
+ messages = [UserMsg(name="user", content="request")]
+ if phase == ContentBlockedPhase.OUTPUT:
+ result = await agent._call_model(messages, tools=[])
+ self.assertEqual(
+ (result, model.received_messages),
+ (success, [messages, messages]),
+ )
+ else:
+ with self.assertRaises(ContentBlockedError) as caught:
+ await agent._call_model(messages, tools=[])
+ self.assertEqual(
+ (caught.exception, model.received_messages),
+ (error, [messages]),
+ )
+
+ async def test_partial_output_and_review_stop_replay(self) -> None:
+ """Partial output and review stops prevent retries and fallback."""
+ cases = (
+ ContentBlockedError(
+ "blocked",
+ phase=ContentBlockedPhase.OUTPUT,
+ partial_output=True,
+ ),
+ ContentBlockedError(
+ "blocked",
+ provider="openai",
+ original_code="misalignment_policy_violation",
+ requires_review=True,
+ ),
+ ContentBlockedError(
+ "blocked",
+ provider="openai",
+ original_code="BIO_POLICY",
+ requires_review=True,
+ ),
+ ContentBlockedError(
+ "blocked",
+ phase=ContentBlockedPhase.OUTPUT,
+ provider="custom",
+ requires_review=True,
+ ),
+ )
+ for error in cases:
+ with self.subTest(error=vars(error)):
+ model = MockModel()
+ model.set_responses([error, _response("unexpected")])
+ fallback = MockModel()
+ fallback.set_responses([_response("unexpected fallback")])
+ agent = self._agent(model, retries=3)
+ agent.model_config.fallback_model = fallback
+ with self.assertRaises(ContentBlockedError) as caught:
+ await agent._call_model(messages=[], tools=[])
+ self.assertEqual(
+ (caught.exception, model.cnt, fallback.cnt),
+ (error, 1, 0),
+ )
+
+ async def test_output_retry_budget_is_bounded(self) -> None:
+ """Repeated OUTPUT blocks stop at the existing agent retry limit."""
+ model = MockModel()
+ errors = [
+ ContentBlockedError("blocked", phase=ContentBlockedPhase.OUTPUT)
+ for _ in range(3)
+ ]
+ model.set_responses(errors)
+ agent = self._agent(model, retries=2)
+ with self.assertRaises(ContentBlockedError) as caught:
+ await agent._call_model(messages=[], tools=[])
+ self.assertEqual((caught.exception, model.cnt), (errors[-1], 3))
+
+ async def test_agent_preserves_normalized_error_cause(self) -> None:
+ """The agent retains the SDK error attached by normalization."""
+ original = RuntimeError("provider error")
+ model = _NormalizingModel()
+ model.set_responses([original])
+ agent = self._agent(model)
+ with self.assertRaises(ContentBlockedError) as caught:
+ await agent._call_model(messages=[], tools=[])
+ self.assertEqual(
+ (caught.exception.__cause__, model.cnt),
+ (original, 1),
+ )
+
+ async def test_ordinary_error_keeps_existing_retry(self) -> None:
+ """Ordinary failures retain the existing same-payload retry."""
+ model = MockModel()
+ success = _response("retried")
+ model.set_responses([RuntimeError("temporary failure"), success])
+ result = await self._agent(model, retries=1)._call_model(
+ messages=[],
+ tools=[],
+ )
+ self.assertEqual((result, model.cnt), (success, 2))
+
+ async def test_stream_errors_do_not_retry_or_switch_models(self) -> None:
+ """All stream phases retain accurate partial-output state."""
+ for phase in ContentBlockedPhase:
+ for partial in (False, True):
+ with self.subTest(phase=phase, partial=partial):
+ error = ContentBlockedError("blocked", phase=phase)
+ chunks = (
+ [_response("partial", is_last=False)]
+ if partial
+ else []
+ )
+ model = MockModel()
+ model.set_responses([[*chunks, error]])
+ fallback = MockModel()
+ fallback.set_responses([_response("unexpected")])
+ agent = self._agent(model, retries=3)
+ agent.model_config.fallback_model = fallback
+ stream = await agent._call_model(messages=[], tools=[])
+ seen = []
+ with self.assertLogs("as", level="WARNING") as logs:
+ with self.assertRaises(ContentBlockedError) as caught:
+ async for chunk in stream:
+ seen.append(chunk)
+ self.assertEqual(
+ (
+ seen,
+ caught.exception,
+ error.partial_output,
+ model.cnt,
+ fallback.cnt,
+ ),
+ (chunks, error, partial, 1, 0),
+ )
+ self.assertIn(
+ "during stream consumption",
+ "\n".join(logs.output),
+ )
+
+ async def test_closing_observer_closes_delegated_stream(self) -> None:
+ """Early consumer closure deterministically closes the inner stream."""
+ closed = []
+ expected = _response("first", is_last=False)
+
+ async def stream() -> Any:
+ """Record cleanup of a partially consumed provider stream."""
+ try:
+ yield expected
+ yield _response("second", is_last=False)
+ finally:
+ closed.append(True)
+
+ model = MockModel()
+ observed = self._agent(model)._observe_model_stream(stream(), model)
+ first = await anext(observed)
+ self.assertEqual((first, closed), (expected, []))
+ await observed.aclose()
+ self.assertEqual(closed, [True])
diff --git a/tests/compress_context_test.py b/tests/compress_context_test.py
index 7e3abd16a..c4837c8dc 100644
--- a/tests/compress_context_test.py
+++ b/tests/compress_context_test.py
@@ -6,15 +6,17 @@ import json
import os
import tempfile
from datetime import datetime
+from itertools import product
from typing import Any
from unittest.async_case import IsolatedAsyncioTestCase
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
from utils import MockModel, AnyString
from agentscope.model import ChatResponse, ChatUsage, StructuredResponse
from agentscope.agent import Agent, ContextConfig, InjectionConfig
+from agentscope.exception import ContentBlockedError
from agentscope.state import AgentState
from agentscope.message import (
UserMsg,
@@ -2830,6 +2832,66 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
self.assertEqual(agent.state, expected_state)
+ async def test_content_block_stops_compression(self) -> None:
+ """Stop errors survive every compression entry and failure path."""
+ cases = product(
+ ("requires_review", "partial_output"),
+ ((False, False), (True, False), (True, True)),
+ (False, True),
+ (False, True),
+ )
+ for flag, (overflow, retry), via_tool, truncate in cases:
+ with self.subTest(
+ flag=flag,
+ overflow=overflow,
+ retry=retry,
+ via_tool=via_tool,
+ truncate=truncate,
+ ):
+ agent, model = _make_failing_compression_agent()
+ agent.context_config.compression_fallback_to_truncation = (
+ truncate
+ )
+ expected_state = agent.state.model_copy(deep=True)
+ error = ContentBlockedError("blocked", **{flag: True})
+ errors = (
+ [RuntimeError("temporary failure"), error]
+ if retry
+ else [error]
+ )
+ with (
+ patch.object(
+ model,
+ "count_tokens",
+ new=AsyncMock(return_value=200 if overflow else 95),
+ ),
+ patch.object(
+ agent,
+ "_split_context_for_compression",
+ new=AsyncMock(
+ return_value=(
+ agent.state.context[:1],
+ agent.state.context[1:],
+ ),
+ ),
+ ),
+ patch.object(
+ model,
+ "_call_api_with_structured_output",
+ new=AsyncMock(side_effect=errors),
+ ) as call,
+ ):
+ with self.assertRaises(ContentBlockedError) as caught:
+ if via_tool:
+ await agent._compress_context_tool()
+ else:
+ await agent.compress_context()
+
+ self.assertEqual(
+ (caught.exception, call.await_count, agent.state),
+ (error, len(errors), expected_state),
+ )
+
async def test_summary_failure_raises_without_truncation_fallback(
self,
) -> None:
diff --git a/tests/model_base_test.py b/tests/model_base_test.py
index cf7780588..3b8f597fe 100644
--- a/tests/model_base_test.py
+++ b/tests/model_base_test.py
@@ -24,7 +24,11 @@ from agentscope.model import (
FinishedReason,
StructuredResponse,
)
-from agentscope.exception import StructuredOutputError
+from agentscope.exception import (
+ ContentBlockedError,
+ ContentBlockedPhase,
+ StructuredOutputError,
+)
from agentscope.tool import ToolChoice
@@ -1289,6 +1293,83 @@ class StructuredOutputStrategyTest(IsolatedAsyncioTestCase):
),
)
+ async def test_content_block_is_normalized_before_fallback(self) -> None:
+ """A blocked request does not traverse output strategies."""
+
+ class _NormalizingStructuredModel(
+ StructuredOutputStrategyMockModel,
+ ):
+ """Normalize the simulated provider bad request."""
+
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Translate the provider error into a content block."""
+ return ContentBlockedError(
+ "blocked",
+ phase=ContentBlockedPhase.INPUT,
+ provider="test",
+ original_code="content_filter",
+ )
+
+ original = _BadRequestError("input blocked")
+ model = _NormalizingStructuredModel(responses=[original])
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ await model.generate_structured_output(
+ self.messages,
+ self.schema,
+ )
+
+ self.assertIs(raised.exception.__cause__, original)
+ self.assertEqual(
+ model.structured_calls,
+ [("generate_structured_output", {})],
+ )
+
+ async def test_normalized_retryable_error_is_retried(self) -> None:
+ """Structured output classifies the normalized exception."""
+
+ class _RetryableError(Exception):
+ """A normalized transient provider error."""
+
+ class _NormalizingStructuredModel(
+ StructuredOutputStrategyMockModel,
+ ):
+ """Normalize a provider failure into a retryable error."""
+
+ @classmethod
+ def _get_retryable_exceptions(
+ cls,
+ ) -> tuple[type[Exception], ...]:
+ """Declare the normalized transient error retryable."""
+ return (_RetryableError,)
+
+ def _normalize_exception(self, error: Exception) -> Exception:
+ """Translate the provider error into a transient error."""
+ return _RetryableError(str(error))
+
+ model = _NormalizingStructuredModel(
+ responses=[
+ _BadRequestError("temporary provider failure"),
+ StructuredResponse(content={}),
+ ],
+ )
+ model.max_retries = 1
+ model.retry_delay = 0
+
+ result = await model.generate_structured_output(
+ self.messages,
+ self.schema,
+ )
+
+ self.assertDictEqual(result.content, {})
+ self.assertEqual(
+ model.structured_calls,
+ [
+ ("generate_structured_output", {}),
+ ("generate_structured_output", {}),
+ ],
+ )
+
async def test_final_error_is_chained_from_first_error(self) -> None:
"""The first provider failure remains visible as the root cause."""
first_error = _BadRequestError("tool_choice is unsupported")
diff --git a/tests/model_content_block_test.py b/tests/model_content_block_test.py
new file mode 100644
index 000000000..b87ae1843
--- /dev/null
+++ b/tests/model_content_block_test.py
@@ -0,0 +1,1290 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for provider content-block normalization."""
+from datetime import datetime
+from types import SimpleNamespace
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import openai
+from pydantic import BaseModel
+
+from agentscope.credential import (
+ AnthropicCredential,
+ DashScopeCredential,
+ DeepSeekCredential,
+ GeminiCredential,
+ MiniMaxCredential,
+ MoonshotCredential,
+ OpenAICredential,
+ VolcengineCredential,
+)
+from agentscope.exception import ContentBlockedError, ContentBlockedPhase
+from agentscope.message import TextBlock, UserMsg
+from agentscope.model import (
+ AnthropicChatModel,
+ ChatResponse,
+ DashScopeChatModel,
+ DeepSeekChatModel,
+ GeminiChatModel,
+ MiniMaxChatModel,
+ MoonshotChatModel,
+ OpenAIChatModel,
+ OpenAIResponseModel,
+ StructuredResponse,
+ VolcengineChatModel,
+)
+
+
+class _ProviderError(Exception):
+ """A structured OpenAI-compatible provider error."""
+
+ def __init__(self, body: dict, request_id: str) -> None:
+ """Initialize the structured error payload."""
+ super().__init__(body["message"])
+ self.body = body
+ self.request_id = request_id
+
+
+class _Stream:
+ """An async context-managed stream over fixed chunks."""
+
+ def __init__(self, chunks: list) -> None:
+ """Initialize the stream chunks."""
+ self._chunks = iter(chunks)
+ self.response = SimpleNamespace(request=None)
+
+ async def __aenter__(self) -> "_Stream":
+ """Enter the stream context."""
+ return self
+
+ async def __aexit__(self, *args: object) -> None:
+ """Exit the stream context."""
+
+ def __aiter__(self) -> "_Stream":
+ """Return the asynchronous iterator."""
+ return self
+
+ async def __anext__(self) -> Any:
+ """Return the next chunk."""
+ try:
+ return next(self._chunks)
+ except StopIteration as error:
+ raise StopAsyncIteration from error
+
+
+def _model_with_filters(model_class: type) -> Any:
+ """Create a parser-only model with explicit filter opt-in."""
+ model = object.__new__(model_class)
+ model.raise_on_content_filter = True
+ model.raise_on_refusal = False
+ return model
+
+
+class ContentBlockCompatibilityTest(IsolatedAsyncioTestCase):
+ """Verify opt-in filtering and backward-compatible default behavior."""
+
+ def test_sdk_normalization_switch_and_provider_fields(self) -> None:
+ """Known provider payloads normalize only with explicit opt-in."""
+ cases: tuple[
+ tuple[type, str, dict[str, Any], ContentBlockedPhase],
+ ...,
+ ] = (
+ (
+ OpenAIChatModel,
+ "openai",
+ {"code": "content_filter"},
+ ContentBlockedPhase.INPUT,
+ ),
+ (
+ DashScopeChatModel,
+ "dashscope",
+ {"code": "DataInspectionFailed"},
+ ContentBlockedPhase.UNKNOWN,
+ ),
+ (
+ MoonshotChatModel,
+ "moonshot",
+ {"code": 400, "type": "content_filter"},
+ ContentBlockedPhase.UNKNOWN,
+ ),
+ (
+ VolcengineChatModel,
+ "volcengine",
+ {"code": "OutputTextSensitiveContentDetected"},
+ ContentBlockedPhase.OUTPUT,
+ ),
+ (
+ OpenAIResponseModel,
+ "openai",
+ {"code": "bio_policy"},
+ ContentBlockedPhase.UNKNOWN,
+ ),
+ (
+ OpenAIResponseModel,
+ "openai",
+ {"code": "misalignment_policy_violation"},
+ ContentBlockedPhase.UNKNOWN,
+ ),
+ )
+ for model_class, provider, fields, phase in cases:
+ for enabled in (False, True):
+ with self.subTest(model=model_class, enabled=enabled):
+ model = _model_with_filters(model_class)
+ model.raise_on_content_filter = enabled
+ original = _ProviderError(
+ {
+ "message": "outer",
+ "error": {**fields, "message": "inner"},
+ },
+ "request-id",
+ )
+ normalized = model._normalize_exception(original)
+ if not enabled:
+ self.assertIs(normalized, original)
+ continue
+ code = fields.get("type", fields["code"])
+ self.assertEqual(
+ {
+ "message": normalized.message,
+ "provider": normalized.provider,
+ "phase": normalized.phase,
+ "original_code": normalized.original_code,
+ "request_id": normalized.request_id,
+ "partial_output": normalized.partial_output,
+ "requires_review": normalized.requires_review,
+ },
+ {
+ "message": "inner",
+ "provider": provider,
+ "phase": phase,
+ "original_code": code,
+ "request_id": "request-id",
+ "partial_output": False,
+ "requires_review": code
+ in {
+ "bio_policy",
+ "misalignment_policy_violation",
+ },
+ },
+ )
+
+ async def test_stream_refusal_uses_stable_diagnostic(self) -> None:
+ """Do not present the first refusal fragment as a full explanation."""
+ for model_class, response, expected in (
+ (
+ OpenAIChatModel,
+ SimpleNamespace(
+ id="refusal",
+ usage=None,
+ choices=[
+ SimpleNamespace(
+ finish_reason=None,
+ delta=SimpleNamespace(refusal="I"),
+ ),
+ ],
+ ),
+ "openai refused the response.",
+ ),
+ (
+ OpenAIResponseModel,
+ SimpleNamespace(type="response.refusal.delta", delta="I"),
+ "OpenAI refused to generate the response.",
+ ),
+ ):
+ with self.subTest(model=model_class):
+ model = _model_with_filters(model_class)
+ model.raise_on_content_filter = False
+ model.raise_on_refusal = True
+ with self.assertRaises(ContentBlockedError) as caught:
+ async for _ in model._parse_stream_response(
+ datetime.now(),
+ _Stream([response]),
+ ):
+ pass
+ self.assertEqual(
+ (
+ caught.exception.message,
+ caught.exception.partial_output,
+ ),
+ (expected, False),
+ )
+
+ def test_content_filter_constructor_defaults_and_opt_in(self) -> None:
+ """All filter-aware adapters require an explicit opt-in."""
+ providers = (
+ (OpenAIChatModel, OpenAICredential, "openai.AsyncClient"),
+ (OpenAIResponseModel, OpenAICredential, "openai.AsyncClient"),
+ (DashScopeChatModel, DashScopeCredential, "openai.AsyncClient"),
+ (DeepSeekChatModel, DeepSeekCredential, "openai.AsyncClient"),
+ (MoonshotChatModel, MoonshotCredential, "openai.AsyncClient"),
+ (VolcengineChatModel, VolcengineCredential, "openai.AsyncClient"),
+ (GeminiChatModel, GeminiCredential, "google.genai.Client"),
+ )
+ for model_class, credential_class, client_path in providers:
+ for options in ({}, {"raise_on_content_filter": True}):
+ with self.subTest(model=model_class, options=options):
+ with patch(client_path):
+ model = model_class(
+ credential=credential_class(api_key="test"),
+ model="test-model",
+ **options,
+ )
+ self.assertEqual(
+ model.raise_on_content_filter,
+ options.get("raise_on_content_filter", False),
+ )
+
+ async def test_default_chat_filter_retains_same_chunk_content(
+ self,
+ ) -> None:
+ """Legacy parsing retains content accompanying a filter signal."""
+ fields = {
+ "content": "partial content",
+ "refusal": None,
+ "reasoning_content": None,
+ "reasoning": None,
+ "audio": None,
+ "tool_calls": None,
+ }
+ for model_class in (
+ OpenAIChatModel,
+ DashScopeChatModel,
+ DeepSeekChatModel,
+ MoonshotChatModel,
+ VolcengineChatModel,
+ ):
+ for streaming in (False, True):
+ for enabled in (False, True):
+ with self.subTest(
+ model=model_class,
+ streaming=streaming,
+ enabled=enabled,
+ ):
+ model = _model_with_filters(model_class)
+ model.raise_on_content_filter = enabled
+ choice = SimpleNamespace(
+ finish_reason="content_filter",
+ message=SimpleNamespace(**fields),
+ delta=SimpleNamespace(**fields),
+ )
+ response = SimpleNamespace(
+ id="filtered",
+ choices=[choice],
+ usage=None,
+ )
+
+ async def parse(
+ model: Any = model,
+ response: Any = response,
+ streaming: bool = streaming,
+ ) -> list:
+ if streaming:
+ stream = model._parse_stream_response(
+ datetime.now(),
+ _Stream([response]),
+ )
+ return [chunk async for chunk in stream]
+ return [
+ model._parse_completion_response(
+ datetime.now(),
+ response,
+ ),
+ ]
+
+ if enabled:
+ with self.assertRaises(
+ ContentBlockedError,
+ ) as caught:
+ await parse()
+ self.assertEqual(
+ caught.exception.partial_output,
+ False,
+ )
+ else:
+ parsed = await parse()
+ self.assertEqual(
+ [b.text for r in parsed for b in r.content],
+ ["partial content"],
+ )
+
+ async def test_disabled_gemini_filter_skips_inspection(self) -> None:
+ """The disabled switch avoids inspecting filter signals entirely."""
+ model = _model_with_filters(GeminiChatModel)
+ model.raise_on_content_filter = False
+ response = SimpleNamespace(
+ response_id="gemini-filter",
+ candidates=[],
+ usage_metadata=None,
+ )
+ with patch(
+ "agentscope.model._gemini._model._gemini_content_block_error",
+ ) as inspect_block:
+ parsed = model._parse_completion_response(datetime.now(), response)
+ chunks = [
+ chunk
+ async for chunk in model._parse_stream_response(
+ datetime.now(),
+ _Stream([response]),
+ )
+ ]
+ self.assertEqual((parsed.content, chunks), ([], []))
+ inspect_block.assert_not_called()
+
+ async def test_default_gemini_and_responses_filters_are_not_errors(
+ self,
+ ) -> None:
+ """Default mode preserves incomplete and safety-blocked responses."""
+ model = _model_with_filters(GeminiChatModel)
+ model.raise_on_content_filter = False
+ for reason in (
+ "SAFETY",
+ "BLOCKLIST",
+ "PROHIBITED_CONTENT",
+ "SPII",
+ "IMAGE_SAFETY",
+ ):
+ with self.subTest(reason=reason):
+ response = SimpleNamespace(
+ response_id="gemini-filter",
+ prompt_feedback=SimpleNamespace(block_reason=reason),
+ candidates=[],
+ usage_metadata=None,
+ )
+ parsed = model._parse_completion_response(
+ datetime.now(),
+ response,
+ )
+ self.assertEqual(parsed.content, [])
+ chunks = [
+ c
+ async for c in model._parse_stream_response(
+ datetime.now(),
+ _Stream([response]),
+ )
+ ]
+ self.assertEqual(chunks, [])
+
+ model = _model_with_filters(OpenAIResponseModel)
+ model.raise_on_content_filter = False
+ response = SimpleNamespace(
+ id="filtered-response",
+ incomplete_details=SimpleNamespace(reason="content_filter"),
+ error=None,
+ output=[
+ SimpleNamespace(
+ type="message",
+ content=[
+ SimpleNamespace(type="output_text", text="partial"),
+ ],
+ ),
+ ],
+ usage=None,
+ )
+ parsed = model._parse_completion_response(datetime.now(), response)
+ self.assertEqual([b.text for b in parsed.content], ["partial"])
+ chunks = [
+ c
+ async for c in model._parse_stream_response(
+ datetime.now(),
+ _Stream(
+ [
+ SimpleNamespace(
+ type="response.output_text.delta",
+ delta="partial",
+ item_id="message-1",
+ content_index=0,
+ ),
+ SimpleNamespace(
+ type="response.incomplete",
+ response=response,
+ ),
+ ],
+ ),
+ )
+ ]
+ self.assertEqual(
+ [b.text for c in chunks for b in c.content],
+ ["partial"],
+ )
+
+ async def test_dashscope_structured_output_opt_in(self) -> None:
+ """Disabled normalization preserves legacy strategy fallback."""
+ messages = [UserMsg(name="user", content="Return an empty object.")]
+ for enabled in (False, True):
+ with self.subTest(enabled=enabled):
+ with patch("openai.AsyncClient"):
+ model = DashScopeChatModel(
+ credential=DashScopeCredential(api_key="test"),
+ model="test",
+ max_retries=0,
+ raise_on_content_filter=enabled,
+ )
+ original = openai.BadRequestError(
+ "inspection failed",
+ response=httpx.Response(
+ 400,
+ request=httpx.Request("POST", "https://example.com"),
+ ),
+ body={"code": "DataInspectionFailed"},
+ )
+ expected = StructuredResponse(content={})
+ with patch.object(
+ model,
+ "_call_api_with_structured_output",
+ new=AsyncMock(side_effect=[original, expected]),
+ ) as call:
+ if enabled:
+ with self.assertRaises(ContentBlockedError) as caught:
+ await model.generate_structured_output(
+ messages,
+ BaseModel,
+ )
+ self.assertIs(caught.exception.__cause__, original)
+ self.assertEqual(call.await_count, 1)
+ else:
+ result = await model.generate_structured_output(
+ messages,
+ BaseModel,
+ )
+ self.assertEqual(
+ (result, call.await_count),
+ (expected, 2),
+ )
+
+ async def test_sdk_stream_error_tracks_visible_output(self) -> None:
+ """SDK errors track emitted chunks without middleware."""
+ for visible in (False, True):
+ for enabled in (False, True):
+ with self.subTest(visible=visible, enabled=enabled):
+ with patch("openai.AsyncClient"):
+ model = DashScopeChatModel(
+ credential=DashScopeCredential(api_key="test"),
+ model="test",
+ raise_on_content_filter=enabled,
+ )
+ original = _ProviderError(
+ {"code": "DataInspectionFailed", "message": "blocked"},
+ "request-1",
+ )
+
+ async def stream(
+ visible: bool = visible,
+ error: Exception = original,
+ ) -> Any:
+ yield ChatResponse(
+ content=[TextBlock(text="partial")]
+ if visible
+ else [],
+ is_last=False,
+ )
+ raise error
+
+ with patch.object(
+ model,
+ "_call_api",
+ return_value=stream(),
+ ):
+ result = await model(messages=[])
+ chunks = []
+ with self.assertRaises(
+ ContentBlockedError if enabled else _ProviderError,
+ ) as caught:
+ async for chunk in result:
+ chunks.append(chunk)
+ self.assertEqual(
+ [b.text for c in chunks for b in c.content],
+ ["partial"] if visible else [],
+ )
+ if enabled:
+ self.assertEqual(
+ (
+ caught.exception.partial_output,
+ caught.exception.__cause__,
+ ),
+ (visible, original),
+ )
+ else:
+ self.assertIs(caught.exception, original)
+
+ def test_unverified_error_codes_remain_sdk_errors(self) -> None:
+ """Do not infer exception codes from compatible finish reasons."""
+ for model_class, body in (
+ (DeepSeekChatModel, {"code": "content_filter"}),
+ (OpenAIResponseModel, {"code": "content_filter"}),
+ (MoonshotChatModel, {"code": "content_filter"}),
+ (VolcengineChatModel, {"code": "content_filter"}),
+ (
+ VolcengineChatModel,
+ {"code": "InputTextSensitiveContentDetected.Unknown"},
+ ),
+ ):
+ with self.subTest(model=model_class, body=body):
+ model = _model_with_filters(model_class)
+ error = _ProviderError(
+ {**body, "message": "blocked"},
+ "request",
+ )
+ self.assertIs(model._normalize_exception(error), error)
+
+
+class ModelContentBlockTest(IsolatedAsyncioTestCase):
+ """Test structured content-block signals from supported providers."""
+
+ def test_refusal_option_defaults_and_opt_in(self) -> None:
+ """Each supported constructor preserves the refusal opt-in."""
+ providers = (
+ (OpenAIChatModel, OpenAICredential, "openai.AsyncClient"),
+ (OpenAIResponseModel, OpenAICredential, "openai.AsyncClient"),
+ (
+ AnthropicChatModel,
+ AnthropicCredential,
+ "anthropic.AsyncAnthropic",
+ ),
+ (MiniMaxChatModel, MiniMaxCredential, "anthropic.AsyncAnthropic"),
+ )
+ for model_class, credential_class, client_path in providers:
+ for options in ({}, {"raise_on_refusal": True}):
+ with self.subTest(model=model_class, options=options):
+ with patch(client_path):
+ model = model_class(
+ credential=credential_class(api_key="test"),
+ model="test-model",
+ **options,
+ )
+ self.assertEqual(
+ model.raise_on_refusal,
+ options.get("raise_on_refusal", False),
+ )
+
+ async def test_dashscope_data_inspection_error(self) -> None:
+ """DashScope inspection codes map to a normalized unknown phase."""
+ model = _model_with_filters(DashScopeChatModel)
+ original = _ProviderError(
+ {
+ "code": "DataInspectionFailed",
+ "message": "inspection failed",
+ },
+ "dash-request",
+ )
+
+ error = model._normalize_exception(original)
+
+ self.assertIsInstance(error, ContentBlockedError)
+ self.assertDictEqual(
+ {
+ "message": error.message,
+ "phase": error.phase,
+ "provider": error.provider,
+ "original_code": error.original_code,
+ "request_id": error.request_id,
+ "partial_output": error.partial_output,
+ },
+ {
+ "message": "inspection failed",
+ "phase": ContentBlockedPhase.UNKNOWN,
+ "provider": "dashscope",
+ "original_code": "DataInspectionFailed",
+ "request_id": "dash-request",
+ "partial_output": False,
+ },
+ )
+
+ async def test_openai_content_filter_error(self) -> None:
+ """OpenAI input filter codes map to an input content block."""
+ model = _model_with_filters(OpenAIChatModel)
+ original = _ProviderError(
+ {
+ "code": "content_filter",
+ "message": "input blocked",
+ },
+ "openai-request",
+ )
+
+ error = model._normalize_exception(original)
+
+ self.assertIsInstance(error, ContentBlockedError)
+ self.assertEqual(error.phase, ContentBlockedPhase.INPUT)
+ self.assertEqual(error.provider, "openai")
+ self.assertEqual(error.original_code, "content_filter")
+ self.assertEqual(error.request_id, "openai-request")
+
+ async def test_openai_completion_finish_reason(self) -> None:
+ """A non-stream content-filter finish reason is an output block."""
+ model = _model_with_filters(OpenAIChatModel)
+ response = SimpleNamespace(
+ id="response-1",
+ choices=[SimpleNamespace(finish_reason="content_filter")],
+ usage=None,
+ )
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ model._parse_completion_response(datetime.now(), response)
+
+ self.assertEqual(raised.exception.phase, ContentBlockedPhase.OUTPUT)
+ self.assertEqual(raised.exception.request_id, "response-1")
+ self.assertFalse(raised.exception.partial_output)
+
+ async def test_openai_chat_refusal(self) -> None:
+ """A Chat Completions refusal is an output content block."""
+ model = _model_with_filters(OpenAIChatModel)
+ model.raise_on_refusal = True
+ response = SimpleNamespace(
+ id="response-refusal",
+ choices=[
+ SimpleNamespace(
+ finish_reason="stop",
+ message=SimpleNamespace(refusal="Cannot help."),
+ ),
+ ],
+ usage=None,
+ )
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ model._parse_completion_response(datetime.now(), response)
+
+ self.assertEqual(raised.exception.phase, ContentBlockedPhase.OUTPUT)
+ self.assertEqual(raised.exception.original_code, "refusal")
+ self.assertEqual(raised.exception.message, "Cannot help.")
+
+ async def test_openai_chat_refusal_is_output_by_default(self) -> None:
+ """A Chat Completions refusal remains visible by default."""
+ model = _model_with_filters(OpenAIChatModel)
+ response = SimpleNamespace(
+ id="response-refusal",
+ choices=[
+ SimpleNamespace(
+ finish_reason="stop",
+ message=SimpleNamespace(
+ content=None,
+ refusal="Cannot help.",
+ audio=None,
+ tool_calls=[],
+ ),
+ ),
+ ],
+ usage=None,
+ )
+
+ parsed = model._parse_completion_response(datetime.now(), response)
+
+ self.assertListEqual(
+ [block.text for block in parsed.content],
+ ["Cannot help."],
+ )
+
+ async def test_openai_chat_stream_refusal_after_output(self) -> None:
+ """A streamed Chat refusal records prior emitted output."""
+ model = _model_with_filters(OpenAIChatModel)
+ model.raise_on_refusal = True
+ stream = _Stream(
+ [
+ SimpleNamespace(
+ id="response-refusal-stream",
+ usage=None,
+ choices=[
+ SimpleNamespace(
+ finish_reason=None,
+ delta=SimpleNamespace(
+ refusal=None,
+ reasoning_content=None,
+ content="partial",
+ tool_calls=None,
+ audio=None,
+ ),
+ ),
+ ],
+ ),
+ SimpleNamespace(
+ id="response-refusal-stream",
+ usage=None,
+ choices=[
+ SimpleNamespace(
+ finish_reason="stop",
+ delta=SimpleNamespace(refusal="Cannot help."),
+ ),
+ ],
+ ),
+ ],
+ )
+ chunks = []
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ async for chunk in model._parse_stream_response(
+ datetime.now(),
+ stream,
+ ):
+ chunks.append(chunk)
+
+ self.assertListEqual(
+ [chunk.content[0].text for chunk in chunks],
+ ["partial"],
+ )
+ self.assertTrue(raised.exception.partial_output)
+
+ async def test_openai_chat_stream_refusal_is_output_by_default(
+ self,
+ ) -> None:
+ """Refusal fragments are returned as text with the default option."""
+ model = _model_with_filters(OpenAIChatModel)
+ stream = _Stream(
+ [
+ SimpleNamespace(
+ id="response-refusal-stream",
+ usage=None,
+ choices=[
+ SimpleNamespace(
+ finish_reason=None,
+ delta=SimpleNamespace(refusal=fragment),
+ ),
+ ],
+ )
+ for fragment in ("Cannot ", "help.")
+ ],
+ )
+
+ chunks = [
+ chunk
+ async for chunk in model._parse_stream_response(
+ datetime.now(),
+ stream,
+ )
+ ]
+
+ self.assertEqual(
+ [block.text for chunk in chunks for block in chunk.content],
+ ["Cannot ", "help."],
+ )
+
+ async def test_dashscope_stream_finish_reason_after_output(self) -> None:
+ """A streamed filter signal records previously emitted output."""
+ model = _model_with_filters(DashScopeChatModel)
+ text_delta = SimpleNamespace(
+ reasoning_content=None,
+ content="partial",
+ tool_calls=None,
+ audio=None,
+ )
+ empty_delta = SimpleNamespace(
+ reasoning_content=None,
+ content=None,
+ tool_calls=None,
+ audio=None,
+ )
+ stream = _Stream(
+ [
+ SimpleNamespace(
+ id="response-2",
+ usage=None,
+ choices=[
+ SimpleNamespace(
+ finish_reason=None,
+ delta=text_delta,
+ ),
+ ],
+ ),
+ SimpleNamespace(
+ id="response-2",
+ usage=None,
+ choices=[
+ SimpleNamespace(
+ finish_reason="content_filter",
+ delta=empty_delta,
+ ),
+ ],
+ ),
+ ],
+ )
+ chunks = []
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ async for chunk in model._parse_stream_response(
+ datetime.now(),
+ stream,
+ ):
+ chunks.append(chunk)
+
+ self.assertListEqual(
+ [chunk.content[0].text for chunk in chunks],
+ ["partial"],
+ )
+ self.assertTrue(raised.exception.partial_output)
+
+ async def test_openai_compatible_models_normalize_errors(self) -> None:
+ """OpenAI-compatible providers normalize explicit filter codes."""
+ providers = [
+ (
+ MoonshotChatModel,
+ "moonshot",
+ "type",
+ "content_filter",
+ ContentBlockedPhase.UNKNOWN,
+ ),
+ (
+ VolcengineChatModel,
+ "volcengine",
+ "code",
+ "InputTextSensitiveContentDetected",
+ ContentBlockedPhase.INPUT,
+ ),
+ (
+ VolcengineChatModel,
+ "volcengine",
+ "code",
+ "OutputTextSensitiveContentDetected",
+ ContentBlockedPhase.OUTPUT,
+ ),
+ ]
+
+ for model_class, provider, field, code, phase in providers:
+ with self.subTest(provider=provider):
+ model = _model_with_filters(model_class)
+ original = _ProviderError(
+ {
+ field: code,
+ "message": "input blocked",
+ },
+ f"{provider}-request",
+ )
+
+ error = model._normalize_exception(original)
+
+ self.assertIsInstance(error, ContentBlockedError)
+ self.assertEqual(error.phase, phase)
+ self.assertEqual(error.provider, provider)
+ self.assertEqual(error.original_code, code)
+ self.assertEqual(
+ error.request_id,
+ f"{provider}-request",
+ )
+
+ async def test_anthropic_refusal_is_output_by_default(self) -> None:
+ """Anthropic-compatible refusal text remains normal by default."""
+ response = SimpleNamespace(
+ id="response-default-refusal",
+ stop_reason="refusal",
+ stop_details=SimpleNamespace(explanation="policy block"),
+ content=[SimpleNamespace(type="text", text="Cannot help.")],
+ usage=None,
+ )
+
+ for model_class in (AnthropicChatModel, MiniMaxChatModel):
+ with self.subTest(model_class=model_class):
+ model = _model_with_filters(model_class)
+ parsed = await model._parse_anthropic_completion_response(
+ datetime.now(),
+ response,
+ )
+
+ self.assertListEqual(
+ [block.text for block in parsed.content],
+ ["Cannot help."],
+ )
+
+ async def test_openai_compatible_models_map_finish_reason(self) -> None:
+ """OpenAI-compatible completion filter reasons are normalized."""
+ providers = [
+ (DeepSeekChatModel, "deepseek"),
+ (MoonshotChatModel, "moonshot"),
+ (VolcengineChatModel, "volcengine"),
+ ]
+ response = SimpleNamespace(
+ id="response-3",
+ choices=[SimpleNamespace(finish_reason="content_filter")],
+ usage=None,
+ )
+
+ for model_class, provider in providers:
+ with self.subTest(provider=provider):
+ model = _model_with_filters(model_class)
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ model._parse_completion_response(
+ datetime.now(),
+ response,
+ )
+
+ self.assertEqual(
+ raised.exception.phase,
+ ContentBlockedPhase.OUTPUT,
+ )
+ self.assertEqual(raised.exception.provider, provider)
+
+ async def test_anthropic_and_minimax_refusal(self) -> None:
+ """Anthropic-compatible refusal reasons preserve the provider."""
+ response = SimpleNamespace(
+ id="response-5",
+ stop_reason="refusal",
+ stop_details=SimpleNamespace(explanation="policy block"),
+ content=[],
+ usage=None,
+ )
+
+ for model_class, provider in [
+ (AnthropicChatModel, "anthropic"),
+ (MiniMaxChatModel, "minimax"),
+ ]:
+ with self.subTest(provider=provider):
+ model = _model_with_filters(model_class)
+ model.raise_on_refusal = True
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ await model._parse_anthropic_completion_response(
+ datetime.now(),
+ response,
+ )
+
+ self.assertDictEqual(
+ {
+ "message": raised.exception.message,
+ "phase": raised.exception.phase,
+ "provider": raised.exception.provider,
+ "original_code": raised.exception.original_code,
+ },
+ {
+ "message": "policy block",
+ "phase": ContentBlockedPhase.OUTPUT,
+ "provider": provider,
+ "original_code": "refusal",
+ },
+ )
+
+ async def test_anthropic_stream_refusal_after_output(self) -> None:
+ """An Anthropic stream refusal records prior emitted output."""
+ model = _model_with_filters(AnthropicChatModel)
+ model.raise_on_refusal = True
+ stream = _Stream(
+ [
+ SimpleNamespace(
+ type="content_block_start",
+ index=0,
+ content_block=SimpleNamespace(type="text"),
+ ),
+ SimpleNamespace(
+ type="content_block_delta",
+ index=0,
+ delta=SimpleNamespace(
+ type="text_delta",
+ text="partial",
+ ),
+ ),
+ SimpleNamespace(
+ type="message_delta",
+ delta=SimpleNamespace(
+ stop_reason="refusal",
+ stop_details=None,
+ ),
+ usage=None,
+ ),
+ ],
+ )
+ chunks = []
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ async for chunk in (
+ model._parse_anthropic_stream_completion_response(
+ datetime.now(),
+ stream,
+ )
+ ):
+ chunks.append(chunk)
+
+ self.assertEqual(chunks[0].content[0].text, "partial")
+ self.assertTrue(raised.exception.partial_output)
+
+ async def test_anthropic_stream_refusal_is_output_by_default(
+ self,
+ ) -> None:
+ """Refusal stop reasons preserve streamed text by default."""
+ for model_class in (AnthropicChatModel, MiniMaxChatModel):
+ with self.subTest(model=model_class):
+ model = _model_with_filters(model_class)
+ stream = _Stream(
+ [
+ SimpleNamespace(
+ type="content_block_start",
+ index=0,
+ content_block=SimpleNamespace(type="text"),
+ ),
+ SimpleNamespace(
+ type="content_block_delta",
+ index=0,
+ delta=SimpleNamespace(
+ type="text_delta",
+ text="Cannot help.",
+ ),
+ ),
+ SimpleNamespace(
+ type="message_delta",
+ delta=SimpleNamespace(stop_reason="refusal"),
+ usage=None,
+ ),
+ ],
+ )
+
+ chunks = [
+ chunk
+ async for chunk in (
+ model._parse_anthropic_stream_completion_response(
+ datetime.now(),
+ stream,
+ )
+ )
+ ]
+
+ self.assertEqual(
+ [
+ block.text
+ for chunk in chunks
+ for block in chunk.content
+ ],
+ ["Cannot help."],
+ )
+
+ async def test_gemini_prompt_block(self) -> None:
+ """Gemini prompt feedback maps to an input content block."""
+ model = _model_with_filters(GeminiChatModel)
+ response = SimpleNamespace(
+ response_id="response-6",
+ prompt_feedback=SimpleNamespace(
+ block_reason="PROHIBITED_CONTENT",
+ block_reason_message="prompt blocked",
+ ),
+ candidates=[],
+ usage_metadata=None,
+ )
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ model._parse_completion_response(datetime.now(), response)
+
+ self.assertEqual(raised.exception.phase, ContentBlockedPhase.INPUT)
+ self.assertEqual(raised.exception.provider, "gemini")
+ self.assertEqual(
+ raised.exception.original_code,
+ "PROHIBITED_CONTENT",
+ )
+
+ async def test_gemini_candidate_block(self) -> None:
+ """Gemini safety finish reasons map to an output content block."""
+ model = _model_with_filters(GeminiChatModel)
+ response = SimpleNamespace(
+ response_id="response-7",
+ prompt_feedback=None,
+ candidates=[
+ SimpleNamespace(
+ finish_reason="SAFETY",
+ content=None,
+ ),
+ ],
+ usage_metadata=None,
+ )
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ model._parse_completion_response(datetime.now(), response)
+
+ self.assertEqual(raised.exception.phase, ContentBlockedPhase.OUTPUT)
+ self.assertEqual(raised.exception.original_code, "SAFETY")
+
+ async def test_gemini_other_reason_is_not_content_block(self) -> None:
+ """Gemini's generic OTHER reason is not treated as content policy."""
+ model = _model_with_filters(GeminiChatModel)
+ response = SimpleNamespace(
+ response_id="response-8",
+ prompt_feedback=SimpleNamespace(block_reason="OTHER"),
+ candidates=[],
+ usage_metadata=None,
+ )
+
+ parsed = model._parse_completion_response(datetime.now(), response)
+
+ self.assertListEqual(parsed.content, [])
+
+
+class OpenAIResponseContentBlockTest(IsolatedAsyncioTestCase):
+ """Test explicit content-block signals from the Responses API."""
+
+ async def test_review_flags_cover_all_policy_error_paths(self) -> None:
+ """The adapter assigns review flags for SDK and response errors."""
+ model = _model_with_filters(OpenAIResponseModel)
+ for code, requires_review in (
+ ("bio_policy", True),
+ ("MISALIGNMENT_POLICY_VIOLATION", True),
+ ("image_content_policy_violation", False),
+ ):
+ with self.subTest(code=code):
+ fields = {"code": code, "message": "policy block"}
+ response = SimpleNamespace(
+ id="response-policy",
+ incomplete_details=None,
+ error=SimpleNamespace(**fields),
+ output=[],
+ usage=None,
+ )
+ errors = [
+ model._normalize_exception(
+ _ProviderError(fields, "response-policy"),
+ ),
+ ]
+ with self.assertRaises(ContentBlockedError) as caught:
+ model._parse_completion_response(datetime.now(), response)
+ errors.append(caught.exception)
+ for event in (
+ SimpleNamespace(type="response.failed", response=response),
+ SimpleNamespace(type="error", **fields),
+ ):
+ with patch(
+ "agentscope.model._openai_response._model."
+ "_generate_id",
+ return_value="response-policy",
+ ):
+ with self.assertRaises(ContentBlockedError) as caught:
+ async for _ in model._parse_stream_response(
+ datetime.now(),
+ _Stream([event]),
+ ):
+ pass
+ errors.append(caught.exception)
+ expected = {
+ "message": "policy block",
+ "phase": ContentBlockedPhase.UNKNOWN,
+ "provider": "openai",
+ "original_code": code.casefold(),
+ "request_id": "response-policy",
+ "partial_output": False,
+ "requires_review": requires_review,
+ }
+ self.assertEqual(
+ [vars(error) for error in errors],
+ [{**expected, "original_code": code}, *[expected] * 3],
+ )
+
+ async def test_openai_response_policy_error(self) -> None:
+ """A documented Responses policy code maps to an unknown phase."""
+ model = _model_with_filters(OpenAIResponseModel)
+ api_error = _ProviderError(
+ {
+ "code": "bio_policy",
+ "message": "request policy block",
+ },
+ "response-request",
+ )
+ response = SimpleNamespace(
+ id="response-9",
+ incomplete_details=None,
+ error=SimpleNamespace(
+ code="bio_policy",
+ message="policy block",
+ ),
+ output=[],
+ usage=None,
+ )
+
+ normalized = model._normalize_exception(api_error)
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ model._parse_completion_response(datetime.now(), response)
+
+ self.assertIsInstance(normalized, ContentBlockedError)
+ self.assertEqual(normalized.phase, ContentBlockedPhase.UNKNOWN)
+ self.assertEqual(normalized.request_id, "response-request")
+ self.assertEqual(raised.exception.message, "policy block")
+ self.assertEqual(raised.exception.phase, ContentBlockedPhase.UNKNOWN)
+ self.assertEqual(raised.exception.original_code, "bio_policy")
+
+ async def test_openai_response_refusal(self) -> None:
+ """A Responses refusal content part is an output block."""
+ model = _model_with_filters(OpenAIResponseModel)
+ model.raise_on_refusal = True
+ response = SimpleNamespace(
+ id="response-refusal",
+ incomplete_details=None,
+ error=None,
+ output=[
+ SimpleNamespace(
+ type="message",
+ content=[
+ SimpleNamespace(
+ type="refusal",
+ refusal="Cannot help.",
+ ),
+ ],
+ ),
+ ],
+ usage=None,
+ )
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ model._parse_completion_response(datetime.now(), response)
+
+ self.assertEqual(raised.exception.phase, ContentBlockedPhase.OUTPUT)
+ self.assertEqual(raised.exception.original_code, "refusal")
+ self.assertEqual(raised.exception.message, "Cannot help.")
+
+ async def test_openai_response_stream_refusal_after_output(self) -> None:
+ """A streamed Responses refusal records prior emitted output."""
+ model = _model_with_filters(OpenAIResponseModel)
+ model.raise_on_refusal = True
+ stream = _Stream(
+ [
+ SimpleNamespace(
+ type="response.output_text.delta",
+ delta="partial",
+ item_id="message-1",
+ content_index=0,
+ ),
+ SimpleNamespace(
+ type="response.refusal.delta",
+ delta="Cannot help.",
+ ),
+ ],
+ )
+ chunks = []
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ async for chunk in model._parse_stream_response(
+ datetime.now(),
+ stream,
+ ):
+ chunks.append(chunk)
+
+ self.assertEqual(chunks[0].content[0].text, "partial")
+ self.assertEqual(raised.exception.original_code, "refusal")
+ self.assertTrue(raised.exception.partial_output)
+
+ async def test_openai_response_incomplete_after_output(self) -> None:
+ """A streamed Responses filter records prior emitted output."""
+ model = _model_with_filters(OpenAIResponseModel)
+ stream = _Stream(
+ [
+ SimpleNamespace(
+ type="response.output_text.delta",
+ delta="partial",
+ item_id="message-1",
+ content_index=0,
+ ),
+ SimpleNamespace(
+ type="response.incomplete",
+ response=SimpleNamespace(
+ id="response-10",
+ incomplete_details=SimpleNamespace(
+ reason="content_filter",
+ ),
+ error=None,
+ output=[],
+ ),
+ ),
+ ],
+ )
+ chunks = []
+
+ with self.assertRaises(ContentBlockedError) as raised:
+ async for chunk in model._parse_stream_response(
+ datetime.now(),
+ stream,
+ ):
+ chunks.append(chunk)
+
+ self.assertEqual(chunks[0].content[0].text, "partial")
+ self.assertTrue(raised.exception.partial_output)
diff --git a/tests/model_openai_chat_test.py b/tests/model_openai_chat_test.py
index 045e98b70..ef9393a3d 100644
--- a/tests/model_openai_chat_test.py
+++ b/tests/model_openai_chat_test.py
@@ -249,6 +249,32 @@ class TestOpenAIChatNonStream(IsolatedAsyncioTestCase):
)
self.assertEqual(result.id, "resp-1")
+ async def test_refusal_only_fills_missing_content(self) -> None:
+ """Prefer content when compatible providers also supply refusal."""
+ for content in ("Cannot help.", "Primary answer.", None, ""):
+ with self.subTest(content=content):
+ response = _mock_completion(text=content)
+ response.choices[0].message.refusal = "Cannot help."
+ self.mock_client.chat.completions.create = AsyncMock(
+ return_value=response,
+ )
+
+ result = await self.model([])
+
+ self.assertEqual(
+ (result.is_last, result.content),
+ (
+ True,
+ [
+ TextBlock.model_construct(
+ id=A,
+ created_at=A,
+ text=content or "Cannot help.",
+ ),
+ ],
+ ),
+ )
+
async def test_default_thinking_enable_not_forwarded(
self,
) -> None:
@@ -704,6 +730,40 @@ class TestOpenAIChatStream(IsolatedAsyncioTestCase):
)
self.assertEqual(responses[-1].id, "resp-1")
+ async def test_stream_refusal_only_fills_missing_content(self) -> None:
+ """Do not duplicate refusal text in deltas or the final response."""
+ for content in ("Cannot help.", "Primary answer.", None, ""):
+ with self.subTest(content=content):
+ chunk = _make_stream_chunk(delta_text=content)
+ chunk.choices[0].delta.refusal = "Cannot help."
+ self.mock_client.chat.completions.create = AsyncMock(
+ return_value=_MockAsyncStream([chunk]),
+ )
+
+ responses = [
+ response async for response in await self.model([])
+ ]
+
+ self.assertEqual(
+ [
+ (response.is_last, response.content)
+ for response in responses
+ ],
+ [
+ (
+ is_last,
+ [
+ TextBlock.model_construct(
+ id=A,
+ created_at=A,
+ text=content or "Cannot help.",
+ ),
+ ],
+ )
+ for is_last in (False, True)
+ ],
+ )
+
async def test_stream_thinking_and_text(
self,
) -> None: