agentscope-ai/agentscope · error · ValueError

The field `{key}` already exists in the original function sc

Error message

The field `{key}` already exists in the original function schema of `{self.tool.name}`. Try to use a different name.

What it means

Raised in ToolMetadata.get_tool_schema when merging an extended model's schema into the tool's original function schema and a property name collides with one already defined on the original function parameters. Extended models are meant to add new fields, not redefine existing ones.

Source

Thrown at src/agentscope/tool/_types.py:100

                "description": self.tool.description,
                "parameters": input_schema,
            },
        }

        extended_model = extended_model or self.extended_model

        if extended_model is None:
            return function_schema

        # Merge the extended model with the original JSON schema
        extended_schema = extended_model.model_json_schema()

        _remove_title_field(extended_schema)

        # Merge properties from extended schema
        for key, value in extended_schema["properties"].items():
            if key in function_schema["function"]["parameters"]["properties"]:
                raise ValueError(
                    f"The field `{key}` already exists in the original "
                    f"function schema of `{self.tool.name}`. Try to use a "
                    "different name.",
                )

            function_schema["function"]["parameters"]["properties"][
                key
            ] = value

            if key in extended_schema.get("required", []):
                if "required" not in function_schema["function"]["parameters"]:
                    function_schema["function"]["parameters"]["required"] = []
                function_schema["function"]["parameters"]["required"].append(
                    key,
                )

        # Merge $defs from extended schema to support nested models
        if "$defs" in extended_schema:

View on GitHub (pinned to e90f1c7592)

Solutions

1. Rename the conflicting field on the extended BaseModel to something not used by the function signature
2. Strip/alias the overlapping function parameter or the model field
3. Audit field names: set(model.model_fields) vs the function's parameter names before merging

Example fix

# before
class Ext(BaseModel):
    query: str  # collides with function arg `query`
tool_meta.get_tool_schema(extended_model=Ext)
# after
class Ext(BaseModel):
    context_query: str
tool_meta.get_tool_schema(extended_model=Ext)

import inspect
fn_params = set(inspect.signature(func).parameters)
collisions = fn_params & set(ExtendedModel.model_fields)
assert not collisions, f'field name collisions: {collisions}'

When it happens

Trigger: Calling get_tool_schema(extended_model=SomeModel) where SomeModel has a field whose name matches a parameter of the wrapped function, e.g. the function has an 'offset' parameter and the extended model also defines 'offset'.

Common situations: Adding metadata fields (session_id, user_id, memory) via an extended BaseModel whose field names clash with existing function args; reusing a generic Context model across multiple tools.

Related errors

• The $defs key `{def_key}` conflicts with existing definition
• Invalid input_schema: {self.tool.input_schema}.
• The injection template must contain the '{runtime_state}' pl
• Session {session_id!r} already has an active chat run in thi
• Exactly one of `data` or `url` must be provided.

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/e66118fdc581158a. Report an issue: GitHub.