agentscope-ai/agentscope · error · RuntimeError

f"{type(self).__name__} does not implement on_system_prompt"

Error message

f"{type(self).__name__} does not implement on_system_prompt"

What it means

Middleware.on_system_prompt base stub raises RuntimeError when _get_system_prompt dispatches to a middleware that did not override on_system_prompt. Middlewares in the system-prompt chain must implement this hook to transform or pass through the prompt string.

Source

Thrown at src/agentscope/middleware/_base.py:282

    async def on_system_prompt(
        self,
        agent: "Agent",
        current_prompt: str,
    ) -> str:
        """Transform the system prompt string.

        This uses a transformer/pipeline pattern rather than onion pattern.
        Multiple middlewares are applied sequentially, each receiving the
        output of the previous one.

        Args:
            agent: The Agent instance executing this middleware
            current_prompt: The current system prompt string

        Returns:
            str: The transformed system prompt
        """
        raise RuntimeError(
            f"{type(self).__name__} does not implement on_system_prompt",
        )

    async def list_tools(self) -> list[ToolBase]:
        """List available tools provided by this middleware. Optional to
        implement.

        Returns:
            `list[ToolBase]`:
                A list of tools provided by this middleware.
        """
        return []

    async def get_middleware_key(self) -> str:
        """Get the unique key for this middleware, used to save middleware
        states in `AgentState` instances.

        Optionally, middleware classes can override this method to

View on GitHub (pinned to e90f1c7592)

Solutions

1. Implement async on_system_prompt(self, agent, current_prompt) -> str returning the (possibly transformed) prompt
2. Have unrelated middlewares return current_prompt unchanged
3. Verify method name spelling and signature against the current base class

Example fix

// before
class PersonaMiddleware(Middleware):
    async def on_acting(self, agent, tool_call, next_handler):
        async for c in next_handler(tool_call):
            yield c
# _get_system_prompt -> RuntimeError 239

// after
class PersonaMiddleware(Middleware):
    async def on_system_prompt(self, agent, current_prompt):
        return current_prompt + "\nAlways answer in the user's language."

    async def on_acting(self, agent, tool_call, next_handler):
        async for c in next_handler(tool_call):
            yield c

from agentscope.middleware import Middleware
assert type(mw).on_system_prompt is not Middleware.on_system_prompt

def implements_on_system_prompt(mw) -> bool:
    from agentscope.middleware import Middleware
    return type(mw).on_system_prompt is not Middleware.on_system_prompt

When it happens

Trigger: Agent construction/reply startup calls _get_system_prompt, which walks the middleware chain; any middleware in that chain without an on_system_prompt override raises. Also triggered by overrides calling super().on_system_prompt(...).

Common situations: Custom middlewares registered on an agent but written without the system-prompt hook; upgrading agentscope where the system-prompt chain now includes all registered middlewares; ordering bugs inserting a base-like stub into the chain.

Related errors

• {type(self).__name__} does not implement on_reply
• {type(self).__name__} does not implement on_reasoning
• {type(self).__name__} does not implement on_acting
• f"{type(self).__name__} does not implement on_check_permissi
• f"{type(self).__name__} does not implement on_model_call"

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