Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
fix(schema): lift _flatten_json_schema to shared util and apply in OpenAI chat model (#1940)
qbc3467754dc48c
diff --git a/src/agentscope/_utils/_common.py b/src/agentscope/_utils/_common.pyindex 01ac9fbf1..6aaac28af 100644--- a/src/agentscope/_utils/_common.py+++ b/src/agentscope/_utils/_common.py@@ -2,6 +2,7 @@"""The common utilities for agentscope library."""import asyncioimport base64+import copyimport functoolsimport inspectimport json@@ -237,3 +238,92 @@ def _map_text_to_uuid(text: str) -> str:A deterministic UUID string derived from the input text."""return str(uuid.uuid3(uuid.NAMESPACE_DNS, text))+++def _flatten_json_schema(schema: dict) -> dict:+ """Flatten a JSON schema by resolving all local ``$ref`` references.++ Some LLM providers (e.g. Gemini, GLM-5.x via OpenCode Go) cannot+ process ``$defs`` / ``$ref`` patterns in tool parameter schemas.+ When Pydantic generates schemas for complex nested types it emits a+ ``$defs`` block (or the legacy ``definitions`` block) and refers to+ it with ``{"$ref": "#/$defs/TypeName"}``.++ This function resolves every such reference by substituting the full+ definition inline, then drops the ``$defs`` / ``definitions``+ sections so the output is a flat, self-contained schema.++ Circular references are detected and replaced with a fallback object+ schema to avoid infinite recursion. Only local references of the+ form ``#/$defs/<name>`` or ``#/definitions/<name>`` are expanded;+ external ``$ref`` URLs are left unchanged.++ Args:+ schema (`dict`):+ The JSON schema that may contain ``$defs`` and ``$ref``+ references.++ Returns:+ `dict`:+ A flattened JSON schema with all references resolved inline.+ """+ has_defs = isinstance(schema.get("$defs"), dict) or isinstance(+ schema.get("definitions"),+ dict,+ )+ if not has_defs:+ return schema++ schema = copy.deepcopy(schema)+ defs: dict[str, Any] = {}+ if isinstance(schema.get("$defs"), dict):+ defs.update(schema.pop("$defs"))+ if isinstance(schema.get("definitions"), dict):+ defs.update(schema.pop("definitions"))++ if not defs:+ return schema++ def _resolve_ref(obj: Any, visited: frozenset = frozenset()) -> Any:+ if isinstance(obj, list):+ return [_resolve_ref(item, visited) for item in obj]+ if not isinstance(obj, dict):+ return obj+ if "$ref" in obj:+ ref_path = obj["$ref"]+ if isinstance(ref_path, str) and (+ ref_path.startswith("#/$defs/")+ or ref_path.startswith("#/definitions/")+ ):+ def_name = ref_path.split("/")[-1]+ if def_name in visited:+ logger.warning(+ "Circular reference detected for '%s' in tool "+ "schema",+ def_name,+ )+ return {+ "type": "object",+ "description": f"(circular: {def_name})",+ }+ if def_name in defs:+ resolved = _resolve_ref(+ defs[def_name],+ visited | {def_name},+ )+ for key, value in obj.items():+ if key != "$ref":+ resolved[key] = _resolve_ref(+ value,+ visited | {def_name},+ )+ return resolved+ return obj+ result: dict[str, Any] = {}+ for key, value in obj.items():+ if key in ("$defs", "definitions"):+ continue+ result[key] = _resolve_ref(value, visited)+ return result++ return _resolve_ref(schema)diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.pyindex 0a1855e01..3a50d7cef 100644--- a/src/agentscope/model/_gemini/_model.py+++ b/src/agentscope/model/_gemini/_model.py@@ -1,14 +1,13 @@# -*- coding: utf-8 -*-"""The Google Gemini chat model implementation."""import base64-import copyimport jsonfrom datetime import datetimefrom typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Typefrom pydantic import BaseModel, Field-from ..._utils._common import _generate_id+from ..._utils._common import _generate_id, _flatten_json_schemafrom .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsage@@ -16,7 +15,6 @@ from ...credential import GeminiCredentialfrom ...formatter import FormatterBase, GeminiChatFormatterfrom ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlockfrom ...tool import ToolChoice-from ..._logging import loggerif TYPE_CHECKING:from google.genai.types import GenerateContentResponse@@ -24,58 +22,6 @@ else:GenerateContentResponse = Any-def _flatten_json_schema(schema: dict) -> dict:- """Flatten a JSON schema by resolving all $ref references.-- Gemini API does not support ``$defs`` and ``$ref`` in JSON schemas.-- Args:- schema (`dict`):- The JSON schema that may contain ``$defs`` and ``$ref`` references.-- Returns:- `dict`:- A flattened JSON schema with all references resolved inline.- """- schema = copy.deepcopy(schema)- defs = schema.pop("$defs", {})-- def _resolve_ref(obj: Any, visited: set | None = None) -> Any:- if visited is None:- visited = set()- if not isinstance(obj, dict):- if isinstance(obj, list):- return [_resolve_ref(item, visited.copy()) for item in obj]- return obj- if "$ref" in obj:- ref_path = obj["$ref"]- if ref_path.startswith("#/$defs/"):- def_name = ref_path[len("#/$defs/") :]- if def_name in visited:- logger.warning(- "Circular reference detected for '%s' in tool schema",- def_name,- )- return {- "type": "object",- "description": f"(circular: {def_name})",- }- visited.add(def_name)- if def_name in defs:- resolved = _resolve_ref(defs[def_name], visited.copy())- for key, value in obj.items():- if key != "$ref":- resolved[key] = _resolve_ref(value, visited.copy())- return resolved- return obj- result = {}- for key, value in obj.items():- result[key] = _resolve_ref(value, visited.copy())- return result-- return _resolve_ref(schema)--def _sanitize_schema_for_gemini(schema: Any) -> Any:"""Sanitize a JSON schema to be compatible with the Gemini API.diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.pyindex c62c0f26f..f49aad9cb 100644--- a/src/agentscope/model/_openai_chat/_model.py+++ b/src/agentscope/model/_openai_chat/_model.py@@ -11,7 +11,7 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Typefrom pydantic import BaseModel, Fieldfrom ..._utils._audio import _build_streaming_wav_header-from ..._utils._common import _generate_id+from ..._utils._common import _generate_id, _flatten_json_schemafrom .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponse, StructuredResponsefrom .._model_usage import ChatUsage@@ -657,6 +657,10 @@ class OpenAIChatModel(ChatModelBase):(str) the model is forced to call exactly that tool without needing tofilter the list, preserving prompt-cache efficiency.+ Tool parameter schemas are flattened (``$ref`` / ``$defs`` resolved+ inline) so that providers which do not support JSON Schema references+ (e.g. GLM-5.x via OpenCode Go) receive a self-contained schema.+Args:tools (`list[dict] | None`, optional):The raw tool schemas.@@ -673,6 +677,9 @@ class OpenAIChatModel(ChatModelBase):allowed = set(tool_choice.tools)tools = [t for t in tools if t["function"]["name"] in allowed]+ if tools:+ tools = self._flatten_tool_schemas(tools)+if not tool_choice:return tools, None@@ -682,3 +689,38 @@ class OpenAIChatModel(ChatModelBase):return tools, {"type": "function", "function": {"name": mode}}return tools, mode++ @staticmethod+ def _flatten_tool_schemas(+ tools: list[dict],+ ) -> list[dict]:+ """Inline ``$ref`` / ``$defs`` in each tool's parameter schema.++ Args:+ tools (`list[dict]`):+ The list of tool dicts, each with a ``"function"`` key+ containing the tool name, description and ``"parameters"``+ JSON schema.++ Returns:+ `list[dict]`:+ A new list where each tool's ``parameters`` schema has all+ local ``$ref`` / ``$defs`` resolved inline. Tools whose+ schema contained no references are returned unchanged (same+ object identity).+ """+ result = []+ for tool in tools:+ func = tool.get("function")+ if not isinstance(func, dict):+ result.append(tool)+ continue+ params = func.get("parameters")+ if not isinstance(params, dict):+ result.append(tool)+ continue+ flat = _flatten_json_schema(params)+ if flat is not params:+ tool = {**tool, "function": {**func, "parameters": flat}}+ result.append(tool)+ return resultdiff --git a/tests/model_gemini_test.py b/tests/model_gemini_test.pyindex ad91ee9f1..5788f6684 100644--- a/tests/model_gemini_test.py+++ b/tests/model_gemini_test.py@@ -15,10 +15,8 @@ from utils import AnyStringfrom agentscope.message import TextBlock, ToolCallBlock, ThinkingBlockfrom agentscope.model import GeminiChatModel-from agentscope.model._gemini._model import (- _flatten_json_schema,- _sanitize_schema_for_gemini,-)+from agentscope.model._gemini._model import _sanitize_schema_for_gemini+from agentscope._utils._common import _flatten_json_schemafrom agentscope.credential import GeminiCredentialfrom agentscope.tool import ToolChoice@@ -651,3 +649,27 @@ class TestGeminiSchemaUtils(unittest.TestCase):},},)++ def test_flatten_legacy_definitions_ref(self) -> None:+ """Legacy 'definitions' keyword is resolved like '$defs'."""+ self.assertEqual(+ _flatten_json_schema(+ {+ "definitions": {"Address": {"type": "string"}},+ "properties": {+ "addr": {"$ref": "#/definitions/Address"},+ },+ },+ ),+ {+ "properties": {+ "addr": {"type": "string"},+ },+ },+ )++ def test_flatten_no_defs_returns_same_object(self) -> None:+ """Schema with no $defs/definitions is returned unchanged (+ identity)."""+ schema = {"type": "object", "properties": {"x": {"type": "integer"}}}+ self.assertIs(_flatten_json_schema(schema), schema)