agentscope-ai/agentscope · error · ToolGroupInactiveError

ToolGroupInactiveError: The tool '{tool_name}' in group '{al

Error message

ToolGroupInactiveError: The tool '{tool_name}' in group '{all_tools[tool_name].group}' is currently inactive. You should first activate the group by calling the '{self.builtin_meta_tool.tool.name}' tool.

What it means

Toolkit.check_tool_available raises ToolGroupInactiveError when the requested tool exists but lives in a tool group that is currently inactive (not activated). The message tells the LLM/agent to activate the group first via the built-in meta tool instead of treating it as a missing tool.

Source

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

        Returns:
            `ToolBase`:
                If the tool is available, return the corresponding ToolBase
                object. Otherwise, raise the agent-oriented exception with the
                error message.
        """
        tools = await self._get_available_tools(activated_groups)
        if tool_name not in tools:
            # The dict above is already filtered to the basic + activated
            # groups, so a tool from an inactive group is missing from it.
            # Look the name up across all registered groups to distinguish
            # "inactive" from "doesn't exist" - the same fallback call_tool
            # performs - so the agent gets the activation hint instead of a
            # misleading not-found error.
            all_tools = await self._get_available_tools(
                [_.name for _ in self.tool_groups],
            )
            if tool_name in all_tools:
                raise ToolGroupInactiveError(
                    f"ToolGroupInactiveError: The tool '{tool_name}' in "
                    f"group '{all_tools[tool_name].group}' is currently "
                    f"inactive. You should first activate the group by "
                    f"calling the "
                    f"'{self.builtin_meta_tool.tool.name}' tool.",
                )
            raise ToolNotFoundError(
                f"ToolNotFoundError: The tool named '{tool_name}' doesn't "
                f"exist.",
            )

        return tools[tool_name].tool

    async def get_tool(self, name: str) -> ToolBase | None:
        """Get tool instance by its name.

        Args:
            name (`str`):

View on GitHub (pinned to e90f1c7592)

Solutions

1. Have the agent call the built-in meta tool (named in the error message) to activate the group before calling the tool
2. If the tool should always be available, configure its group to be active by default / remove it from lazy activation
3. Catch ToolGroupInactiveError in your orchestration layer and re-prompt the model with the activation hint

Example fix

# before
result = await toolkit.call_tool('search_docs', {...})  # group inactive
# after
await toolkit.call_tool(meta_tool_name, {'action': 'activate', 'group': 'search'})
result = await toolkit.call_tool('search_docs', {...})

active = await toolkit._get_available_tools([g.name for g in toolkit.tool_groups if g.is_active])
if tool_name not in active:
    # activate group or pick another tool

try:
    tool = await toolkit.check_tool_available(name)
except ToolGroupInactiveError as e:
    # instruct the model to call the activation meta tool, then retry
    await activate_group(meta_tool_name, group)

When it happens

Trigger: The agent calls a tool whose group has not been activated yet; check_tool_available looks the name up across all (including inactive) groups, finds it, and raises this hint error.

Common situations: Agents with lazy/on-demand group activation calling a tool before invoking the activation meta tool; tests exercising inactive-group behavior; forgetting the activation step in a scripted tool sequence.

Related errors

• The 'reserve_ratio' of the context config must be smaller th
• The 'context_buffer_ratio' of the injection config must be s
• Agent did not produce a final message.
• The system prompt {suffix}exceed(s) the compression threshol
• Agent {agent_id!r} not found.

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