> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maadify.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Maadify Browser Agent
> Configure browser tools that agents can use to navigate pages, take actions, and extract data
The **Maadify Browser Agent** lets an agent control a browser as part of a workflow. Use it when a task requires logging in to a web app, navigating pages, clicking controls, filling forms, checking page state, or extracting structured data from a site that does not have a direct API connector.
Browser tools are configured from connectors as a **Custom Browser Flow**. After you configure the browser flow, add the tool to a sub-agent or parent agent workflow. When the workflow runs, Maadify opens a browser session, executes each browser step in order, and returns the step results or extracted data to the agent.
## How the browser agent works
A browser flow has two parts:
* **Input configuration** defines the values a user or workflow provides when the tool runs.
* **Browser steps** define what the browser does with those values.
At runtime, Maadify starts a browser session, applies tool inputs and saved defaults, replaces template variables in URLs or instructions, and runs each step. Chat and Agent activity can show the live browser session while the agent is working. After the run, Maadify can attach a browser session replay and returns step results, extracted records, errors, or cancellation details.
## Create a browser tool
Go to **Connectors** and open the **Maadify Browser Agent** connector.
Add or open a tool named **Custom Browser Flow**. The tool configuration opens with a **Browser Flow Configurations** tab.
Add a description that explains what the browser flow does. This helps other builders understand when an agent should use the tool.
In **Input Configuration**, add the values the browser flow needs, such as customer name, order ID, login email, product list, or search terms.
In **Browser Steps Builder**, add the ordered steps the browser should run.
Save the configuration. Maadify stores the browser steps and updates the tool input and output schemas.
## Define input configuration
Input fields become the schema for the tool. Agents and workflow builders use this schema when they call the browser tool.
You can:
* Click **Add Input Field** to build fields manually.
* Click **Import from JSON** to generate fields from a JSON schema or example.
* Reorder input fields to make the form easier to use.
* Remove fields that the browser flow no longer needs.
Use input fields for values that should change per run. For example, a browser flow that updates inventory might need `sku`, `warehouse`, and `quantity`. A browser flow that searches a portal might need `customer_name` or `order_number`.
## Use variables in steps
Browser steps can insert input values into URLs and instructions.
* Use `{{ variable }}` when the value can be sent to the AI model as part of the instruction, these are variables sent as inputs that are configured via the schema builder.
* Use `%variable%` when the value is sensitive and should be inserted without being sent to the AI model.
When you add a variable from the picker, Maadify only shows fields that are valid for the current step. For normal steps, scalar input fields are available. Inside a looped group, fields from the current array item and parent array items are available.
Use `%variable%` for credentials, tokens, or private values. Use `{{ variable }}` for regular workflow data such as names, IDs, quantities, and search terms.
## Add browser steps
Each browser step has a **Step Type** and step-specific settings. Steps run in order unless a failure rule jumps to another step.
### Go to
Use **goto** to open a URL. The URL can include variables, such as a customer portal URL or a search page with query parameters.
Required field:
* **URL**: the page the browser should open.
### Action
Use **action** to take an action on the page. Write instructions in natural language, such as "click the Sign in button", "type `%password%` into the password field", or "select the first matching order".
Action steps can use cached page observations. If the page structure is stable, the cache helps repeat the action faster. If the page changes often, enable **Ignore Cache** so Maadify evaluates the page again.
Required field:
* **Instructions**: what the browser should do.
### Evaluate
Use **evaluate** to check the page before continuing. For example, evaluate whether a login succeeded, whether a confirmation message appears, or whether a target button is visible.
If the evaluate step returns no matching result, the step fails unless **Ignore Evaluate** is enabled.
Required field:
* **Instructions**: what page condition to check.
### Extract
Use **extract** to return structured data from the current page. Write extraction instructions and define an **Output Schema** so the browser knows what fields to return.
You can create the output schema manually with **Add Field** or generate it with **Import from JSON**. Extract steps can return values such as order numbers, status labels, prices, tracking links, table rows, or confirmation messages.
Required fields:
* **Instructions**: what data to extract.
* **Output Schema**: the fields the extraction should return.
### Group
Use **group** to organize nested steps. Groups are useful when you want to repeat a set of actions for every item in an array.
If the input configuration includes an array field, choose it in **Loop On**. Maadify runs the group steps once for each item in that array. Nested groups can loop over child arrays.
Group steps can contain:
* **goto**
* **action**
* **extract**
* **group**
* **evaluate**
### End
Use **end** to stop the browser flow at a specific point. This is useful when earlier steps have completed the task and later steps should not run.
## Configure advanced step behavior
Open **Advanced Step Configurations** on a step when the site needs timing, retry, cache, or failure handling.
Available settings depend on the step type:
* **Ignore Cache** re-evaluates an action step instead of using saved observations.
* **Skip Evaluate** runs an action directly from the instruction instead of observing matching elements first.
* **Ignore Evaluate** lets an evaluate step continue even when no matching result is found.
* **Execute Iframes** attempts to act on elements inside iframes.
* **Skip Missing Variables** skips the step when a required variable is unavailable.
* **Send Only Extracted Data** returns only extracted records instead of the full step history.
* **Wait Until** controls whether the browser waits for `domcontentloaded`, `load`, or `networkidle`.
* **Retry Count** retries a failing step before the run fails or jumps.
* **Wait For Settled DOM** adds a delay in milliseconds before the step runs.
* **Go To Step On Failure** jumps to another step in the same scope if the step fails.
* **Max Repeat Step On Failure** limits how many times a failure jump can repeat.
Failure jumps stay within the same scope. A top-level step can jump to another top-level step. A step inside a group can jump only to another step in that same group.
## Add the browser tool to an agent
After the browser flow is saved, add the Custom Browser Flow tool to the agent that should use it.
Open the parent agent or sub-agent that should control the browser.
Choose the **Custom Browser Flow** tool from the Maadify Browser Agent connector.
For assistant sub-agents, register the tool so the agent can call it. For execution-focused agents, configure the tool as an executable action.
Use the browser tool schema to map chat context, workflow inputs, or outputs from earlier steps into the tool fields.
Open [https://app.maadify.com/chat](https://app.maadify.com/chat), choose the agent, and send a request that should trigger the browser flow.
## Review a browser run
When an agent runs a browser tool, you can review what happened from chat or **Agent activity**.
You may see:
* A live browser view while the run is active.
* Step results for actions, evaluations, and extractions.
* Extracted records returned by extract steps.
* A browser session replay after the run completes.
* Error details with the step that failed.
* Cancellation details if the run was stopped.
## Best practices
* Keep browser steps small and specific. One step should do one navigation, action, check, or extraction.
* Use **evaluate** before important actions when the page state may vary.
* Use **extract** with a strict output schema when later workflow steps need reliable fields.
* Use groups for repeated work across arrays, such as processing multiple products or orders.
* Use secret variables for credentials and sensitive values.
* Add retry and wait settings for pages with slow loading or dynamic content.
* Test the browser tool in chat before adding it to a production workflow.
## Troubleshooting
* Confirm the tool is a **Custom Browser Flow** from the **Maadify Browser Agent** connector.
* Check that the tool has at least one browser step.
* Verify the agent has access to the tool.
* Use clearer action instructions.
* Enable **Ignore Cache** if the page layout changed.
* Add a **Wait For Settled DOM** delay or choose a slower **Wait Until** option.
* Add an **evaluate** step before the action to confirm the page is ready.
* Check the input configuration field name.
* Confirm the tool input mapping provides that value.
* Enable **Skip Missing Variables** only when the step can be skipped safely.
* Review the extraction instructions.
* Confirm the browser is on the page that contains the target data.
* Update the output schema so the field names match what you need.
* Confirm **Loop On** points to an array input field.
* Check that the tool input includes array items at runtime.
* For nested groups, choose a child array available inside the current group context.