> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/agents/tools/web-tools) — a client-side JavaScript function that runs in the user's browser via the Hamsa Voice Agents SDK. Unlike the [Tool Node](./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.

<Warning>
  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.
</Warning>

## 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:

```yaml theme={null}
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?"
```

<Info>
  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.
</Info>

## 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

<CardGroup cols={2}>
  <Card title="Web Tools" href="/agents/tools/web-tools">
    Full web tools documentation with SDK registration and examples
  </Card>

  <Card title="Tool Node" href="./tool-node">
    Server-side tool execution for API calls
  </Card>

  <Card title="Variables" href="/agents/variables/introduction">
    Use extracted tool data in your flow
  </Card>

  <Card title="Transitions" href="../transitions">
    Route based on tool responses
  </Card>
</CardGroup>