Added Graph Based Execution functionality to Autogen

[abhinav-aegis]

Why are these changes needed?

Related issue number

Checks

• I've included any doc changes needed for https://microsoft.github.io/autogen/. See https://github.com/microsoft/autogen/blob/main/CONTRIBUTING.md to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

Closes #4623

Add Directed Graph-based Group Chat Execution Engine (DiGraphGroupChat)

This PR introduces a new graph-based execution framework for Autogen agent teams, located under autogen_agentchat/teams/_group_chat/_graph.

Key Features:

• DiGraphGroupChat: A new group chat implementation that executes agents based on a user-defined directed graph (DAG or cyclic with exit conditions).
• AGGraphBuilder: A fluent builder API to programmatically construct graphs.
• MessageFilterAgent: A wrapper to restrict what messages an agent sees before invocation, supporting per-source and per-position filtering.

Capabilities:

• Supports sequential, parallel, conditional, and cyclic workflows.
• Enables fine-grained control over both execution order and message context.
• Compatible with existing Autogen agents and runtime interfaces.

Tests:

• Located in autogen_agentchat/tests/test_group_chat_graph.py
• Includes unit and integration tests covering:
  • Graph validation
  • Execution paths
  • Conditional routing
  • Loops with exit conditions
  • Message filtering

Let me know if anything needs refactoring or if you'd like the components split further.

[codecov]

Codecov Report

Attention: Patch coverage is 90.20772% with 33 lines in your changes missing coverage. Please review.

Project coverage is 78.54%. Comparing base (fcbac2d) to head (c2a1f93).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...at/teams/_group_chat/_graph/_digraph_group_chat.py	87.91%	29 Missing ⚠️
...entchat/teams/_group_chat/_graph/_graph_builder.py	92.68%	3 Missing ⚠️
.../autogen_agentchat/agents/_message_filter_agent.py	98.03%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6333      +/-   ##
==========================================
+ Coverage   78.29%   78.54%   +0.24%     
==========================================
  Files         221      225       +4     
  Lines       16184    16521     +337     
==========================================
+ Hits        12672    12976     +304     
- Misses       3512     3545      +33     

Flag	Coverage Δ
unittests	78.54% <90.20%> (+0.24%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ekzhu]

Thanks @abhinav-aegis, I believe this PR is in a good shape.

I have one last request, that is to make the name shorter and easier to type: GraphGroupChat.

Other things to do before we merge it:

1. Use

.. warning::

   This is an experimental feature, and the API will change in the future releases.

To the GraphGroupChat.

2. Disable condition on the edge for now and create more complete conditions in a subsequent PR.

[abhinav-aegis]

Thanks @abhinav-aegis, I believe this PR is in a good shape.

I have one last request, that is to make the name shorter and easier to type: GraphGroupChat.
Will add.

Other things to do before we merge it:

1. Use

.. warning::

   This is an experimental feature, and the API will change in the future releases.

Will add.

To the GraphGroupChat.

2. Disable condition on the edge for now and create more complete conditions in a subsequent PR.

Hi @ekzhu I must have misunderstood you about the conditional edges. I thought we will keep the text based conditional edges for now as an experimental feature and add the complete implementation in the next PR. The problem with removing them completely is that then even loops will not work (you will always need a conditional edge to exit a loop). In terms of testing, this would be the feature that will require the most amount of feedback from users.

My preference would be to mark this as experimental and work on the more complete implementation or just fix it upfront and merge the full implementation in this PR. The in between option will firstly require too much change to remove the conditional edges and also a primary requirement not available at all.

[ekzhu]

My preference would be to mark this as experimental and work on the more complete implementation or just fix it upfront and merge the full implementation in this PR. The in between option will firstly require too much change to remove the conditional edges and also a primary requirement not available at all.

Okay. I think that makes sense. Though we do need to document it clearly that the current condition in the edge involves only checking substring containment.

[sandangel]

