# Building Nested Group Chat Hierarchies with DiGraphGroupChat in Autogen

> Discover how Microsoft Autogen builds nested group chat hierarchies using DiGraphGroupChat. Model conversations as directed graphs for advanced agent communication and conditional message routing.

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

---

**Microsoft Autogen enables arbitrarily deep nested group chat hierarchies by modeling conversations as directed graphs (DiGraph), where each node represents an agent or sub-group, and edges define conditional message routing between parent and child groups.**

Building nested group chat hierarchies with DiGraphGroupChat allows you to orchestrate complex multi-agent workflows in Microsoft Autogen. The framework treats group chats as directed graphs where nodes can be individual agents or entire sub-groups, enabling recursive nesting that mirrors organizational structures. This architecture, implemented in the `autogen_agentchat` package, provides precise control over conversation flow through conditional edges and automatic cycle detection.

## Core DiGraph Components for Hierarchical Chats

The **DiGraphGroupChat** system relies on four foundational classes defined in [`autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py):

- **`DiGraphNode`** – A Pydantic model that stores an agent's name and a list of outgoing edges. Each node represents a participant in the chat hierarchy, which can be either a single agent or an entire sub-group manager.

- **`DiGraphEdge`** – Describes a directed edge containing the *target* node name and optional **`condition`** or **`activation_condition`** parameters. These conditions control when the edge is traversed, enabling logic like "route to TeamA only if trigger1 is present."

- **`DiGraph`** – The container class that maps node names to `DiGraphNode` instances. It validates the graph structure (detecting cycles and missing nodes) and provides utilities for traversal and serialization via `model_dump_json()` and `model_validate_json()`.

- **`DiGraphBuilder`** – Located in [`autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py), this helper constructs a `DiGraph` from user-friendly dictionaries or YAML/JSON specifications, simplifying the creation of complex nested configurations.

## How Message Routing Works in Nested Hierarchies

The runtime execution follows a strict traversal protocol managed by **`GroupChatManager`**:

1. **Graph Definition** – You instantiate a `DiGraph` with nodes and edges describing your hierarchy, from root groups down to leaf agents.

2. **Manager Instantiation** – `GroupChatManager` receives the `DiGraph` and creates separate agent instances for every node. When a node represents a nested group, you pass sub-managers via the `sub_managers` parameter.

3. **Message Flow** – When an agent sends a message, the manager examines outgoing edges from the current node. If an edge includes a **condition**, the manager evaluates it against the message content. Passing conditions forward the message to the target node, which becomes the new active participant.

4. **Nested Execution** – Because each node can itself be a `GroupChatManager`, the parent graph treats the child manager as a single node. Control returns to the parent only after the child group reaches a termination condition or exhausts its own edges.

5. **Cycle Prevention** – The `DiGraph` validator detects cycles lacking termination conditions and raises an error. Conditional cycles are explicitly permitted (e.g., "repeat until trigger X"), allowing iterative refinement loops within nested structures.

6. **Persistence** – The entire hierarchy serializes to JSON via Pydantic's `model_dump_json()`, enabling you to save complex organizational topologies and reconstruct them later with `model_validate_json()`.

## Implementing Nested Group Chat Hierarchies

### Simple Two-Level Hierarchy

Create a root chat that spawns a team, which then spawns a sub-team:

```python
from autogen_agentchat.teams._group_chat._graph._digraph_group_chat import (
    DiGraph, DiGraphNode, DiGraphEdge
)
from autogen_agentchat.teams.group_chat_manager import GroupChatManager

# Define the graph structure

graph = DiGraph(
    {
        "Root": DiGraphNode(
            name="Root",
            edges=[DiGraphEdge(target="TeamA")]
        ),
        "TeamA": DiGraphNode(
            name="TeamA",
            edges=[DiGraphEdge(target="SubTeam1")]
        ),
        "SubTeam1": DiGraphNode(name="SubTeam1", edges=[])
    }
)

# Instantiate and run

manager = GroupChatManager(graph=graph, name="RootChat")
manager.run()

```

### Conditional Branching Between Teams

Route messages to different teams based on content triggers:

```python
graph = DiGraph(
    {
        "Root": DiGraphNode(
            name="Root",
            edges=[
                DiGraphEdge(target="TeamA", condition="trigger1"),
                DiGraphEdge(target="TeamB", condition="trigger2")
            ]
        ),
        "TeamA": DiGraphNode(name="TeamA", edges=[]),
        "TeamB": DiGraphNode(name="TeamB", edges=[])
    }
)

```

The manager evaluates the `condition` string against incoming messages to determine whether to activate `TeamA` or `TeamB`.

### Deep Nesting with Child Managers

Embed a complete sub-hierarchy within a parent graph by passing child managers:

