microsoft/autogen · error · ValueError

Maximum number of tool iterations must be greater than or eq

Error message

Maximum number of tool iterations must be greater than or equal to 1, got {max_tool_iterations}

What it means

AssistantAgent validates max_tool_iterations >= 1; the parameter bounds how many tool-call/reflection rounds the agent performs per turn, and zero or negative values are rejected with ValueError naming the offending value.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py:853

            self._workbench = [StaticStreamWorkbench(self._tools)]

        if model_context is not None:
            self._model_context = model_context
        else:
            self._model_context = UnboundedChatCompletionContext()

        if self._output_content_type is not None and reflect_on_tool_use is None:
            # If output_content_type is set, we need to reflect on tool use by default.
            self._reflect_on_tool_use = True
        elif reflect_on_tool_use is None:
            self._reflect_on_tool_use = False
        else:
            self._reflect_on_tool_use = reflect_on_tool_use

        # Tool call loop
        self._max_tool_iterations = max_tool_iterations
        if self._max_tool_iterations < 1:
            raise ValueError(
                f"Maximum number of tool iterations must be greater than or equal to 1, got {max_tool_iterations}"
            )

        self._tool_call_summary_format = tool_call_summary_format
        self._tool_call_summary_formatter = tool_call_summary_formatter
        self._is_running = False

    @property
    def produced_message_types(self) -> Sequence[type[BaseChatMessage]]:
        """Get the types of messages this agent can produce.

        Returns:
            Sequence of message types this agent can generate
        """
        types: List[type[BaseChatMessage]] = [TextMessage, ToolCallSummaryMessage, HandoffMessage]
        if self._structured_message_factory is not None:
            types.append(StructuredMessage)
        return types

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Set max_tool_iterations to at least 1 (typical values: 5-25 depending on task).
2. If tools should not run at all, omit the tools/workbench arguments rather than setting iterations to 0.
3. Validate/compute the value with max(1, n) in config-loading code.

Example fix

# before
agent = AssistantAgent(name="a", model_client=client, tools=[t], max_tool_iterations=0)

# after
agent = AssistantAgent(name="a", model_client=client, tools=[t], max_tool_iterations=10)

max_tool_iterations = max(1, int(max_tool_iterations))

def is_valid_iteration_count(n) -> bool:
    return isinstance(n, int) and n >= 1

try:
    agent = AssistantAgent(name="a", model_client=client, tools=tools, max_tool_iterations=n)
except ValueError as e:
    if "tool iterations" in str(e):
        agent = AssistantAgent(name="a", model_client=client, tools=tools, max_tool_iterations=10)
    else:
        raise

When it happens

Trigger: Passing max_tool_iterations=0 (e.g. intending 'no tool use') or a negative number, often from a config file default, a computed value, or copy-pasting older examples.

Common situations: Config-driven agent factories where an unset key defaults to 0, arithmetic that subtracts (budget - used) going negative, or misunderstanding 'iterations' as 'additional iterations beyond the first'.

Related errors

• Tool names must be unique: {tool_names}
• At least one participant is required.
• The participant names must be unique.
• Task list cannot be empty.
• The maximum number of turns must be greater than 0.

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/48c38b33d8e39765. Report an issue: GitHub.