Add Edge

Add Edge#

edge type#

EvoFabric provides two types of edges: ordinary edges and conditional edges, used to describe the state transition logic between nodes.

edge type#

edge type

Derived class

Function Description

Ordinary edge

EdgeSpec

Fixed path from the source node to a single target node, optionally with state_filter to filter or rewrite the state.

Conditional edge

ConditionEdgeSpec

The router function dynamically determines the next hop target node at runtime, returning one or more target nodes and the state_filter function for each node.

Add Ordinary Edge#

Call the add_edge() method to establish an ordinary edge between two nodes.

The typical use case for this method is to fixedly connect two nodes, commonly used in linear or workflows with less branching logic.

from pydantic import BaseModel
from typing import Annotated

class MyState(BaseModel):
    text: Annotated[str, "overwrite"]
    validated: Annotated[bool, "overwrite"] = False

graph.add_edge(
    source="preprocess",
    target="analyze",
    group="all",
    state_filter=lambda s: s.copy(update={"validated": True})
)

Parameter Description:

  • source : Source node name, must be a node already added to the graph.

  • target : Target node name, must be an existing node.

  • group : The group name to which the edge belongs. Multiple groups can be used to distinguish logical channels or execution paths, with a default value of all.

  • state_filter: Optional state filtering function used to rewrite the State during state passing.

Operating Mechanism:

When the source node completes execution, its output state will flow along this edge to the target node. If state_filter is provided, the state will be processed by this function before reaching the target node.

Add conditional edge#

When the next hop node needs to dynamically determine based on runtime state, you can use add_condition_edge() to add a conditional edge.

The behavior of such edges is determined by the router function, which can flexibly implement multi-path branching logic.

from pydantic import BaseModel
from typing import Annotated

class MyState(BaseModel):
    score: Annotated[float, "overwrite"]

def route_next(state):
    if state.score > 0.8:
        return "success"
    else:
        return "retry"

graph.add_condition_edge(
    source="evaluate",
    router=route_next,
    possible_targets=["success", "retry"],
    group="decision"
)

Parameter Description:

  • source : Source node name.

  • router : routing function, input is the complete State after the current node’s output, returns the next hop node or node list.

    Support the following return formats:

    • str: single target node.

    • List[str]: multiple target nodes.

    • Tuple[str, Callable]: target node + edge-specific state filtering function.

    • List[Tuple[str, Callable]]: multiple (target node, state filter function) pairs.

    Note

    The router function receives the complete state (i.e., the result of merging the input state with the incremental state output by the source node).

  • possible_targets : the set of all target nodes allowed to be routed to, used for validation and optimization.

  • group : the group name the edge belongs to, default to all.

Operating Mechanism:

Conditional edges will call the router function at runtime to determine the target node list based on the state. The system will automatically verify that the returned target nodes are included in possible_targets and uniformly encapsulate them into a list in the format (target node, state filter) for transmission.

Note

Conditional edges are typically used in scenarios requiring branching, retrying, or dynamic routing based on context state, such as diverting to different processing nodes based on the Agent’s output, or determining whether to enter the retry process based on model confidence, etc.

Edge grouping mechanism#

EvoFabric supports setting the group parameter for edges to group state propagation across different channels.

Edges within the same group will be uniformly processed in the target node’s trigger logic, and can be combined with the node’s action_mode and multi_input_merge_strategy to achieve more complex execution control.

Note

When a node’s action_mode is set to all, the self-loop and exit logic added via conditional edges should specify separate groups. Otherwise, the node may never be executed. Because under the all mode, the group containing the self-loop logic can never satisfy the condition that “all predecessor nodes have been executed.”

Contents