Hi, I wonder if we can have Workflow agent like google adk. I personally feel it's easier to grab my head around the workflow concept rather than having to think about graph, nodes, edges, conditional filter etc like langgraph. Also it seems to be more convenient to compose them.

[abhinav-aegis]

@sandangel Agree with what you are saying. These Sequential agents, Loop agents and parallel agents ADK become special (and most used) scenarios of a General Directed Graph. These would be standard usage patterns. For me the first next step would be to provide an easy API to create the patterns that you mentioned so that the user can just create the require workflows easily.

The current pull request sets of the execution framework that would allow us to create the patters in ADK easily. Would be a part of the next pull request along with better definitions for conditions.

[abhinav-aegis]

My preference would be to mark this as experimental and work on the more complete implementation or just fix it upfront and merge the full implementation in this PR. The in between option will firstly require too much change to remove the conditional edges and also a primary requirement not available at all.

Okay. I think that makes sense. Though we do need to document it clearly that the current condition in the edge involves only checking substring containment.

Updated the Code with the cosmetic changes you requested.

DiGraphGroupChat -> AGGraph and similar changes for Manager, and Builder. Hopefully this is simpler. I also clearly marked everything as experimental (including conditional edges). I created a separate pull request for AGGraph documentation and a user guide to show how one could get started.

[ekzhu]

Updated the Code with the cosmetic changes you requested.

DiGraphGroupChat -> AGGraph and similar changes for Manager, and Builder. Hopefully this is simpler. I also clearly marked everything as experimental (including conditional edges). I created a separate pull request for AGGraph documentation and a user guide to show how one could get started.

Thanks! Though I haven't seen the changes on adding experimental notice in this branch?

[abhinav-aegis]

Updated the Code with the cosmetic changes you requested.

DiGraphGroupChat -> AGGraph and similar changes for Manager, and Builder. Hopefully this is simpler. I also clearly marked everything as experimental (including conditional edges). I created a separate pull request for AGGraph documentation and a user guide to show how one could get started.

Thanks! Though I haven't seen the changes on adding experimental notice in this branch?

Sorry about that! I thought I pushed to both this branch and the docs branch. Done now.

[ekzhu]

Okay. Why renaming it to AGGraph now? I thought we were going for just Graph. I think "Graph" is shorter and more succinct, it is already in AutoGen package so I feel "AG" bit is redundant.

[abhinav-aegis]

Okay. Why renaming it to AGGraph now? I thought we were going for just Graph. I think "Graph" is shorter and more succinct, it is already in AutoGen package so I feel "AG" bit is redundant.

Done.

[ekzhu]

Sorry I might have confused you regarding naming of the classes. What I meant was to name the team "GraphGroupChat" and the graph "Graph". I can make the changes directly and get the PR finished

[abhinav-aegis]

Sorry I might have confused you regarding naming of the classes. What I meant was to name the team "GraphGroupChat" and the graph "Graph". I can make the changes directly and get the PR finished

No worries. Please go ahead and make the changes. The only thing to keep in mind is that the documentation needs to be kept in Sync (see #6417). If you are okay with the documentation, maybe you can just make the name changes there and just merge in that pull request instead of this one.

For what it's worth, in my opinion, Graph (or GraphGroup) might be a better name than GraphGroupChat - The suffix Chat is a bit misleading for Graph/workflow type execution order. Having said that, happy to go with whatever you pick :).

[ekzhu]

For what it's worth, in my opinion, Graph (or GraphGroup) might be a better name than GraphGroupChat - The suffix Chat is a bit misleading for Graph/workflow type execution order. Having said that, happy to go with whatever you pick :).

Makes sense. How about "GraphFlow"? This way it is clear it is not a "Chat".

[abhinav-aegis]

For what it's worth, in my opinion, Graph (or GraphGroup) might be a better name than GraphGroupChat - The suffix Chat is a bit misleading for Graph/workflow type execution order. Having said that, happy to go with whatever you pick :).

Makes sense. How about "GraphFlow"? This way it is clear it is not a "Chat".

I like that.