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

> Run a web tool from your flow: the step asks the caller's web page or app to do something, waits for its reply, and routes on success or failure.

A Web tool step runs one of your [web tools](https://docs.tryhamsa.com/agents/tools/web-tools.md): it asks the web page or app the caller is talking from to do something, such as fill in a form, open a page or read what's in the cart, and waits for the page's reply. The page does the work; the step sends the request, saves values from the reply, and moves on through **On Success** or **On Failure**.

## Before you start

* Create the web tool in **APIs & MCPs**. See [Web tools](https://docs.tryhamsa.com/agents/tools/web-tools.md).
* Your web page or app must connect to the agent with the Hamsa web SDK and answer the tool by its name. See [Embed on your website](https://docs.tryhamsa.com/agents/publishing/embed.md).

Web tool steps work on calls from your website or app. On a phone call there's no web page to answer, so the step takes **On Failure**.

## Add a Web tool step

**1. Add the step**

On the canvas, click **Add node** and choose **Web tool** ("Execute web-based tools").

**2. Pick the web tool**

On the step's card, click **Select a web tool**. In **Choose a web tool** ("The web tool this step runs."), pick one. If you have none, the list shows "No web tools yet".

![The Choose a web tool dialog listing three web tools: read\_cart, open\_order\_page and fill\_return\_form](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/web-tool-picker-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=6723c185d9a5edf81c75d7083a431de6)

**3. Set its parameters**

Open **Tool configuration** and decide where each parameter's value comes from.

**4. Save values from the reply**

Paste an **Example response**, then add a **Tool response variable** for each value you need.

**5. Connect both outcomes**

Connect **On Success** and **On Failure** to their next steps.

## Fields and sections

| Field or section | What it does | Default |
| - | - | - |
| **Processing message** | What the agent says before it sends the request. **Static** speaks your text; **Prompt** lets the agent write it. Leave it empty to say nothing. | **Static**, empty |
| **Example response** | Paste a reply your web tool returns, as JSON or plain text, then click **Save example response**. It "helps validate extraction paths without executing the tool." **Clear example** removes it. | None |
| **Tool configuration** | "Configure parameters for this web tool instance": **Tool display** (**Tool name**, **Tool description**) and **Parameters**, each filled by **AI extraction** or set with **Override** to a fixed value or `{{variable}}`, as on a [Tool step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md#tool-configuration). | The web tool's own settings |
| **Variables** | **Tool response variable** to save a value from the reply, or **Local variable**. | None |

![A Web tool step on the canvas with the read\_cart web tool, and its panel open: Processing message, Transitions, Example response, Tool configuration, Variables and Global](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/web-tool-step-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=2b4618589cc1c9b7c39fa4b4b81d630e)

Parameters filled by **AI extraction** work only when the call reaches the step through a **Prompt** transition. From a Router, a Tool step, a **DTMF input** or **Auto** transition, give each one a value, fixed or `{{variable}}`; the panel marks required ones **Manual value required**.

### Paths for reply values

A web tool's reply is used as it is. Write the **JSON path** with the reply's own keys: for a reply `{"cart": {"total": 120}}`, the path `cart.total` saves `120`.

## Transitions

| Transition | Taken when |
| - | - |
| **On Success** | The page replied with valid JSON within 15 seconds. |
| **On Failure** | The page replied with an error or with text that isn't valid JSON, didn't reply within 15 seconds, or there was no page connected to the call. |

Both are created with the step and can't be removed.

You can also add **Skip if** to this step: when its conditions already hold as the call arrives, the call goes straight to its target and the step doesn't run. See [Skip if](https://docs.tryhamsa.com/agents/flow/transitions.md#skip-if).

## How it works on a call

1. The step's local variables are set.
2. The processing message plays to the end, if there is one.
3. The request goes to the caller's page with the tool name and parameters. The step waits up to 15 seconds for the reply.
4. On a JSON reply, your response variables are saved and the call takes **On Success**. Otherwise it takes **On Failure**.

The agent doesn't speak the reply. To tell the caller what happened, connect the step to a [Conversation step](https://docs.tryhamsa.com/agents/flow/steps/conversation.md) that uses the saved values.

## Related

> [card] [Web tools](https://docs.tryhamsa.com/agents/tools/web-tools.md)
>
> Create the tools your web page answers.

> [card] [Embed on your website](https://docs.tryhamsa.com/agents/publishing/embed.md)
>
> Connect your page to the agent.

> [card] [Tool step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md)
>
> Call an API from your servers instead.

> [card] [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md)
>
> How the call moves between steps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.