agentscope-ai/agentscope · error · ValueError

The 'basic' tool group is reserved for the default tool…

Error message

The 'basic' tool group is reserved for the default tool group. Don't include 'basic' in the tool_groups argument when you also provide tools, skills or mcps in the constructor.

What it means

Toolkit.__init__ rejects a tool_groups list that contains a group named 'basic': that name is reserved for the implicit default group holding constructor-level tools/skills/mcps.

Solutions

Rename your group to something other than 'basic'
Move those tools/skills to the Toolkit constructor's top-level arguments if they belong in the default group

Example fix

# before
Toolkit(tools=[t], tool_groups=[ToolGroup(name='basic', description='d', skills=[s])])
# after
Toolkit(tools=[t], skills=[s])

Defensive patterns

Strategy: validation

Validate before calling

assert not any(g.name == 'basic' for g in tool_groups or [])

Prevention

Never name a custom group 'basic'
Generate group names from a namespace to avoid reserved words

When it happens

Trigger: Toolkit(tools=[...], tool_groups=[ToolGroup(name='basic', ...)]) — mixing an explicitly named 'basic' group with top-level tools/skills/mcps.

Common situations: Copying an example ToolGroup config and forgetting to rename it; assembling groups dynamically and colliding with the reserved name.

Related errors

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

Appendix: source

Thrown at src/agentscope/tool/_toolkit.py:120

                The tool objects that belong to the "basic" tool group.
            skills_or_loaders (`list[str | Skill | SkillLoaderBase] | None`, \
            optional):
                The agent skill directories to be registered in the "basic"
                tool group.
            mcps (`list[MCPClient] | None`, optional):
                The mcp clients to be registered in the "basic" tool group.
            tool_groups (`list[ToolGroup] | None`, optional):
                The tool groups to be registered.
            meta_tool_response_template (`str`, optional):
                The template for meta tool responses.
            skill_instruction_template (`str`):
                A Jinja2 template for generating the agent skill instruction.
        """

        if tool_groups is not None and any(
            _.name == "basic" for _ in tool_groups
        ):
            raise ValueError(
                "The 'basic' tool group is reserved for the default tool "
                "group. Don't include 'basic' in the tool_groups argument "
                "when you also provide tools, skills or mcps in the "
                "constructor.",
            )

        self.tool_groups = [
            ToolGroup(
                name="basic",
                tools=tools or [],
                skills_or_loaders=skills_or_loaders or [],
                mcps=mcps or [],
            ),
        ] + (tool_groups or [])

        # Check name conflict for tool groups
        if len(set(_.name for _ in self.tool_groups)) != len(
            self.tool_groups,

View on GitHub (pinned to e90f1c7592)