A programming framework for agentic AI
add activation group for workflow with multiple cycles (#6711)
Zen9b8dc8d70787
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.pyindex 5e0981d02..aaca418df 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py@@ -50,6 +50,25 @@ class DiGraphEdge(BaseModel):# Using Field to exclude the condition in serialization if it's a callablecondition_function: Callable[[BaseChatMessage], bool] | None = Field(default=None, exclude=True)+ activation_group: str = Field(default="")+ """Group identifier for forward dependencies.++ When multiple edges point to the same target node, they are grouped by this field.+ This allows distinguishing between different cycles or dependency patterns.++ Example: In a graph containing a cycle like A->B->C->B, the two edges pointing to B (A->B and C->B)+ can be in different activation groups to control how B is activated.+ Defaults to the target node name if not specified.+ """+ activation_condition: Literal["all", "any"] = "all"+ """Determines how forward dependencies within the same activation_group are evaluated.++ - "all": All edges in this activation group must be satisfied before the target node can execute+ - "any": Any single edge in this activation group being satisfied allows the target node to execute++ This is used to handle complex dependency patterns in cyclic graphs where multiple+ paths can lead to the same target node.+ """@model_validator(mode="after")def _validate_condition(self) -> "DiGraphEdge":@@ -59,6 +78,11 @@ class DiGraphEdge(BaseModel):# For serialization purposes, we'll set the condition to None# when storing as a pydantic model/dictobject.__setattr__(self, "condition", None)++ # Set activation_group to target if not already set+ if not self.activation_group:+ self.activation_group = self.target+return selfdef check_condition(self, message: BaseChatMessage) -> bool:@@ -112,8 +136,7 @@ class DiGraph(BaseModel):parents: Dict[str, List[str]] = {node: [] for node in self.nodes}for node in self.nodes.values():for edge in node.edges:- if edge.target != node.name:- parents[edge.target].append(node.name)+ parents[edge.target].append(node.name)return parentsdef get_start_nodes(self) -> Set[str]:@@ -206,8 +229,79 @@ class DiGraph(BaseModel):if has_condition and has_unconditioned:raise ValueError(f"Node '{node.name}' has a mix of conditional and unconditional edges.")+ # Validate activation conditions across all edges in the graph+ self._validate_activation_conditions()+self._has_cycles = self.has_cycles_with_exit()+ def _validate_activation_conditions(self) -> None:+ """Validate that all edges pointing to the same target node have consistent activation_condition values.++ Raises:+ ValueError: If edges pointing to the same target have different activation_condition values+ """+ target_activation_conditions: Dict[str, Dict[str, str]] = {} # target_node -> {activation_group -> condition}++ for node in self.nodes.values():+ for edge in node.edges:+ target = edge.target # The target node this edge points to+ activation_group = edge.activation_group++ if target not in target_activation_conditions:+ target_activation_conditions[target] = {}++ if activation_group in target_activation_conditions[target]:+ if target_activation_conditions[target][activation_group] != edge.activation_condition:+ # Find the source node that has the conflicting condition+ conflicting_source = self._find_edge_source_by_target_and_group(+ target, activation_group, target_activation_conditions[target][activation_group]+ )+ raise ValueError(+ f"Conflicting activation conditions for target '{target}' group '{activation_group}': "+ f"'{target_activation_conditions[target][activation_group]}' (from node '{conflicting_source}') "+ f"and '{edge.activation_condition}' (from node '{node.name}')"+ )+ else:+ target_activation_conditions[target][activation_group] = edge.activation_condition++ def _find_edge_source_by_target_and_group(+ self, target: str, activation_group: str, activation_condition: str+ ) -> str:+ """Find the source node that has an edge pointing to the given target with the given activation_group and activation_condition."""+ for node_name, node in self.nodes.items():+ for edge in node.edges:+ if (+ edge.target == target+ and edge.activation_group == activation_group+ and edge.activation_condition == activation_condition+ ):+ return node_name+ return "unknown"++ def get_remaining_map(self) -> Dict[str, Dict[str, int]]:+ """Get the remaining map that tracks how many edges point to each target node with each activation group.++ Returns:+ Dictionary mapping target nodes to their activation groups and remaining counts+ """++ remaining_map: Dict[str, Dict[str, int]] = {}++ for node in self.nodes.values():+ for edge in node.edges:+ target = edge.target+ activation_group = edge.activation_group++ if target not in remaining_map:+ remaining_map[target] = {}++ if activation_group not in remaining_map[target]:+ remaining_map[target][activation_group] = 0++ remaining_map[target][activation_group] += 1++ return remaining_map+class GraphFlowManagerState(BaseGroupChatManagerState):"""Tracks active execution state for DAG-based execution."""@@ -254,18 +348,51 @@ class GraphFlowManager(BaseGroupChatManager):self._parents = graph.get_parents()# Lookup table for outgoing edges for each node.self._edges: Dict[str, List[DiGraphEdge]] = {n: node.edges for n, node in graph.nodes.items()}- # Activation lookup table for each node.- self._activation: Dict[str, Literal["any", "all"]] = {n: node.activation for n, node in graph.nodes.items()}+ # Build activation and enqueued_any lookup tables by collecting all edges and grouping by target node+ self._build_lookup_tables(graph)++ # Track which activation groups were triggered for each node+ self._triggered_activation_groups: Dict[str, Set[str]] = {}# === Mutable states for the graph execution ===# Count the number of remaining parents to activate each node.- self._remaining: Counter[str] = Counter({n: len(p) for n, p in self._parents.items()})- # Lookup table for nodes that have been enqueued through an any activation.- # This is used to prevent re-adding the same node multiple times.- self._enqueued_any: Dict[str, bool] = {n: False for n in graph.nodes}+ self._remaining: Dict[str, Counter[str]] = {+ target: Counter(groups) for target, groups in graph.get_remaining_map().items()+ }+ # cache for remaining+ self._origin_remaining: Dict[str, Dict[str, int]] = {+ target: Counter(groups) for target, groups in self._remaining.items()+ }+# Ready queue for nodes that are ready to execute, starting with the start nodes.self._ready: Deque[str] = deque([n for n in graph.get_start_nodes()])+ def _build_lookup_tables(self, graph: DiGraph) -> None:+ """Build activation and enqueued_any lookup tables by collecting all edges and grouping by target node.++ Args:+ graph: The directed graph+ """+ self._activation: Dict[str, Dict[str, Literal["any", "all"]]] = {}+ self._enqueued_any: Dict[str, Dict[str, bool]] = {}++ for node in graph.nodes.values():+ for edge in node.edges:+ target = edge.target+ activation_group = edge.activation_group++ # Build activation lookup+ if target not in self._activation:+ self._activation[target] = {}+ if activation_group not in self._activation[target]:+ self._activation[target][activation_group] = edge.activation_condition++ # Build enqueued_any lookup+ if target not in self._enqueued_any:+ self._enqueued_any[target] = {}+ if activation_group not in self._enqueued_any[target]:+ self._enqueued_any[target][activation_group] = False+async def update_message_thread(self, messages: Sequence[BaseAgentEvent | BaseChatMessage]) -> None:await super().update_message_thread(messages)@@ -282,16 +409,55 @@ class GraphFlowManager(BaseGroupChatManager):# Use the new check_condition method that handles both string and callable conditionsif not edge.check_condition(message):continue- if self._activation[edge.target] == "all":- self._remaining[edge.target] -= 1- if self._remaining[edge.target] == 0:++ target = edge.target+ activation_group = edge.activation_group++ if self._activation[target][activation_group] == "all":+ self._remaining[target][activation_group] -= 1+ if self._remaining[target][activation_group] == 0:# If all parents are done, add to the ready queue.- self._ready.append(edge.target)+ self._ready.append(target)+ # Track which activation group was triggered+ self._save_triggered_activation_group(target, activation_group)else:# If activation is any, add to the ready queue if not already enqueued.- if not self._enqueued_any[edge.target]:- self._ready.append(edge.target)- self._enqueued_any[edge.target] = True+ if not self._enqueued_any[target][activation_group]:+ self._ready.append(target)+ self._enqueued_any[target][activation_group] = True+ # Track which activation group was triggered+ self._save_triggered_activation_group(target, activation_group)++ def _save_triggered_activation_group(self, target: str, activation_group: str) -> None:+ """Save which activation group was triggered for a target node.++ Args:+ target: The target node that was triggered+ activation_group: The activation group that caused the trigger+ """+ if target not in self._triggered_activation_groups:+ self._triggered_activation_groups[target] = set()+ self._triggered_activation_groups[target].add(activation_group)++ def _reset_triggered_activation_groups(self, speaker: str) -> None:+ """Reset the bookkeeping for the specific activation groups that were triggered for a speaker.++ Args:+ speaker: The speaker node to reset activation groups for+ """+ if speaker not in self._triggered_activation_groups:+ return++ for activation_group in self._triggered_activation_groups[speaker]:+ if self._activation[speaker][activation_group] == "any":+ self._enqueued_any[speaker][activation_group] = False+ else:+ # Reset the remaining count for this activation group using the graph's original count+ if speaker in self._remaining and activation_group in self._remaining[speaker]:+ self._remaining[speaker][activation_group] = self._origin_remaining[speaker][activation_group]++ # Clear the triggered activation groups for this speaker+ self._triggered_activation_groups[speaker].clear()async def select_speaker(self, thread: Sequence[BaseAgentEvent | BaseChatMessage]) -> List[str]:# Drain the ready queue for the next set of speakers.@@ -299,11 +465,9 @@ class GraphFlowManager(BaseGroupChatManager):while self._ready:speaker = self._ready.popleft()speakers.append(speaker)- # Reset the bookkeeping for the node that were selected.- if self._activation[speaker] == "any":- self._enqueued_any[speaker] = False- else:- self._remaining[speaker] = len(self._parents[speaker])++ # Reset the bookkeeping for the specific activation groups that were triggered+ self._reset_triggered_activation_groups(speaker)# If there are no speakers, trigger the stop agent.if not speakers:@@ -319,7 +483,7 @@ class GraphFlowManager(BaseGroupChatManager):state = {"message_thread": [message.dump() for message in self._message_thread],"current_turn": self._current_turn,- "remaining": dict(self._remaining),+ "remaining": {target: dict(counter) for target, counter in self._remaining.items()},"enqueued_any": dict(self._enqueued_any),"ready": list(self._ready),}@@ -329,7 +493,7 @@ class GraphFlowManager(BaseGroupChatManager):"""Restore execution state from saved data."""self._message_thread = [self._message_factory.create(msg) for msg in state["message_thread"]]self._current_turn = state["current_turn"]- self._remaining = Counter(state["remaining"])+ self._remaining = {target: Counter(groups) for target, groups in state["remaining"].items()}self._enqueued_any = state["enqueued_any"]self._ready = deque(state["ready"])@@ -339,8 +503,8 @@ class GraphFlowManager(BaseGroupChatManager):self._message_thread.clear()if self._termination_condition:await self._termination_condition.reset()- self._remaining = Counter({n: len(p) for n, p in self._parents.items()})- self._enqueued_any = {n: False for n in self._graph.nodes}+ self._remaining = {target: Counter(groups) for target, groups in self._graph.get_remaining_map().items()}+ self._enqueued_any = {n: {g: False for g in self._enqueued_any[n]} for n in self._enqueued_any}self._ready = deque([n for n in self._graph.get_start_nodes()])diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.pyindex 2f531e89b..e083415db 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py@@ -74,6 +74,23 @@ class DiGraphBuilder:>>> builder.add_edge(agent_b, agent_a, condition=lambda msg: "loop" in msg.to_model_text())>>> # Add exit condition to break the loop>>> builder.add_edge(agent_b, agent_c, condition=lambda msg: "loop" not in msg.to_model_text())++ Example — Loop with multiple paths to the same node: A → B → C → B:+ >>> builder = GraphBuilder()+ >>> builder.add_node(agent_a).add_node(agent_b).add_node(agent_c)+ >>> builder.add_edge(agent_a, agent_b)+ >>> builder.add_edge(agent_b, agent_c)+ >>> builder.add_edge(agent_c, agent_b, activation_group="loop_back")++ Example — Loop with multiple paths to the same node with any activation condition: A → B → (C1, C2) → B → E(exit):+ >>> builder = GraphBuilder()+ >>> builder.add_node(agent_a).add_node(agent_b).add_node(agent_c1).add_node(agent_c2).add_node(agent_e)+ >>> builder.add_edge(agent_a, agent_b)+ >>> builder.add_edge(agent_b, agent_c1)+ >>> builder.add_edge(agent_b, agent_c2)+ >>> builder.add_edge(agent_b, agent_e, condition="exit")+ >>> builder.add_edge(agent_c1, agent_b, activation_group="loop_back_group", activation_condition="any")+ >>> builder.add_edge(agent_c2, agent_b, activation_group="loop_back_group", activation_condition="any")"""def __init__(self) -> None:@@ -97,6 +114,8 @@ class DiGraphBuilder:source: Union[str, ChatAgent],target: Union[str, ChatAgent],condition: Optional[Union[str, Callable[[BaseChatMessage], bool]]] = None,+ activation_group: Optional[str] = None,+ activation_condition: Optional[Literal["all", "any"]] = None,) -> "DiGraphBuilder":"""Add a directed edge from source to target, optionally with a condition.@@ -120,8 +139,18 @@ class DiGraphBuilder:raise ValueError(f"Source node '{source_name}' must be added before adding an edge.")if target_name not in self.nodes:raise ValueError(f"Target node '{target_name}' must be added before adding an edge.")-- self.nodes[source_name].edges.append(DiGraphEdge(target=target_name, condition=condition))+ if activation_group is None:+ activation_group = target_name+ if activation_condition is None:+ activation_condition = "all"+ self.nodes[source_name].edges.append(+ DiGraphEdge(+ target=target_name,+ condition=condition,+ activation_group=activation_group,+ activation_condition=activation_condition,+ )+ )return selfdef add_conditional_edges(diff --git a/python/packages/autogen-agentchat/tests/test_group_chat_graph.py b/python/packages/autogen-agentchat/tests/test_group_chat_graph.pyindex fc26a82b7..33f57e697 100644--- a/python/packages/autogen-agentchat/tests/test_group_chat_graph.py+++ b/python/packages/autogen-agentchat/tests/test_group_chat_graph.py@@ -1,4 +1,5 @@import asyncio+import refrom typing import AsyncGenerator, List, Sequencefrom unittest.mock import patch@@ -247,6 +248,32 @@ def test_cycle_detection_without_exit_condition() -> None:graph.has_cycles_with_exit()+def test_different_activation_groups_detection() -> None:+ """Test different activation groups."""+ graph = DiGraph(+ nodes={+ "A": DiGraphNode(+ name="A",+ edges=[+ DiGraphEdge(target="B"),+ DiGraphEdge(target="C"),+ ],+ ),+ "B": DiGraphNode(name="B", edges=[DiGraphEdge(target="D", activation_condition="all")]),+ "C": DiGraphNode(name="C", edges=[DiGraphEdge(target="D", activation_condition="any")]),+ "D": DiGraphNode(name="D", edges=[]),+ }+ )+ with pytest.raises(+ ValueError,+ match=re.escape(+ "Conflicting activation conditions for target 'D' group 'D': "+ "'all' (from node 'B') and 'any' (from node 'C')"+ ),+ ):+ graph.graph_validate()++def test_validate_graph_success() -> None:"""Test successful validation of a valid graph."""graph = DiGraph(@@ -719,7 +746,7 @@ async def test_digraph_group_chat_loop_with_exit_condition(runtime: AgentRuntime@pytest.mark.asyncio-async def test_digraph_group_chat_loop_with_exit_condition_2(runtime: AgentRuntime | None) -> None:+async def test_digraph_group_chat_loop_with_self_cycle(runtime: AgentRuntime | None) -> None:# Agents A and C: Echo Agentsagent_a = _EchoAgent("A", description="Echo agent A")agent_c = _EchoAgent("C", description="Echo agent C")@@ -740,7 +767,11 @@ async def test_digraph_group_chat_loop_with_exit_condition_2(runtime: AgentRuntinodes={"A": DiGraphNode(name="A", edges=[DiGraphEdge(target="B")]),"B": DiGraphNode(- name="B", edges=[DiGraphEdge(target="C", condition="exit"), DiGraphEdge(target="B", condition="loop")]+ name="B",+ edges=[+ DiGraphEdge(target="C", condition="exit"),+ DiGraphEdge(target="B", condition="loop", activation_group="B_loop"),+ ],),"C": DiGraphNode(name="C", edges=[]),},@@ -777,6 +808,96 @@ async def test_digraph_group_chat_loop_with_exit_condition_2(runtime: AgentRuntiassert result.messages[-1].source == _DIGRAPH_STOP_AGENT_NAME+async def test_digraph_group_chat_loop_with_two_cycles(runtime: AgentRuntime | None) -> None:+ # Agents A and C: Echo Agents+ agent_a = _EchoAgent("A", description="Echo agent A")+ agent_b = _EchoAgent("B", description="Echo agent B")+ agent_c = _EchoAgent("C", description="Echo agent C")+ agent_e = _EchoAgent("E", description="Echo agent E")++ # Replay model client for agent B+ model_client = ReplayChatCompletionClient(+ chat_completions=[+ "to_x", # First time O will branch to B+ "to_o", # X will go back to O+ "to_y", # Second time O will branch to C+ "to_o", # Y will go back to O+ "exit", # Third time O will say exit+ ]+ )+ # Agent o, b, c: Assistant Agent using Replay Client+ agent_o = AssistantAgent("O", description="Decision agent o", model_client=model_client)+ agent_x = AssistantAgent("X", description="Decision agent x", model_client=model_client)+ agent_y = AssistantAgent("Y", description="Decision agent y", model_client=model_client)++ # DiGraph:+ #+ # A+ # / \+ # B C+ # \ |+ # X = O = Y (bidirectional)+ # |+ # E(exit)+ graph = DiGraph(+ nodes={+ "A": DiGraphNode(name="A", edges=[DiGraphEdge(target="B"), DiGraphEdge(target="C")]),+ "B": DiGraphNode(+ name="B", edges=[DiGraphEdge(target="O")]+ ), # default activation group name is same as target node name "O"+ "C": DiGraphNode(+ name="C", edges=[DiGraphEdge(target="O")]+ ), # default activation group name is same as target node name "O"+ "O": DiGraphNode(+ name="O",+ edges=[+ DiGraphEdge(target="X", condition="to_x"),+ DiGraphEdge(target="Y", condition="to_y"),+ DiGraphEdge(target="E", condition="exit"),+ ],+ ),+ "X": DiGraphNode(name="X", edges=[DiGraphEdge(target="O", condition="to_o", activation_group="x_o_loop")]),+ "Y": DiGraphNode(name="Y", edges=[DiGraphEdge(target="O", condition="to_o", activation_group="y_o_loop")]),+ "E": DiGraphNode(name="E", edges=[]),+ },+ default_start_node="A",+ )++ team = GraphFlow(+ participants=[agent_a, agent_o, agent_b, agent_c, agent_x, agent_y, agent_e],+ graph=graph,+ runtime=runtime,+ termination_condition=MaxMessageTermination(20),+ )++ # Run+ result = await team.run(task="Start")++ # Assert message order+ expected_sources = [+ "user",+ "A",+ "B",+ "C",+ "O",+ "X", # O -> X+ "O", # X -> O+ "Y", # O -> Y+ "O", # Y -> O+ "E", # O -> E+ _DIGRAPH_STOP_AGENT_NAME,+ ]++ actual_sources = [m.source for m in result.messages]++ assert actual_sources == expected_sources+ assert result.stop_reason is not None+ assert result.messages[-2].source == "E"+ assert any(m.content == "exit" for m in result.messages[:-1]) # type: ignore[attr-defined,union-attr]+ assert result.messages[-1].source == _DIGRAPH_STOP_AGENT_NAME++@pytest.mark.asyncioasync def test_digraph_group_chat_parallel_join_any_1(runtime: AgentRuntime | None) -> None:agent_a = _EchoAgent("A", description="Echo agent A")@@ -787,9 +908,9 @@ async def test_digraph_group_chat_parallel_join_any_1(runtime: AgentRuntime | Nograph = DiGraph(nodes={"A": DiGraphNode(name="A", edges=[DiGraphEdge(target="B"), DiGraphEdge(target="C")]),- "B": DiGraphNode(name="B", edges=[DiGraphEdge(target="D")]),- "C": DiGraphNode(name="C", edges=[DiGraphEdge(target="D")]),- "D": DiGraphNode(name="D", edges=[], activation="any"),+ "B": DiGraphNode(name="B", edges=[DiGraphEdge(target="D", activation_group="any")]),+ "C": DiGraphNode(name="C", edges=[DiGraphEdge(target="D", activation_group="any")]),+ "D": DiGraphNode(name="D", edges=[]),})diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/graph-flow.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/graph-flow.ipynbindex a96b2df2b..d267257b4 100644--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/graph-flow.ipynb+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/graph-flow.ipynb@@ -577,6 +577,220 @@"# Run the flow and pretty print the output in the console\n","await Console(flow.run_stream(task=\"Brainstorm ways to reduce plastic waste.\"))"]+ },+ {+ "cell_type": "markdown",+ "id": "4b39f9d6",+ "metadata": {},+ "source": [+ "## 🔁 Advanced Example: Cycles With Activation Group Examples\n",+ "\n",+ "The following examples demonstrate how to use `activation_group` and `activation_condition` to handle complex dependency patterns in cyclic graphs, especially when multiple paths lead to the same target node."+ ]+ },+ {+ "cell_type": "markdown",+ "id": "791a4c47",+ "metadata": {},+ "source": [+ "### Example 1: Loop with Multiple Paths - \"All\" Activation (A→B→C→B)\n",+ "\n",+ "In this scenario, we have A → B → C → B, where B has two incoming edges (from A and from C). By default, B requires **all** its dependencies to be satisfied before executing.\n",+ "\n",+ "This example shows a review loop where both the initial input (A) and the feedback (C) must be processed before B can execute again."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "id": "384f5831",+ "metadata": {},+ "outputs": [],+ "source": [+ "from autogen_agentchat.agents import AssistantAgent\n",+ "from autogen_agentchat.teams import DiGraphBuilder, GraphFlow\n",+ "from autogen_agentchat.ui import Console\n",+ "from autogen_ext.models.openai import OpenAIChatCompletionClient\n",+ "\n",+ "# Model client\n",+ "client = OpenAIChatCompletionClient(model=\"gpt-4o-mini\")\n",+ "\n",+ "# Create agents for A→B→C→B→E scenario\n",+ "agent_a = AssistantAgent(\"A\", model_client=client, system_message=\"Start the process and provide initial input.\")\n",+ "agent_b = AssistantAgent(\n",+ " \"B\",\n",+ " model_client=client,\n",+ " system_message=\"Process input from A or feedback from C. Say 'CONTINUE' if it's from A or 'STOP' if it's from C.\",\n",+ ")\n",+ "agent_c = AssistantAgent(\"C\", model_client=client, system_message=\"Review B's output and provide feedback.\")\n",+ "agent_e = AssistantAgent(\"E\", model_client=client, system_message=\"Finalize the process.\")\n",+ "\n",+ "# Build the graph with activation groups\n",+ "builder = DiGraphBuilder()\n",+ "builder.add_node(agent_a).add_node(agent_b).add_node(agent_c).add_node(agent_e)\n",+ "\n",+ "# A → B (initial path)\n",+ "builder.add_edge(agent_a, agent_b, activation_group=\"initial\")\n",+ "\n",+ "# B → C\n",+ "builder.add_edge(agent_b, agent_c, condition=\"CONTINUE\")\n",+ "\n",+ "# C → B (loop back - different activation group)\n",+ "builder.add_edge(agent_c, agent_b, activation_group=\"feedback\")\n",+ "\n",+ "# B → E (exit condition)\n",+ "builder.add_edge(agent_b, agent_e, condition=\"STOP\")\n",+ "\n",+ "# Build and create flow\n",+ "graph = builder.build()\n",+ "flow = GraphFlow(participants=[agent_a, agent_b, agent_c], graph=graph)\n",+ "\n",+ "print(\"=== Example 1: A→B→C→B with 'All' Activation ===\")\n",+ "print(\"B will exit when it receives a message from C\")\n",+ "# await Console(flow.run_stream(task=\"Start a review process for a document.\"))"+ ]+ },+ {+ "cell_type": "markdown",+ "id": "5dc08c64",+ "metadata": {},+ "source": [+ "### Example 2: Loop with Multiple Paths - \"Any\" Activation (A→B→(C1,C2)→B)\n",+ "\n",+ "In this more complex scenario, we have A → B → (C1, C2) → B, where:\n",+ "- B fans out to both C1 and C2 in parallel\n",+ "- Both C1 and C2 feed back to B \n",+ "- B uses \"any\" activation, meaning it executes as soon as **either** C1 or C2 completes\n",+ "\n",+ "This is useful for scenarios where you want the fastest response to trigger the next step.\n"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "id": "00f40293",+ "metadata": {},+ "outputs": [],+ "source": [+ "# Create agents for A→B→(C1,C2)→B scenario\n",+ "agent_a2 = AssistantAgent(\"A\", model_client=client, system_message=\"Initiate a task that needs parallel processing.\")\n",+ "agent_b2 = AssistantAgent(\n",+ " \"B\",\n",+ " model_client=client,\n",+ " system_message=\"Coordinate parallel tasks. Say 'PROCESS' to start parallel work or 'DONE' to finish.\",\n",+ ")\n",+ "agent_c1 = AssistantAgent(\"C1\", model_client=client, system_message=\"Handle task type 1. Say 'C1_COMPLETE' when done.\")\n",+ "agent_c2 = AssistantAgent(\"C2\", model_client=client, system_message=\"Handle task type 2. Say 'C2_COMPLETE' when done.\")\n",+ "agent_e = AssistantAgent(\"E\", model_client=client, system_message=\"Finalize the process.\")\n",+ "\n",+ "# Build the graph with \"any\" activation\n",+ "builder2 = DiGraphBuilder()\n",+ "builder2.add_node(agent_a2).add_node(agent_b2).add_node(agent_c1).add_node(agent_c2).add_node(agent_e)\n",+ "\n",+ "# A → B (initial)\n",+ "builder2.add_edge(agent_a2, agent_b2)\n",+ "\n",+ "# B → C1 and B → C2 (parallel fan-out)\n",+ "builder2.add_edge(agent_b2, agent_c1, condition=\"PROCESS\")\n",+ "builder2.add_edge(agent_b2, agent_c2, condition=\"PROCESS\")\n",+ "\n",+ "# B → E (exit condition)\n",+ "builder2.add_edge(agent_b2, agent_e, condition=lambda msg: \"DONE\" in msg.to_model_text())\n",+ "\n",+ "# C1 → B and C2 → B (both in same activation group with \"any\" condition)\n",+ "builder2.add_edge(\n",+ " agent_c1, agent_b2, activation_group=\"loop_back_group\", activation_condition=\"any\", condition=\"C1_COMPLETE\"\n",+ ")\n",+ "\n",+ "builder2.add_edge(\n",+ " agent_c2, agent_b2, activation_group=\"loop_back_group\", activation_condition=\"any\", condition=\"C2_COMPLETE\"\n",+ ")\n",+ "\n",+ "# Build and create flow\n",+ "graph2 = builder2.build()\n",+ "flow2 = GraphFlow(participants=[agent_a2, agent_b2, agent_c1, agent_c2, agent_e], graph=graph2)\n",+ "\n",+ "print(\"=== Example 2: A→B→(C1,C2)→B with 'Any' Activation ===\")\n",+ "print(\"B will execute as soon as EITHER C1 OR C2 completes (whichever finishes first)\")\n",+ "# await Console(flow2.run_stream(task=\"Start a parallel processing task.\"))"+ ]+ },+ {+ "cell_type": "markdown",+ "id": "7c56cd2e",+ "metadata": {},+ "source": [+ "### Example 3: Mixed Activation Groups\n",+ "\n",+ "This example shows how different activation groups can coexist in the same graph. We have a scenario where:\n",+ "- Node D receives inputs from multiple sources with different activation requirements\n",+ "- Some dependencies use \"all\" activation (must wait for all inputs)\n",+ "- Other dependencies use \"any\" activation (proceed on first input)\n",+ "\n",+ "This pattern is useful for complex workflows where different types of dependencies have different urgency levels.\n"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "id": "97f75ba1",+ "metadata": {},+ "outputs": [],+ "source": [+ "# Create agents for mixed activation scenario\n",+ "agent_a3 = AssistantAgent(\"A\", model_client=client, system_message=\"Provide critical input that must be processed.\")\n",+ "agent_b3 = AssistantAgent(\"B\", model_client=client, system_message=\"Provide secondary critical input.\")\n",+ "agent_c3 = AssistantAgent(\"C\", model_client=client, system_message=\"Provide optional quick input.\")\n",+ "agent_d3 = AssistantAgent(\"D\", model_client=client, system_message=\"Process inputs based on different priority levels.\")\n",+ "\n",+ "# Build graph with mixed activation groups\n",+ "builder3 = DiGraphBuilder()\n",+ "builder3.add_node(agent_a3).add_node(agent_b3).add_node(agent_c3).add_node(agent_d3)\n",+ "\n",+ "# Critical inputs that must ALL be present (activation_group=\"critical\", activation_condition=\"all\")\n",+ "builder3.add_edge(agent_a3, agent_d3, activation_group=\"critical\", activation_condition=\"all\")\n",+ "builder3.add_edge(agent_b3, agent_d3, activation_group=\"critical\", activation_condition=\"all\")\n",+ "\n",+ "# Optional input that can trigger execution on its own (activation_group=\"optional\", activation_condition=\"any\")\n",+ "builder3.add_edge(agent_c3, agent_d3, activation_group=\"optional\", activation_condition=\"any\")\n",+ "\n",+ "# Build and create flow\n",+ "graph3 = builder3.build()\n",+ "flow3 = GraphFlow(participants=[agent_a3, agent_b3, agent_c3, agent_d3], graph=graph3)\n",+ "\n",+ "print(\"=== Example 3: Mixed Activation Groups ===\")\n",+ "print(\"D will execute when:\")\n",+ "print(\"- BOTH A AND B complete (critical group with 'all' activation), OR\")\n",+ "print(\"- C completes (optional group with 'any' activation)\")\n",+ "print(\"This allows for both required dependencies and fast-path triggers.\")\n",+ "# await Console(flow3.run_stream(task=\"Process inputs with mixed priority levels.\"))"+ ]+ },+ {+ "cell_type": "markdown",+ "id": "e329fe57",+ "metadata": {},+ "source": [+ "### Key Takeaways for Activation Groups\n",+ "\n",+ "1. **`activation_group`**: Groups edges that point to the same target node, allowing you to define different dependency patterns.\n",+ "\n",+ "2. **`activation_condition`**: \n",+ " - `\"all\"` (default): Target node waits for ALL edges in the group to be satisfied\n",+ " - `\"any\"`: Target node executes as soon as ANY edge in the group is satisfied\n",+ "\n",+ "3. **Use Cases**:\n",+ " - **Cycles with multiple entry points**: Different activation groups prevent conflicts\n",+ " - **Priority-based execution**: Mix \"all\" and \"any\" conditions for different urgency levels \n",+ " - **Parallel processing with early termination**: Use \"any\" to proceed with the fastest result\n",+ "\n",+ "4. **Best Practices**:\n",+ " - Use descriptive group names (`\"critical\"`, `\"optional\"`, `\"feedback\"`, etc.)\n",+ " - Keep activation conditions consistent within the same group\n",+ " - Test your graph logic with different execution paths\n",+ "\n",+ "These patterns enable sophisticated workflow control while maintaining clear, understandable execution semantics."+ ]}],"metadata": {