Web Tool Node

Execute client-side browser tools within your flow with output mapping and conditional routing

Overview

The Web Tool Node executes a Web Tool — a client-side JavaScript function that runs in the user’s browser via the Hamsa Voice Agents SDK. Unlike the Tool Node which calls server-side APIs, web tool nodes trigger actions directly in your web application.

For example, when a user says “show me my cart”, the agent can call a web tool that opens the cart drawer on your website — no server round-trip needed. Web tools also let you reuse your existing client-side API integrations rather than rebuilding them as server-side tools, saving development time when the web is your primary channel.

Web tools only work on web calls (via the Voice Agents SDK). They do not function on phone calls — there is no browser to execute them.

Use Cases

• Navigate the UI — “Show me my dashboard” → routes the user to a specific page
• Open UI elements — “I need to upload a document” → opens the upload modal
• Read page state — Agent reads current form values or page context to give relevant answers
• Leverage existing auth — The browser already has the user’s session, so web tools can call authenticated APIs without re-passing credentials to the server
• Trigger client-side flows — “Schedule a demo” → opens the booking widget
• Interact with embedded content — Play a video, center a map on a location, expand a section

Adding a Web Tool Node

1. Open your Flow Agent
2. Click Add Node and select Web Tool Node
3. Select a registered web tool from the tool selector (only WEB_TOOL type tools are shown)
4. Configure output mapping and transitions

Configuration

Processing Message

Configure a message the agent speaks while the web tool executes:

• Static: A fixed message (e.g., "One moment while I look that up...")
• Prompt: An AI-generated message that can reference variables (e.g., "Let me find the {{product_category}} for you...")

Tool Configuration Overrides

Once a web tool is attached, you can override its default configuration for this specific node instance:

• Name — Override the tool name
• Description — Override the tool description
• Parameters — Customize the parameter definitions
• Custom Parameters — Add additional parameters
• Async — Toggle async execution

These overrides only apply to this node — the original web tool definition remains unchanged.

Example Response

Since web tools run client-side and cannot be tested from the server, the Web Tool Node provides an Example Response field. Paste a sample JSON or plain string response that your web tool would return. This allows you to:

• Validate variable extraction paths before deployment
• Test output mapping without executing the tool
• Preview how transitions will evaluate against the response

Custom Response

When enabled, define a custom template for what the agent says after the tool runs, using extracted values from the response.

Output Mapping and Variables

Extract specific values from the web tool’s JSON response and store them as variables:

Web Tool Node: Check_Cart
  Output Mapping:
    cart_total: $.total
    item_count: $.items.length
  ↓ (Equation: {{cart_total}} > 100)
Conversation Node: "Your cart total is {{cart_total}}. Would you like to checkout?"
  ↓ (Equation: {{cart_total}} <= 100)
Conversation Node: "You have {{item_count}} items. Can I help you find anything else?"

In a single prompt agent, the web tool’s response goes directly to the LLM without extraction. In a flow agent, you control exactly which values are extracted and how they’re used.

Transitions

Web Tool Nodes support the following transition types:

• Prompt: Route based on natural language evaluation of the response
• Equation: Route based on extracted values from the response

Web Tool Node vs Tool Node

Aspect	Web Tool Node	Tool Node
Execution	Client-side in the browser	Server-side API call
Works on	Web calls only	All call types
Tool type	WEB_TOOL	FUNCTION / MCP
Server testing	Not supported — use Example Response	Supported
Override options	Name, description, params, async	Full: URL, method, headers, auth, timeout

Related

Web Tools

Full web tools documentation with SDK registration and examples

Tool Node

Server-side tool execution for API calls

Variables

Use extracted tool data in your flow

Transitions

Route based on tool responses