Skip to main content
Edges connect nodes in your flow, defining the execution path from one step to another. Each edge has a source node, target node, and label.

Basic usage

# Add edge with default "next" label
flow.add_edge("send_greeting", "wait_response")

# Add edge with custom label
flow.add_edge("decide_routing", "support_agent", "support")

Edge labels

  • Default label: “next” - used by most nodes
  • Custom labels: Required for decide nodes to match condition labels
  • Unique labels: Each outgoing edge from a node must have a unique label

Node-specific edges

Most nodes (send text, function, agent, handoff)
flow.add_edge("send_text", "next_step", "next")
Wait nodes
# Default progression
flow.add_edge("wait_input", "process_response", "next")

# After user response
flow.add_edge("wait_input", "process_response", "response")
Decide nodes
# Edge labels must match condition labels exactly
decide = DecideNode(
    id="route_customer",
    conditions=[
        Condition(label="billing", description="Billing questions"),
        Condition(label="support", description="Technical support")
    ]
)

flow.add_edge("route_customer", "billing_agent", "billing")
flow.add_edge("route_customer", "support_agent", "support")

Examples

Linear flow
flow = (Flow(name="Simple Flow")
    .add_node(StartNode(id="start"))
    .add_node(SendTextNode(id="greeting", message="Hello!"))
    .add_node(SendTextNode(id="goodbye", message="Goodbye!"))
    .add_edge("start", "greeting")
    .add_edge("greeting", "goodbye")
)
Branching flow
# Decision routing
decision = DecideNode(
    id="check_type",
    conditions=[
        Condition(label="question", description="User has a question"),
        Condition(label="complaint", description="User has a complaint")
    ]
)

# Responses
faq = SendTextNode(id="faq_response", message="Here are our FAQs...")
escalate = HandoffNode(id="escalate")

# Connect
flow.add_edge("check_type", "faq_response", "question")
flow.add_edge("check_type", "escalate", "complaint")
Complex routing
# Multi-step with conditions
flow = (Flow(name="Customer Service")
    .add_node(StartNode(id="start"))
    .add_node(SendTextNode(id="welcome", message="How can I help?"))
    .add_node(WaitForResponseNode(id="get_request"))
    .add_node(DecideNode(
        id="classify_request",
        conditions=[
            Condition(label="simple", description="Simple question"),
            Condition(label="complex", description="Complex issue")
        ]
    ))
    .add_node(SendTextNode(id="quick_help", message="Here's the answer..."))
    .add_node(AgentNode(
        id="detailed_help",
        system_prompt="Help with complex issues",
        provider_model_name="claude-sonnet-4-20250514"
    ))
    
    # Linear progression
    .add_edge("start", "welcome")
    .add_edge("welcome", "get_request")
    .add_edge("get_request", "classify_request", "response")
    
    # Conditional routing
    .add_edge("classify_request", "quick_help", "simple")
    .add_edge("classify_request", "detailed_help", "complex")
)

Validation rules

  • Source and target node identifiers must exist in the flow definition
  • Exactly one Start node must be present and have at least one outgoing edge
  • Node identifiers must be unique across the flow
  • Flow must include at least one node
  • Decide node edge labels must match condition labels exactly (otherwise execution cannot route)
I