add activation group for workflow with multiple cycles

[ZenWayne]

Why are these changes needed?

1. problem
   When the GraphFlowManager encounters cycles, it tracks remaining indegree counts for the node's activation. However, this tracking mechanism has a flaw when dealing with cycles. When a node first enters a cycle, the GraphFlowManager evaluates all remaining incoming edges, including those that loop back to the origin node. If the activation prerequisites are not satisfied at that moment, the workflow will eventually finish because the _remaining counter never reaches zero, preventing the select_speaker() method from selecting any agents for execution.
2. solution
   change activation map to 2 layer for ditinguish remaining inside different cycle and outside the cycle.
   add a activation group and policy property for edge, compute the remaining map when GraphFlowManager is init and check the remaining map with activation group to avoid checking the loop back edges

Related issue number

#6710

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.

[ZenWayne]

@ekzhu

[Copilot]

Pull Request Overview

This pull request addresses a flaw in the activation tracking mechanism when handling cycles in the workflow, implementing a two-layer activation map to distinguish between edges inside a cycle and outside the cycle. Key changes include:

• Renaming and updating test functions to verify behavior with self cycles and multiple cycles.
• Adding new properties (activation_group and activation_condition) and validators to DiGraphEdge.
• Updating state tracking and lookup methods in GraphFlowManagerState to use a two-layered remaining map.

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
python/packages/autogen-agentchat/tests/test_group_chat_graph.py	Renamed and added tests to validate cycle handling with new activation groups.
python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py	Updated edge and state logic to support a two-layer activation map for handling cycles.

Comments suppressed due to low confidence (3)

python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py:440

• [nitpick] Consider adding a comment to explain the rationale for resetting the remaining count from _origin_remaining in _reset_triggered_activation_groups to improve maintainability.

                    self._remaining[speaker][activation_group] = self._origin_remaining[speaker][activation_group]

python/packages/autogen-agentchat/tests/test_group_chat_graph.py:722

• [nitpick] Ensure the new test name clearly reflects its purpose of testing self-cycle activation behavior, which is key to verifying the updated activation grouping mechanism.

async def test_digraph_group_chat_loop_with_self_cycle(runtime: AgentRuntime | None) -> None:

python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py:122

• The removal of the self-loop check in get_parents now includes self-loop edges as parents. Please confirm this change is intentional and aligns with the revised activation grouping logic.

                parents[edge.target].append(node.name)

[ekzhu]

Thanks for the PR.

• Could you add explanation to the new fields "activation_group" and "activation_condition", and in what scenario user need to use them.
• Could you also add the activation group feature to the digraph builder API?
• Add a code example to the API doc of GraphFlow to show how to use the builder API to create a graph flow with two different cycles involving a single node. Ensure the code block passes Pyright check and fomratted like the existing ones.

[ZenWayne]

Thanks for the code review! really appreciate it. I already finish the code and the api doc example, Could you review it again

[codecov]

Codecov Report

Attention: Patch coverage is 93.40659% with 6 lines in your changes missing coverage. Please review.

Project coverage is 79.75%. Comparing base (c5b893d) to head (e4d30dd).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...at/teams/_group_chat/_graph/_digraph_group_chat.py	93.02%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6711      +/-   ##
==========================================
+ Coverage   79.70%   79.75%   +0.04%     
==========================================
  Files         232      232              
  Lines       17329    17401      +72     
==========================================
+ Hits        13812    13878      +66     
- Misses       3517     3523       +6     

Flag	Coverage Δ
unittests	79.75% <93.40%> (+0.04%)	⬆️

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]

Please see python/README.md for poe tasks for formatting. Also, would be great if we can bump up the unit test for the any case. See: https://app.codecov.io/gh/microsoft/autogen/pull/6711?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=microsoft#bc50044e811136fbc71a280d52f2a023-R425

[ZenWayne]

All set