Add custom tools to agents

This guide shows you how to add custom tools to your agents using SubagentNode. We’ll build a lead collection agent as an example.

Overview

Kapso agents can be extended with custom tools:

App integrations - OAuth-based connections to popular apps (Google, Slack, etc.)
Functions - Serverless JavaScript functions for custom logic
Webhook tools - Direct HTTP calls to any API
MCP servers - Model Context Protocol servers for dynamic tools

You can build agents entirely through the web interface or programmatically using the CLI.

What we’re building

We’ll create a Lead Collection Agent that can:

Capture lead information through natural conversation
Send notifications to your Slack channel
Store lead data in Google Sheets for tracking

Example conversation:

User: "I'm interested in learning more about your product"
Agent: "Great! I'd be happy to help. Could you share your name and 
       company?"
User: "I'm Sarah from TechCorp"
Agent: "Thanks Sarah! What's the best email to reach you at?"
User: "sarah@techcorp.com"
Agent: "Perfect! I've recorded your information and our team will 
       reach out soon."

How it works

The agent uses:

App Integrations: Connections to Slack and Google Sheets
Function: Orchestrates both integrations into a single tool
SubagentNode: Handles the conversation and calls the function

Prerequisites

A Kapso project
A Slack workspace
A Google account with Google Sheets

Method 1: Using the Web Interface

This method requires no coding - everything is configured through the Kapso web app.

Step 1: Enable the App integrations addon

Go to Project Settings → Billing
In the Addons section, toggle on App integrations
Click Save

Step 2: Connect app integrations

We’ll need two integrations:

Integration 1: Google Sheets - Add Row

Navigate to Tools → App integrations
Click Configure New Action
Search for “Google Sheets” and select it
Choose the Add Single Row action
Click Connect Account and authorize your Google account
Configure the action:
- Name: “Save Lead to Sheet”
- Drive: Select your Google Drive
- Spreadsheet: Select or create a spreadsheet for leads
- Worksheet Name: Sheet1 (or your preferred sheet) Map the columns to variables:
- Name: {{name}}
- Email: {{email}}
- Company: {{company}}
- Timestamp: {{timestamp}}
- Source: {{source}}
Variables explained: The {{variableName}} syntax creates placeholders that your agent will fill in. When the agent calls this integration with {name: "Sarah", email: "sarah@techcorp.com"}, those values replace the variables.
Click Save
Note the Integration ID (shown at the top of the page)

Integration 2: Slack - Send Message

Click Configure New Action again
Search for “Slack” → Send Message to a Public Channel action
Click Connect Account and authorize your Slack workspace
Configure the action:
- Name: “Notify Sales Team”
- Channel: Select your sales/leads channel
- Message Text:
```
🎉 New Lead!
Name: {{name}}
Company: {{company}}
Email: {{email}}
Source: {{source}}
```
Click Save
Note this Integration ID too

Step 3: Create a function to orchestrate both integrations

This function will handle both saving to Google Sheets and notifying Slack in a single call.

Navigate to Tools → Functions
Click Create Function
Name it capture-lead
Add this code:

async function handler(request, env) {
  // Get lead data from the agent
  const { name, email, company } = await request.json();
  
  // Add timestamp and source
  const leadData = {
    name,
    email,
    company,
    timestamp: new Date().toISOString(),
    source: "Website Chat"
  };
  
  try {
    // Save to Google Sheets
    const sheetsResponse = await fetch(`https://app.kapso.ai/api/v1/integrations/${env.SHEETS_INTEGRATION_ID}/invoke`, {
      method: 'POST',
      headers: {
        'X-API-Key': env.KAPSO_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(leadData)
    });
    
    if (!sheetsResponse.ok) {
      throw new Error('Failed to save to Google Sheets');
    }
    
    // Notify Slack
    const slackResponse = await fetch(`https://app.kapso.ai/api/v1/integrations/${env.SLACK_INTEGRATION_ID}/invoke`, {
      method: 'POST',
      headers: {
        'X-API-Key': env.KAPSO_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: leadData.name,
        company: leadData.company,
        email: leadData.email,
        source: leadData.source
      })
    });
    
    if (!slackResponse.ok) {
      throw new Error('Failed to notify Slack');
    }
    
    return new Response(JSON.stringify({
      success: true,
      message: `Lead ${name} from ${company} has been captured and the team has been notified.`
    }), {
      headers: { 'Content-Type': 'application/json' }
    });
    
  } catch (error) {
    return new Response(JSON.stringify({
      success: false,
      message: `Error capturing lead: ${error.message}`
    }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' }
    });
  }
}

Click Settings → Environment Variables and add:
- SHEETS_INTEGRATION_ID = your Google Sheets integration ID
- SLACK_INTEGRATION_ID = your Slack integration ID
Click Save and Deploy
Note the Function ID (e.g., fn_capture123)

Step 4: Create an agent with SubagentNode

Now we’ll create an agent that uses the function as a single webhook tool.

