agentscope-ai/agentscope · error · ValueError

Invalid permission decision behavior: {decision.behavior}

Error message

Invalid permission decision behavior: {decision.behavior}

What it means

A defensive ValueError raised in the agent's permission handling when a permission decision object carries a behavior the agent does not know how to execute. The permission engine returns decisions like allow/deny/ask; an unrecognized behavior means the decision producer and consumer are out of sync.

Source

Thrown at src/agentscope/agent/_agent.py:2522

                    # The ended event for the tool result
                    yield ToolResultEndEvent(
                        reply_id=self.state.reply_id,
                        tool_call_id=tool_call.id,
                        state=chunk.state,
                        metadata=chunk.metadata,
                    )

                else:
                    # Intermediate ToolChunk — convert to streaming events
                    async for evt in self._convert_tool_chunk_to_event(
                        tool_call.id,
                        chunk.content,
                    ):
                        yield evt

            return

        raise ValueError(
            f"Invalid permission decision behavior: {decision.behavior}",
        )

    async def _acting(
        self,
        tool_call: ToolCallBlock,
    ) -> AsyncGenerator["ToolChunk | ToolResponse", None]:
        """Raw tool execution entry point (maybe wrapped by middleware).

        This method is the hook point for ``on_acting`` middleware.  It
        delegates to :meth:`_acting_impl` which wraps
        ``toolkit.call_tool`` directly.  Permission checking and context
        writes are **not** part of this method — they are handled by
        :meth:`_execute_tool_call` before and after this call.

        Args:
            tool_call (`ToolCallBlock`):
                The tool call block to execute.

View on GitHub (pinned to e90f1c7592)

Solutions

1. Check the value of decision.behavior in your middleware/hook against the PermissionBehavior enum supported by your installed agentscope version
2. Pin/upgrade agentscope so middleware and agent share the same decision enum
3. Return only documented behaviors (ALLOW/DENY/ASK equivalents) from custom permission logic

Example fix

# before
def my_middleware(...):
    decision = PermissionDecision(behavior="approve")  # unknown

# after
from agentscope.agent import PermissionBehavior
decision = PermissionDecision(behavior=PermissionBehavior.ALLOW)

from agentscope.agent import PermissionBehavior  # adjust import

def behavior_supported(behavior) -> bool:
    try:
        return behavior in set(PermissionBehavior)
    except TypeError:
        return False

def is_known_behavior(value) -> bool:
    return isinstance(value, str) and value in {"allow", "deny", "ask"}

try:
    await agent.run(msg)
except ValueError as e:
    if "Invalid permission decision behavior" in str(e):
        fix_middleware_behavior(); raise

When it happens

Trigger: A custom acting middleware or permission hook returns a PermissionDecision with a behavior value outside the supported set, reaching the fall-through branch after the handled behaviors yield events and return.

Common situations: Upgrading agentscope where new decision behaviors were added but custom middleware returns an old/new mismatched enum; typos in behavior strings; third-party middleware incompatible with the installed agent version.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Model call failed after retries, but no exception was raised
• f"{type(self).__name__} does not implement on_check_permissi
• One or more tool calls raised an exception
• Input validation failed for tool '{tool_call.name}': {e.mess
• The injection template must contain the '{runtime_state}' pl

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