SubagentNode

from kapso.builder.nodes import SubagentNode
from kapso.builder.nodes.subagent.tools import WebhookTool, KnowledgeBaseTool

node = SubagentNode(
    name="assistant",
    prompt="Help users with available tools",
    global_=False,
    global_condition=None
)

# Add tools
node.add_tool(WebhookTool(name="api", url="https://api.com"))
node.add_tool(KnowledgeBaseTool(name="docs", knowledge_base_text="..."))

SubagentNode(
    name: str,                    # Required: unique identifier
    prompt: str = None,           # Optional: LLM instructions
    global_: bool = False,        # Optional: globally accessible
    global_condition: str = None  # Required if global_=True
)

from kapso.builder.nodes.subagent.tools import WebhookTool

tool = WebhookTool(
    name="order_api",                          # Required: tool identifier
    url="https://api.example.com/orders",      # Required: API endpoint
    http_method="POST",                        # Optional: GET, POST, PUT, PATCH, DELETE
    headers={                                  # Optional: request headers
        "Authorization": "Bearer {{api_key}}",
        "Content-Type": "application/json"
    },
    body={                                     # Optional: request body
        "order_id": "{{order_id}}",
        "action": "status"
    },
    body_schema={                              # Optional: JSON Schema validation
        "type": "object",
        "properties": {
            "order_id": {"type": "string"},
            "action": {"type": "string"}
        },
        "required": ["order_id"]
    },
    jmespath_query="data.status",              # Optional: extract specific data
    mock_response={"status": "shipped"},       # Optional: for testing
    mock_response_enabled=True,                # Optional: enable mock
    description="Check order status"           # Optional but recommended
)

node.add_tool(tool)

from kapso.builder.nodes.subagent.tools import KnowledgeBaseTool

# From text
tool = KnowledgeBaseTool(
    name="policies",
    knowledge_base_text="""
    Return Policy:
    - 30-day returns for unopened items
    - 14-day returns for opened items
    - No returns on sale items
    """,
    description="Company policies and procedures"
)

# From file
tool = KnowledgeBaseTool.from_file(
    name="manual",
    file_path="docs/user_manual.pdf",
    description="Product user manual"
)

node.add_tool(tool)

from kapso.builder.nodes.subagent.tools import McpServerTool, JmespathQuery

tool = McpServerTool(
    name="calculator",
    url="https://mcp.example.com/math",
    transport_kind="sse",  # or "streamable_http"
    jmespath_queries=[
        JmespathQuery(
            tool_name="basic_math",
            jmespath_query="tools[?category=='arithmetic']"
        ),
        JmespathQuery(
            tool_name="advanced_math",
            jmespath_query="tools[?category=='scientific']"
        )
    ],
    description="Mathematical calculations"
)

node.add_tool(tool)

from kapso.builder.nodes.subagent.tools import WhatsappTemplateTool

tool = WhatsappTemplateTool(
    name="order_confirmation",
    template_name="order_confirm_v2",              # Meta-approved template
    phone_number="{{customer_phone}}",             # Recipient
    template_parameters={                          # Template variables
        "1": "{{customer_name}}",
        "2": "{{order_number}}",
        "3": "{{delivery_date}}"
    },
    wait_for_response=True,                        # Wait for user reply
    whatsapp_config_id="prod_config",             # WhatsApp configuration
    whatsapp_template_id="template_123",          # Template ID
    description="Send order confirmation message"
)

node.add_tool(tool)

node.add_tool(tool: SubagentTool) -> None

from kapso.builder.nodes.factory import create_subagent_node

# With tool objects
node = create_subagent_node(
    name="helper",
    prompt="Use tools to help users",
    tools=[
        WebhookTool(name="api", url="https://api.example.com"),
        KnowledgeBaseTool(name="docs", knowledge_base_text="...")
    ]
)

# With dictionaries
node = create_subagent_node(
    name="helper",
    tools_dict=[
        {"type": "webhook", "name": "api", "url": "https://api.example.com"},
        {"type": "knowledge_base", "name": "docs", "knowledge_base_text": "..."}
    ]
)

node = SubagentNode(
    name="assistant",
    prompt="""When users ask about:
    - Orders: Use the 'check_order' tool
    - Weather: Use the 'weather_api' tool
    - Policies: Use the 'company_policies' knowledge base
    """
)

from kapso.builder import Agent
from kapso.builder.nodes import SubagentNode
from kapso.builder.nodes.subagent.tools import (
    WebhookTool, KnowledgeBaseTool, WhatsappTemplateTool
)
from kapso.builder.agent.constants import START_NODE, END_NODE

# Create agent
agent = Agent(name="customer_service")
agent.add_node(START_NODE)
agent.add_node(END_NODE)

# Create SubagentNode with multiple tools
subagent = SubagentNode(
    name="assistant",
    prompt="""Help customers using available tools:
    - Use order_api for order inquiries
    - Use company_docs for policy questions
    - Send confirmations via WhatsApp when needed"""
)

# Add API tool
subagent.add_tool(WebhookTool(
    name="order_api",
    url="https://api.example.com/orders/{{order_id}}",
    http_method="GET",
    headers={"Authorization": "Bearer {{api_key}}"},
    description="Retrieve order information by ID"
))

# Add knowledge base
subagent.add_tool(KnowledgeBaseTool(
    name="company_docs",
    knowledge_base_text="""
    Return Policy: Items can be returned within 30 days.
    Shipping: Free shipping on orders over $50.
    Business Hours: Monday-Friday 9AM-5PM EST.
    """,
    description="Search company policies and information"
))

# Add WhatsApp template
subagent.add_tool(WhatsappTemplateTool(
    name="order_confirmation",
    template_name="order_confirmed",
    phone_number="{{customer_phone}}",
    template_parameters={
        "1": "{{order_id}}",
        "2": "{{delivery_date}}"
    },
    description="Send order confirmation via WhatsApp"
))

agent.add_node(subagent)
agent.add_edge(START_NODE, "assistant")
agent.add_edge("assistant", END_NODE)

agent.validate()

# ✅ Good: Clear, action-oriented names
WebhookTool(name="check_inventory", ...)
WebhookTool(name="create_ticket", ...)

# ❌ Bad: Vague names
WebhookTool(name="api1", ...)
WebhookTool(name="webhook", ...)

# ✅ Good: Specific and helpful
WebhookTool(
    name="weather",
    description="Get current weather conditions for any city"
)

# ❌ Bad: Too vague
WebhookTool(
    name="weather",
    description="Weather tool"
)

# Use mock responses during development
tool = WebhookTool(
    name="api",
    url="https://api.example.com",
    mock_response={"error": "Not found"},
    mock_response_enabled=True  # Toggle for dev/prod
)

# Global help menu available from anywhere
help_menu = SubagentNode(
    name="help_assistant",
    prompt="Show available options and guide users",
    global_=True,
    global_condition="user asks for help, menu, or options"
)