Nodes overview

class Node:
    name: str                    # Unique identifier (alphanumeric + underscore)
    type: NodeType              # The node type (DEFAULT, WEBHOOK, etc.)
    prompt: str = None          # Instructions for the LLM
    global_: bool = False       # Whether node is globally accessible
    global_condition: str = None # Condition for global node activation

from kapso.builder.nodes import DefaultNode

node = DefaultNode(
    name="greeting",
    prompt="Welcome the user warmly"
)

from kapso.builder.nodes import SubagentNode

node = SubagentNode(
    name="assistant",
    prompt="Use available tools to help the user"
)

from kapso.builder.nodes import WebhookNode

node = WebhookNode(
    name="api_call",
    url="https://api.example.com/data",
    http_method="GET"
)

from kapso.builder.nodes import KnowledgeBaseNode

node = KnowledgeBaseNode(
    name="docs",
    key="product_docs",
    knowledge_base_text="Product information..."
)

from kapso.builder.nodes import WhatsAppTemplateNode

node = WhatsAppTemplateNode(
    name="notification",
    template_name="order_update",
    phone_number="{{customer_phone}}"
)

from kapso.builder.nodes import HandoffNode

node = HandoffNode(
    name="human_handoff",
    global_=True,
    global_condition="user requests human agent"
)

from kapso.builder.nodes import WarmEndNode

node = WarmEndNode(
    name="goodbye",
    timeout_minutes=30,
    prompt="Thank you for chatting!"
)

# Global help menu
help_menu = DefaultNode(
    name="help",
    prompt="Show available options",
    global_=True,
    global_condition="user asks for help or says 'menu'"
)

# Global human handoff
handoff = HandoffNode(
    name="escalate",
    global_=True,
    global_condition="user is frustrated or requests human"
)

# ❌ Wrong - User-facing message
node = DefaultNode(
    name="greeting",
    prompt="Hello! How can I help you today?"
)

# ✅ Correct - LLM instruction
node = DefaultNode(
    name="greeting",
    prompt="Greet the user warmly and ask how you can help them"
)

# Use SubagentNode as the primary conversation handler
main = SubagentNode(
    name="main",
    prompt="You are the primary assistant. Use tools as needed."
)
# Add various tools for flexibility
main.add_tool(WebhookTool(...))
main.add_tool(KnowledgeBaseTool(...))

# Global error handler
error_handler = DefaultNode(
    name="error_recovery",
    prompt="Apologize for the error and ask how you can help",
    global_=True,
    global_condition="an error occurred or system malfunction"
)

# Chain nodes for complex workflows
collect_info = DefaultNode(name="collect_info", prompt="Gather user details")
process_data = WebhookNode(name="process", url="...", http_method="POST")
confirm = DefaultNode(name="confirm", prompt="Confirm the results with user")

agent.add_edge("collect_info", "process")
agent.add_edge("process", "confirm")

from kapso.builder import Agent
from kapso.builder.nodes import (
    DefaultNode, SubagentNode, WebhookNode, 
    KnowledgeBaseNode, WhatsAppTemplateNode,
    HandoffNode, WarmEndNode
)
from kapso.builder.agent.constants import START_NODE, END_NODE

# Create agent
agent = Agent(name="customer_service_bot")

# Add special nodes
agent.add_node(START_NODE)
agent.add_node(END_NODE)

# Main conversation handler (recommended approach)
subagent = SubagentNode(
    name="assistant",
    prompt="You are a helpful customer service agent. Use available tools as needed."
)
agent.add_node(subagent)

# API integration node
order_api = WebhookNode(
    name="check_order",
    url="https://api.example.com/orders/{{order_id}}",
    http_method="GET",
    prompt="Extract the order ID from the conversation and check its status"
)
agent.add_node(order_api)

# Knowledge base for FAQs
faq = KnowledgeBaseNode(
    name="faq_search",
    key="support_docs",
    knowledge_base_text="Return Policy: Items can be returned within 30 days...",
    prompt="Search for relevant information to answer the user's question"
)
agent.add_node(faq)

# WhatsApp template for order confirmations
confirmation = WhatsAppTemplateNode(
    name="send_confirmation",
    template_name="order_confirmation",
    phone_number="{{customer_phone}}",
    prompt="Send order confirmation when purchase is complete"
)
agent.add_node(confirmation)

# Global human handoff
handoff = HandoffNode(
    name="human_agent",
    global_=True,
    global_condition="user is frustrated or explicitly requests human assistance"
)
agent.add_node(handoff)

# Conversation end with follow-up window
goodbye = WarmEndNode(
    name="end_chat",
    timeout_minutes=30,
    prompt="Thank the user and let them know they can ask follow-up questions"
)
agent.add_node(goodbye)

# Define conversation flow
agent.add_edge(START_NODE, "assistant")
agent.add_edge("assistant", "check_order", condition="user asks about order status")
agent.add_edge("assistant", "faq_search", condition="user has a general question")
agent.add_edge("assistant", "send_confirmation", condition="order completed successfully")
agent.add_edge("assistant", "end_chat", condition="user says goodbye or issue resolved")

# Edges back to assistant
agent.add_edge("check_order", "assistant")
agent.add_edge("faq_search", "assistant")
agent.add_edge("send_confirmation", "assistant")

# Final edge
agent.add_edge("end_chat", END_NODE)

# Validate the agent
agent.validate()