Skip to content

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

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.py
index 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 asyncio
import base64
+import copy
import functools
import inspect
import 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.py
index 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 copy
import json
from datetime import datetime
from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
from pydantic import BaseModel, Field
-from ..._utils._common import _generate_id
+from ..._utils._common import _generate_id, _flatten_json_schema
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
@@ -16,7 +15,6 @@ from ...credential import GeminiCredential
from ...formatter import FormatterBase, GeminiChatFormatter
from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
from ...tool import ToolChoice
-from ..._logging import logger
if 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.py
index 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, Type
from pydantic import BaseModel, Field
from ..._utils._audio import _build_streaming_wav_header
-from ..._utils._common import _generate_id
+from ..._utils._common import _generate_id, _flatten_json_schema
from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse, StructuredResponse
from .._model_usage import ChatUsage
@@ -657,6 +657,10 @@ class OpenAIChatModel(ChatModelBase):
(str) the model is forced to call exactly that tool without needing to
filter 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 result
diff --git a/tests/model_gemini_test.py b/tests/model_gemini_test.py
index ad91ee9f1..5788f6684 100644
--- a/tests/model_gemini_test.py
+++ b/tests/model_gemini_test.py
@@ -15,10 +15,8 @@ from utils import AnyString
from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
from 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_schema
from agentscope.credential import GeminiCredential
from 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)