Heuristic:Microsoft Autogen Parallel Tool Call Safety

Knowledge Sources	Microsoft AutoGen AssistantAgent docstring
Domains	Multi_Agent_Systems, Debugging
Last Updated	2026-02-11 18:00 GMT

Overview

Disable `parallel_tool_calls` in model client configuration when using AgentTool, TeamTool, or handoffs to prevent concurrency bugs and lost handoff messages.

Description

By default, OpenAI and Azure OpenAI model clients allow the LLM to return multiple tool calls in a single response. These tool calls are then executed concurrently by the AssistantAgent. This creates problems in three specific scenarios: (1) when tools wrap stateful agents (AgentTool), (2) when tools wrap stateful teams (TeamTool), and (3) when multiple handoffs are returned simultaneously. In all cases, the underlying agents/teams maintain internal state and cannot safely run concurrently.

Usage

Use this heuristic whenever you configure an agent with:

AgentTool or TeamTool — these wrap stateful agents/teams that cannot run in parallel
Handoffs — if the model returns multiple handoff tool calls, only the first is executed and the rest are silently dropped
Any tool with side effects that depends on sequential execution order

The Insight (Rule of Thumb)

Action: Set `parallel_tool_calls=False` in your model client constructor.
Value: `parallel_tool_calls=False` (boolean flag).
Trade-off: Slightly slower execution when the model requests multiple independent tool calls (they will run sequentially instead of concurrently). In practice, the overhead is negligible for most use cases.
Scope: Applies to `OpenAIChatCompletionClient` and `AzureOpenAIChatCompletionClient`.

from autogen_ext.models.openai import OpenAIChatCompletionClient

# CORRECT: Disable parallel tool calls for safety
model_client = OpenAIChatCompletionClient(
    model="gpt-4o",
    parallel_tool_calls=False,  # Critical for AgentTool/TeamTool/Handoffs
)

Reasoning

The AssistantAgent executes tool calls concurrently when `parallel_tool_calls=True` (default). This is safe for stateless functions (e.g., calculators, web searches) but dangerous for:

AgentTool / TeamTool: These tools run a full agent or team session internally. Agents maintain conversation state, model context, and internal queues. Concurrent execution leads to race conditions, corrupted state, and unpredictable behavior. The AgentTool and TeamTool docstrings explicitly warn:

From `autogen_agentchat/tools/_agent.py:26-28`:

# You MUST disable parallel tool calls in model client configuration
# to avoid concurrency issues. Agents maintain internal state and
# cannot run concurrently.

Handoffs: When the model returns multiple handoff tool calls in one response, only the first handoff is executed. The rest are silently dropped. This means the agent may appear to hand off to the wrong target. From `_assistant_agent.py:171-172`:

# If multiple handoffs are detected, only the first handoff is executed.
# To avoid this, disable parallel tool calls in the model client configuration.

Parallel execution: From `_assistant_agent.py:145`:

# If the model returns multiple tool calls, they will be executed concurrently.
# To disable parallel tool calls you need to configure the model client.
# For example, set parallel_tool_calls=False for OpenAIChatCompletionClient.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment