# Setting up MagenticOneGroupChat for Complex Task Orchestration in AutoGen

> Master MagenticOneGroupChat in AutoGen for complex task orchestration. Learn how this ledger-driven team solves tough problems autonomously using outer and inner loops.

- Repository: [Microsoft/autogen](https://github.com/microsoft/autogen)
- Tags: how-to-guide
- Published: 2026-03-07

---

**MagenticOneGroupChat is a ledger-driven multi-agent team in Microsoft AutoGen that orchestrates specialized agents through an outer planning loop and inner execution loop to solve complex tasks autonomously.**

Microsoft AutoGen provides a layered framework for building multi-agent systems, and the MagenticOne extension represents the state-of-the-art approach for complex task orchestration. Setting up MagenticOneGroupChat enables you to leverage a ledger-driven architecture that coordinates specialized agents like **FileSurfer**, **WebSurfer**, and **Coder** through structured planning and execution loops.

## AutoGen Architecture Layers

AutoGen organizes functionality into distinct layers that separate core primitives from high-level orchestration:

| Layer | Package | Purpose | Key Entry Points |
|-------|---------|---------|------------------|
| **Core** | `autogen-core` | Low-level message passing, event system, cancellation, serialization, and runtime utilities. | `autogen_core._agent`, `autogen_core._agent_runtime` |
| **AgentChat** | `autogen-agentchat` | Opinionated abstractions for agents, tools, group chats, and UI front-ends. | `autogen_agentchat.agents.AssistantAgent`, `autogen_agentchat.teams.*` |
| **Extensions** | `autogen-ext` | Plug-in ecosystem for LLM clients, code executors, browsers, and specialized teams. | `autogen_ext.models.openai.OpenAIChatCompletionClient`, `autogen_ext.teams.magentic_one.MagenticOne` |

The **MagenticOne** implementation resides in the Extensions layer and builds upon the AgentChat API. According to the source code in [`autogen_ext/teams/magentic_one.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/teams/magentic_one.py), the high-level `MagenticOne` class assembles the default agent team and instantiates the underlying `MagenticOneGroupChat`.

## MagenticOneGroupChat Components

### The Orchestrator

At the heart of MagenticOneGroupChat is the **`MagenticOneOrchestrator`**, implemented in [`autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py). This orchestrator drives a two-level loop:

- **Outer loop**: Creates a **task ledger** containing facts and a high-level plan.
- **Inner loop**: Repeatedly queries the LLM for a JSON `LedgerEntry` that determines the next speaker, tracks progress, and triggers re-planning when necessary.

The orchestrator handles start events via `handle_start()`, processes agent responses through `handle_agent_response()`, and detects stalls or loops automatically.

### Specialized Agents

MagenticOneGroupChat coordinates several specialized agents defined in the Extensions package:

- **FileSurfer**: Reads and navigates local files.
- **WebSurfer**: Controls a Chromium-based browser via Playwright MCP.
- **Coder**: Writes and analyzes code.
- **ComputerTerminal**: Executes code via a `CodeExecutorAgent` (defaults to Docker).
- **UserProxy** (optional): Enables human-in-the-loop (HIL) input when `hil_mode=True`.

### Ledger Prompts and Structured Output

The orchestrator relies on structured prompts defined in [`_magentic_one/_prompts.py`](https://github.com/microsoft/autogen/blob/main/_magentic_one/_prompts.py). These prompts instruct the LLM to return a **`LedgerEntry`** JSON object containing:

- `is_request_satisfied`: Boolean indicating task completion.
- `is_progress_being_made`: Boolean tracking forward movement.
- `next_speaker`: The agent selected for the next turn.
- `instruction`: Specific task for the selected agent.

This structured approach allows the orchestrator to parse decisions programmatically rather than interpreting free-form text.

## Execution Flow

When you initialize a MagenticOneGroupChat, the following execution sequence occurs:

1. **CLI or Programmatic Entry**: The task string is parsed along with configuration options (HIL mode, rich console UI).
2. **Model Client Initialization**: An `OpenAIChatCompletionClient` loads from YAML configuration or direct instantiation.
3. **Agent Instantiation**: FileSurfer, WebSurfer, Coder, and the code executor are created with appropriate tool configurations.
4. **Group Chat Creation**: `MagenticOneGroupChat` initializes with the participant list and model client.
5. **Orchestrator Start**: The `handle_start` method generates initial facts and a plan using the task-ledger prompts.
6. **Inner Loop Execution**: `_orchestrate_step` builds progress ledger prompts, validates JSON responses, detects stalls, and publishes instructions to selected agents.
7. **Agent Response Handling**: `handle_agent_response` updates the message thread and repeats the inner loop.
8. **Termination**: When `is_request_satisfied` returns true, the orchestrator generates a final answer and terminates the chat.

The entire process is fully asynchronous, utilizes **cancellation tokens** for graceful shutdown, and logs internal steps through `trace_logger` and `event_logger`.

## Why MagenticOneGroupChat Works

**Declarative planning** separates high-level strategy from execution details. The outer ledger captures facts and plans that the LLM can reason over without getting lost in implementation minutiae.

**Structured progress checks** enforce a uniform contract through the JSON `LedgerEntry` schema. This allows the orchestrator to detect loops or stalls automatically rather than relying on heuristic text parsing.

**Modular agent architecture** treats each skill as a separate `ChatAgent`. This makes it trivial to swap components—replace the web browser with a custom data source, or add domain-specific agents alongside the standard FileSurfer and Coder.

**Human-in-the-loop optionality** enables safe execution for risky tasks while supporting fully autonomous runs when `hil_mode=False`. The `UserProxyAgent` integrates seamlessly into the participant list without disrupting the orchestration logic.

## Key Files Reference

| File | Description | Link |
|------|-------------|------|
| [`python/packages/magentic-one-cli/src/magentic_one_cli/_m1.py`](https://github.com/microsoft/autogen/blob/main/python/packages/magentic-one-cli/src/magentic_one_cli/_m1.py) | CLI bootstrap for Magentic-One | [view](https://github.com/microsoft/autogen/blob/main/python/packages/magentic-one-cli/src/magentic_one_cli/_m1.py) |
| [`python/packages/autogen-ext/src/autogen_ext/teams/magentic_one.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/teams/magentic_one.py) | High-level `MagenticOne` class | [view](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/teams/magentic_one.py) |
| [`python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_group_chat.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_group_chat.py) | Group-chat component | [view](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_group_chat.py) |
| [`python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py) | Ledger-driven orchestrator | [view](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py) |
| [`python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_prompts.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_prompts.py) | Prompt templates and `LedgerEntry` schema | [view](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_prompts.py) |

## Summary

- **MagenticOneGroupChat** implements a ledger-driven orchestration pattern that separates high-level planning from step-by-step execution.
- The architecture relies on an **outer loop** for task planning and an **inner loop** for progress tracking via structured JSON ledger entries.
- Specialized agents (**FileSurfer**, **WebSurfer**, **Coder**, **ComputerTerminal**) handle distinct skills while the **MagenticOneOrchestrator** coordinates them through [`autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py).
- You can instantiate the team programmatically via `MagenticOne` from [`autogen_ext/teams/magentic_one.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/teams/magentic_one.py) or run it directly from the CLI using `magentic_one_cli`.

## Frequently Asked Questions

### What is the difference between MagenticOne and MagenticOneGroupChat?

**MagenticOne** is a high-level convenience class defined in [`autogen_ext/teams/magentic_one.py`](https://github.com/microsoft/autogen/blob/main/autogen_ext/teams/magentic_one.py) that instantiates the default set of agents (FileSurfer, WebSurfer, Coder, etc.) and wraps them in a `MagenticOneGroupChat`. **MagenticOneGroupChat** is the underlying group-chat implementation in [`autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_group_chat.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_group_chat.py) that manages the orchestration logic and can be used directly if you need custom agent compositions.

### How does the ledger-driven orchestration prevent infinite loops?

The **MagenticOneOrchestrator** tracks progress through structured **JSON ledger entries** defined in [`_prompts.py`](https://github.com/microsoft/autogen/blob/main/_prompts.py). Each entry includes `is_progress_being_made` and `is_request_satisfied` boolean flags. If the ledger indicates no progress for several consecutive turns, the orchestrator triggers a **re-planning** phase in the outer loop, effectively resetting the strategy rather than repeating failed actions indefinitely.

### Can I add custom agents to a MagenticOneGroupChat?

Yes. While the `MagenticOne` class provides a pre-configured team, you can instantiate **MagenticOneGroupChat** directly from [`autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_group_chat.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_group_chat.py) and pass any list of `ChatAgent` instances to the `participants` parameter. This allows you to mix standard agents like FileSurfer with custom `AssistantAgent` implementations for domain-specific tasks.

### What are the hardware requirements for running MagenticOneGroupChat?

MagenticOneGroupChat requires an **LLM client** (typically GPT-4o via `OpenAIChatCompletionClient` from `autogen_ext/models/openai`) and optionally a **Docker** environment for the default code executor. The orchestrator itself is lightweight Python code, but the WebSurfer agent launches a Chromium browser via Playwright, which requires sufficient memory (typically 4GB+ RAM) and a stable internet connection for web-based tasks.