Skip to main content
Embedded AI agent that can use tools, access data, and have multi-turn conversations with users.

​
Configuration

  • id: Unique node identifier
  • system_prompt: Instructions for the agent’s behavior
  • provider_model_name: AI model to use
  • temperature: Model creativity, 0.0-1.0 (default: 0.0)
  • max_iterations: Maximum tool calls/responses (default: 80)
  • max_tokens: Maximum tokens per response (default: 8192)
  • reasoning_effort: For o1 models - low, medium, high (optional)
  • webhooks: Custom API tools (optional)
  • mcp_servers: MCP server tools (optional, HTTP streamable only)

​
Built-in tools

Send a message to the user without waiting for a response.Parameters:
  • message (string, required): The text message to send
Usage: Send progress updates, confirmations, or notifications
Send media files to the user via WhatsApp.Parameters:
  • media_url (string, required): URL of the media file
  • media_type (string, required): “image”, “video”, “audio”, or “document”
  • caption (string, optional): Caption for the media
Usage: Share images, documents, or other media content
Access flow execution context and variables.Parameters: NoneReturns: Flow variables, execution context, and metadataUsage: Access stored data and flow state information
Get WhatsApp conversation details.Parameters: NoneReturns: Phone number, conversation ID, and contact informationUsage: Access user contact details for personalization
Store data for use in later flow steps.Parameters:
  • key (string, required): Variable name
  • value (any, required): Value to store
Usage: Save user data, API responses, or calculated values
Retrieve previously stored data.Parameters:
  • key (string, required): Variable name to retrieve
Usage: Access data saved in earlier steps
Get the current date and time.Parameters: NoneReturns: Current timestamp in ISO formatUsage: Time-based logic and timestamp generation
Complete the agent’s task and continue the flow.Parameters: NoneUsage: Signal task completion and advance to next step
Transfer the conversation to a human agent.Parameters:
  • reason (string, optional): Reason for handoff
Usage: Escalate complex issues to human support
Custom tools for external API integration.Parameters: Defined by webhook configurationUsage: Call external APIs, fetch data, trigger actions

​
Examples

Customer support agent 
from kapso.builder.flows.nodes import AgentNode

node = AgentNode(
    id="support_agent",
    system_prompt="You are a helpful customer support agent. Help resolve user issues and answer questions about orders, billing, and technical problems.",
    provider_model_name="claude-3-5-sonnet-20241022"
)
Agent with webhook tools 
from kapso.builder.flows.nodes.agent import FlowAgentWebhook

# Define API tool
check_order = FlowAgentWebhook(
    name="check_order_status",
    url="https://api.example.com/orders/{order_id}",
    description="Check the status of a customer order",
    http_method="GET",
    headers={"Authorization": "Bearer {{api_token}}"}
)

node = AgentNode(
    id="order_agent", 
    system_prompt="Help customers check their order status. Use the check_order_status tool when they provide an order ID.",
    provider_model_name="gpt-4o",
    webhooks=[check_order]
)
When the webhook performs a POST, describe the expected payload with body_schema. The LLM fills that structure automatically; only use body for fixed values or when you already have the exact JSON stored in variables.
Agent with MCP server 
from kapso.builder.flows.nodes.agent import FlowAgentMcpServer

# Define MCP server (HTTP streamable transport)
context_server = FlowAgentMcpServer(
    name="Documentation Server",
    url="https://mcp.context7.ai/v1",
    description="Access to documentation and knowledge bases",
    headers={"Authorization": "Bearer token123"}
)

node = AgentNode(
    id="doc_agent",
    system_prompt="Help users with documentation questions using the available tools.",
    provider_model_name="claude-3-5-sonnet-20241022",
    mcp_servers=[context_server]
)
High-reasoning agent 
node = AgentNode(
    id="complex_support",
    system_prompt="You are an expert technical support agent. Analyze complex problems step by step.",
    provider_model_name="o1-preview",
    reasoning_effort="high",
    temperature=0.1,
    max_iterations=50
)

​
How it works

  1. Starts conversation: Uses system prompt and conversation history
  2. Tool access: Can call built-in tools and custom webhooks
  3. Multi-turn: Continues until calls complete_task or needs user input
  4. Message injection: New user messages are automatically injected during conversation
  5. Flow control: Returns next edge when task completed, wait when needs input

​
Usage patterns

Support flow Data processing
⌘I