Navigate to Agents & Flows → Agents
Click Create Agent
Name it “Lead Collector”

In the canvas, add a SubagentNode:

Name: lead_collector
Prompt:

You are a friendly lead collection assistant. Help capture visitor information through natural conversation.

Your capability:
- capture_lead: Saves lead to Google Sheets AND notifies the team via Slack in one call

Workflow:
1. Greet visitors warmly and ask how you can help
2. If they express interest, collect:
   - Name
   - Company
   - Email
   - Their specific needs/interests
3. Use capture_lead tool with the collected information
4. Thank them and set expectations for follow-up

Keep responses conversational and friendly.
Always get explicit consent before collecting information.
Only call capture_lead once you have name, email, and company.

Step 5: Add webhook tool to the SubagentNode

Click on the SubagentNode to edit it
In the Tools section, click Add Tool

Select Webhook Tool and configure:

Name: capture_lead
URL: https://app.kapso.ai/api/v1/functions/YOUR_FUNCTION_ID/invoke (Replace with your function ID from Step 3)
Method: POST
Headers:

{
  "X-API-Key": "#{KAPSO_API_KEY}"
}

Body Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Lead's full name"
    },
    "email": {
      "type": "string",
      "description": "Lead's email address"
    },
    "company": {
      "type": "string",
      "description": "Lead's company name"
    }
  },
  "required": ["name", "email", "company"]
}

Description: “Capture lead by saving to Google Sheets and notifying Slack”

Step 6: Connect nodes and test

Connect the nodes: Start → lead_collector → End
Click Save
Click Test to try your agent
Example conversations to test:
- “I’m interested in your product”
- “Can you tell me more about your services?”
- “I’d like to schedule a demo”

Step 7: Deploy and integrate

Once testing is complete:

Click Deploy in the agent editor
Integrate with your website chat widget or messaging platform
Your lead collection agent is now live!

Method 2: Using CLI and Builder SDK

This method gives you full programmatic control over your agent.

Step 1: Set up your environment

# Install Kapso CLI
pip install kapso

# Authenticate
kapso login

# Initialize a new project
kapso init lead-collector
cd lead-collector

Step 2: Enable addon and connect app integrations

Even when using the CLI, app integrations must be configured through the web interface:

Go to app.kapso.ai → Project Settings → Billing
Enable App integrations addon
Navigate to Tools → App integrations
Configure Google Sheets and Slack integrations as described in Method 1
Note both Integration IDs

Step 3: Create and deploy the function

Create functions/capture-lead.js:

async function handler(request, env) {
  const { name, email, company } = await request.json();
  
  const leadData = {
    name,
    email,
    company,
    timestamp: new Date().toISOString(),
    source: "Website Chat"
  };
  
  try {
    // Save to Google Sheets
    const sheetsResponse = await fetch(`https://app.kapso.ai/api/v1/integrations/${env.SHEETS_INTEGRATION_ID}/invoke`, {
      method: 'POST',
      headers: {
        'X-API-Key': env.KAPSO_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(leadData)
    });
    
    if (!sheetsResponse.ok) {
      throw new Error('Failed to save to Google Sheets');
    }
    
    // Notify Slack
    const slackResponse = await fetch(`https://app.kapso.ai/api/v1/integrations/${env.SLACK_INTEGRATION_ID}/invoke`, {
      method: 'POST',
      headers: {
        'X-API-Key': env.KAPSO_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: leadData.name,
        company: leadData.company,
        email: leadData.email,
        source: leadData.source
      })
    });
    
    if (!slackResponse.ok) {
      throw new Error('Failed to notify Slack');
    }
    
    return new Response(JSON.stringify({
      success: true,
      message: `Lead ${name} from ${company} has been captured and the team has been notified.`
    }), {
      headers: { 'Content-Type': 'application/json' }
    });
    
  } catch (error) {
    return new Response(JSON.stringify({
      success: false,
      message: `Error capturing lead: ${error.message}`
    }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' }
    });
  }
}

Deploy it:

# Deploy with environment variables
kapso functions push functions/capture-lead.js \
  --env SHEETS_INTEGRATION_ID=YOUR_SHEETS_ID \
  --env SLACK_INTEGRATION_ID=YOUR_SLACK_ID

# Note the Function ID from the output

Step 4: Build the agent

Create agent.py:

from kapso.builder import Agent
from kapso.builder.nodes import SubagentNode
from kapso.builder.nodes.subagent import WebhookTool
from kapso.builder.agent.constants import START_NODE, END_NODE

# Replace with your function ID from Step 3
CAPTURE_LEAD_FUNCTION_ID = "fn_capture123"

# Create the agent
agent = Agent(
    name="lead_collector",
    system_prompt="You are a friendly lead collection assistant"
)