```python
from autogen_agentchat.teams.group_chat_manager import GroupChatManager

# Parent graph references child group as a single node

parent_graph = DiGraph(
    {
        "Root": DiGraphNode(name="Root", edges=[DiGraphEdge(target="ChildGroup")]),
        "ChildGroup": DiGraphNode(name="ChildGroup", edges=[]),
    }
)

# Child graph defines its own internal workflow

child_graph = DiGraph(
    {
        "SubRoot": DiGraphNode(name="SubRoot", edges=[DiGraphEdge(target="Leaf")]),
        "Leaf": DiGraphNode(name="Leaf", edges=[])
    }
)

# Wire nested managers

child_manager = GroupChatManager(graph=child_graph, name="ChildGroup")
parent_manager = GroupChatManager(
    graph=parent_graph,
    name="RootChat",
    sub_managers={"ChildGroup": child_manager}
)

parent_manager.run()

```

When `RootChat` activates `ChildGroup`, the child manager executes its internal graph independently before returning control upstream.

### Persisting Graph Structures

Serialize complex hierarchies for distributed deployment or session recovery:

```python

# Export to JSON

json_str = graph.model_dump_json()

# Restore in another process

restored_graph = DiGraph.model_validate_json(json_str)

```

This preserves the exact node-to-edge relationships and conditional logic required to recreate the nested hierarchy elsewhere.

## Key Source Files and Architecture

The DiGraphGroupChat implementation spans these critical files in the `autogen_agentchat` package:

- **[`autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py)** – Core models (`DiGraph`, `DiGraphNode`, `DiGraphEdge`) with validation logic for lines 25-115.

- **[`autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py)** – The `DiGraphBuilder` utility that simplifies graph construction from declarative configurations.

- **[`autogen_agentchat/teams/group_chat_manager.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/group_chat_manager.py)** – Runtime engine that instantiates agents, routes messages according to graph edges, and manages nested sub-managers.

- **[`tests/test_group_chat_graph.py`](https://github.com/microsoft/autogen/blob/main/tests/test_group_chat_graph.py)** – Comprehensive test suite demonstrating graph configurations, conditional edges, cycle detection, and nested group interactions.

- **[`samples/core_distributed-group-chat/run_group_chat_manager.py`](https://github.com/microsoft/autogen/blob/main/samples/core_distributed-group-chat/run_group_chat_manager.py)** – Example script wiring DiGraph hierarchies to distributed deployments.

## Summary

- **DiGraphGroupChat** models conversations as directed graphs where nodes are agents or sub-groups and edges define message routing rules.

- **`DiGraphNode`** and **`DiGraphEdge`** provide the structural foundation, while **`DiGraph`** handles validation and serialization in [`autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py).

- **Nesting** occurs when a `GroupChatManager` is registered as a sub-manager in another manager's `sub_managers` dictionary, allowing recursive hierarchy depths.

- **Conditional routing** uses the `condition` parameter on edges to dynamically select conversation paths based on message content.

- **Cycle detection** prevents infinite loops by validating graphs at initialization, though intentional conditional cycles are supported for iterative workflows.

- **Serialization** via Pydantic methods enables persistence and transmission of complex chat topologies across processes.

## Frequently Asked Questions

### What is DiGraphGroupChat in Autogen?

**DiGraphGroupChat** is an Autogen architecture that represents group chats as directed graphs rather than simple round-robin or random selections. Each node in the graph is a `DiGraphNode` representing an agent or nested group, and edges (`DiGraphEdge`) define allowed conversation flows, including conditional branching logic. This enables complex hierarchical workflows where parent groups can spawn child groups indefinitely.

### How do you prevent infinite loops in nested group chats?

The `DiGraph` class automatically validates the graph structure upon instantiation in [`autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py`](https://github.com/microsoft/autogen/blob/main/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py). It detects cycles that lack termination conditions and raises validation errors before execution begins. You can create intentional loops by adding conditional edges (e.g., `condition="retry_needed"`), which require explicit trigger content to cycle back, preventing runaway execution.

### Can you serialize and reuse a DiGraph hierarchy across sessions?

Yes. Because `DiGraph` inherits from Pydantic's `BaseModel`, you can call `model_dump_json()` to export the entire hierarchy—including all nodes, edges, and conditions—to a JSON string. Later, use `DiGraph.model_validate_json()` to reconstruct the exact graph structure. This supports saving complex organizational topologies and deploying them across distributed environments.

### How does conditional routing work between parent and child groups?

When `GroupChatManager` processes a message, it evaluates the `condition` or `activation_condition` attribute on each outgoing `DiGraphEdge`. If the condition matches the message content (e.g., a specific trigger string), the manager forwards the message to the target node. If the target is a nested child manager (registered in `sub_managers`), the parent delegates control entirely to the child until that sub-graph completes its execution, at which point the parent resumes its own traversal logic.