{"record":{"id":"48c38b33d8e39765","repo":"microsoft/autogen","slug":"maximum-number-of-tool-iterations-must-be-greater","errorCode":null,"errorMessage":"Maximum number of tool iterations must be greater than or equal to 1, got {max_tool_iterations}","messagePattern":"Maximum number of tool iterations must be greater than or equal to 1, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py","lineNumber":853,"sourceCode":"            self._workbench = [StaticStreamWorkbench(self._tools)]\n\n        if model_context is not None:\n            self._model_context = model_context\n        else:\n            self._model_context = UnboundedChatCompletionContext()\n\n        if self._output_content_type is not None and reflect_on_tool_use is None:\n            # If output_content_type is set, we need to reflect on tool use by default.\n            self._reflect_on_tool_use = True\n        elif reflect_on_tool_use is None:\n            self._reflect_on_tool_use = False\n        else:\n            self._reflect_on_tool_use = reflect_on_tool_use\n\n        # Tool call loop\n        self._max_tool_iterations = max_tool_iterations\n        if self._max_tool_iterations < 1:\n            raise ValueError(\n                f\"Maximum number of tool iterations must be greater than or equal to 1, got {max_tool_iterations}\"\n            )\n\n        self._tool_call_summary_format = tool_call_summary_format\n        self._tool_call_summary_formatter = tool_call_summary_formatter\n        self._is_running = False\n\n    @property\n    def produced_message_types(self) -> Sequence[type[BaseChatMessage]]:\n        \"\"\"Get the types of messages this agent can produce.\n\n        Returns:\n            Sequence of message types this agent can generate\n        \"\"\"\n        types: List[type[BaseChatMessage]] = [TextMessage, ToolCallSummaryMessage, HandoffMessage]\n        if self._structured_message_factory is not None:\n            types.append(StructuredMessage)\n        return types","sourceCodeStart":835,"sourceCodeEnd":871,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py#L835-L871","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Set max_tool_iterations to at least 1 (typical values: 5-25 depending on task).","If tools should not run at all, omit the tools/workbench arguments rather than setting iterations to 0.","Validate/compute the value with max(1, n) in config-loading code."],"exampleFix":"# before\nagent = AssistantAgent(name=\"a\", model_client=client, tools=[t], max_tool_iterations=0)\n\n# after\nagent = AssistantAgent(name=\"a\", model_client=client, tools=[t], max_tool_iterations=10)","handlingStrategy":"validation","validationCode":"max_tool_iterations = max(1, int(max_tool_iterations))","typeGuard":"def is_valid_iteration_count(n) -> bool:\n    return isinstance(n, int) and n >= 1","tryCatchPattern":"try:\n    agent = AssistantAgent(name=\"a\", model_client=client, tools=tools, max_tool_iterations=n)\nexcept ValueError as e:\n    if \"tool iterations\" in str(e):\n        agent = AssistantAgent(name=\"a\", model_client=client, tools=tools, max_tool_iterations=10)\n    else:\n        raise","preventionTips":["Default config values to a sane positive number (e.g. 10), never 0.","Validate config schemas with jsonschema minimum: 1 for max_tool_iterations."],"tags":["python","configuration","validation","autogen"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}