# Create SubagentNode
lead_collector = SubagentNode(
    name="lead_collector",
    prompt="""You are a friendly lead collection assistant. Help capture visitor information through natural conversation.
    
    Your capability:
    - capture_lead: Saves lead to Google Sheets AND notifies the team via Slack in one call
    
    Workflow:
    1. Greet visitors warmly and ask how you can help
    2. If they express interest, collect:
       - Name
       - Company
       - Email
       - Their specific needs/interests
    3. Use capture_lead tool with the collected information
    4. Thank them and set expectations for follow-up
    
    Keep responses conversational and friendly.
    Always get explicit consent before collecting information.
    Only call capture_lead once you have name, email, and company."""
)

# Add webhook tool for capturing leads
lead_collector.add_tool(WebhookTool(
    name="capture_lead",
    url=f"https://app.kapso.ai/api/v1/functions/{CAPTURE_LEAD_FUNCTION_ID}/invoke",
    http_method="POST",
    description="Capture lead by saving to Google Sheets and notifying Slack",
    headers={"X-API-Key": "#{KAPSO_API_KEY}"},
    body_schema={
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "Lead's full name"
            },
            "email": {
                "type": "string",
                "description": "Lead's email address"
            },
            "company": {
                "type": "string",
                "description": "Lead's company name"
            }
        },
        "required": ["name", "email", "company"]
    }
))

# Build the graph
agent.add_node(START_NODE)
agent.add_node(lead_collector)
agent.add_node(END_NODE)

agent.add_edge(START_NODE, "lead_collector")
agent.add_edge("lead_collector", END_NODE)

# Validate the agent
agent.validate()

Step 5: Test locally

# Test in cloud with visual debugger
kapso run --cloud

Step 6: Deploy to production

kapso deploy

MCP Server Configuration

For flows, use FlowAgentMcpServer to add MCP servers (HTTP streamable transport only):

from kapso.builder.flows.nodes import AgentNode
from kapso.builder.flows.nodes.agent import FlowAgentMcpServer

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

# Create agent with MCP server
node = AgentNode(
    id="support_agent",
    system_prompt="Help users with documentation questions using available tools.",
    provider_model_name="claude-3-5-sonnet-20241022",
    mcp_servers=[mcp_server]
)

Key Takeaways

This example demonstrates how functions can orchestrate multiple app integrations:

Single tool for the agent: Instead of giving the agent two separate tools, we created one function that handles both operations
Error handling: The function can handle failures gracefully and provide meaningful error messages
Data transformation: The function adds timestamp and source information automatically
Simplified agent logic: The agent only needs to understand one tool instead of coordinating multiple calls

This pattern is especially useful when:

You need to perform multiple related actions together
You want to add business logic between API calls
You need to transform or enrich data before sending to integrations
You want to provide a simpler interface for your agents

Getting Started

How to

Platform

Building flows

Functions

Build agents

Test agents

Additional resources

Overview

What we’re building

How it works

Prerequisites

Method 1: Using the Web Interface

Step 1: Enable the App integrations addon

Step 2: Connect app integrations

Integration 1: Google Sheets - Add Row

Integration 2: Slack - Send Message

Step 3: Create a function to orchestrate both integrations

Step 4: Create an agent with SubagentNode

Step 5: Add webhook tool to the SubagentNode

Step 6: Connect nodes and test

Step 7: Deploy and integrate

Method 2: Using CLI and Builder SDK

Step 1: Set up your environment

Step 2: Enable addon and connect app integrations

Step 3: Create and deploy the function

Step 4: Build the agent

Step 5: Test locally

Step 6: Deploy to production

MCP Server Configuration

Key Takeaways

Getting Started

How to

Platform

Building flows

Functions

Build agents

Test agents

Additional resources

​Overview

​What we’re building

​How it works

​Prerequisites

​Method 1: Using the Web Interface

​Step 1: Enable the App integrations addon

​Step 2: Connect app integrations

​Integration 1: Google Sheets - Add Row

​Integration 2: Slack - Send Message

​Step 3: Create a function to orchestrate both integrations

​Step 4: Create an agent with SubagentNode

​Step 5: Add webhook tool to the SubagentNode

​Step 6: Connect nodes and test

​Step 7: Deploy and integrate

​Method 2: Using CLI and Builder SDK

​Step 1: Set up your environment

​Step 2: Enable addon and connect app integrations

​Step 3: Create and deploy the function

​Step 4: Build the agent

​Step 5: Test locally

​Step 6: Deploy to production

​MCP Server Configuration

​Key Takeaways

Overview

What we’re building

How it works

Prerequisites

Method 1: Using the Web Interface

Step 1: Enable the App integrations addon

Step 2: Connect app integrations

Integration 1: Google Sheets - Add Row

Integration 2: Slack - Send Message

Step 3: Create a function to orchestrate both integrations

Step 4: Create an agent with SubagentNode

Step 5: Add webhook tool to the SubagentNode

Step 6: Connect nodes and test

Step 7: Deploy and integrate

Method 2: Using CLI and Builder SDK

Step 1: Set up your environment

Step 2: Enable addon and connect app integrations

Step 3: Create and deploy the function

Step 4: Build the agent

Step 5: Test locally

Step 6: Deploy to production

MCP Server Configuration

Key Takeaways