browser_task

Execute a browser automation task in a real Chrome browser running in a WebRun cloud environment (docs.webrun.ai). Creates a session, runs the task, and auto-terminates. Best for simple one-off tasks that no saved workflow covers. May navigate, fill forms, and submit data on third-party websites as the task requires. Do NOT use this to run or test a saved workflow — use trigger_workflow instead: only a workflow run carries the workflow's own rules, tracking and memory, so a session run will behave differently. If the user says "run it", "run it once", "test it" or "try it" about a workflow, that means trigger_workflow, not this tool.

destructive

Argument	Type	Description
files	array	Optional file IDs to attach: ids returned by POST /files/upload, or any file already in one of the user's environment catalogs (GET /environments/:id/files). Max 5 files.
model	string	Optional model name or profile key (from global config). Falls back to the configured default.
proxy	object	Proxy configuration. WebRun-managed: { source: "WebRun", country: "GB" }. Custom: { source: "custom", type: "http"\|"socks", host, port, username?, password? }. Omit for no proxy. Social/messaging automation (WhatsApp, Telegram, Instagram, Facebook, X, LinkedIn, TikTok): prefer country = the country the user is in right now — recommend it and confirm the country with them first; a mismatch is the usual cause of refused logins and sessions that log out repeatedly.
debugC	boolean	Enable debug mode on the instance (default: false)
prompt*	string	Task description in natural language
secrets	array	Domain-matched secrets [{match, fields}] passed to instance (not stored)
webhook	object	Webhook configuration for task completion notification
policyId	string	Policy ID to apply automation guardrails (domain restrictions, capability controls, LLM role). Optional.
timezone	string	IANA timezone name for the session, e.g. "America/New_York", "Europe/London", "Asia/Tokyo". Date/time-sensitive instructions (e.g. "tomorrow morning", "today", "in 2 hours") are interpreted in this timezone. When omitted, follows the WebRun proxy country if one is set (e.g. country "de" → Europe/Berlin); otherwise the browser default.
outputType	string	Response format (default: text)
maxDuration	number	Max duration in minutes (default: 20, max: 60)
startingUrl	string	Optional starting URL
outputSchema	object	JSON Schema for structured output (required if outputType is structured_json)
environmentId	string	Environment ID for persistent profile session. Use list_environments to find available IDs. Without this, a disposable instance is used.
reach_out_mode	string	Controls proactive chat-platform messages (Telegram/WhatsApp/Slack/Discord/Teams) to bot users on the same environment. Default: "off" — no messages are sent unless this is set explicitly. "guardrail_only" forwards guardrail prompts (CAPTCHA/2FA/verification) to chat when the API caller is offline. "full" also forwards the task result on completion. Each bot user additionally filters by their own reachOutMode preference.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "files": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional file IDs to attach: ids returned by POST /files/upload, or any file already in one of the user's environment catalogs (GET /environments/:id/files). Max 5 files."
    },
    "model": {
      "type": "string",
      "description": "Optional model name or profile key (from global config). Falls back to the configured default."
    },
    "proxy": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "description": "Custom proxy host"
        },
        "port": {
          "type": "number",
          "description": "Custom proxy port"
        },
        "type": {
          "enum": [
            "http",
            "socks"
          ],
          "type": "string",
          "description": "Custom proxy type"
        },
        "level": {
          "enum": [
            "system",
            "chrome"
          ],
          "type": "string",
          "description": "Proxy level. \"chrome\" (default) applies proxy via browser extension (instant, no swap). \"system\" launches Chrome with --proxy-server flag (requires instance swap)."
        },
        "source": {
          "enum": [
            "WebRun",
            "custom"
          ],
          "type": "string",
          "description": "Proxy provider"
        },
        "country": {
          "type": "string",
          "description": "ISO country code for WebRun proxy (e.g. \"GB\", \"US\") or \"random\" for a random country with good connectivity"
        },
        "password": {
          "type": "string",
          "description": "Custom proxy password (optional)"
        },
        "username": {
          "type": "string",
          "description": "Custom proxy username (optional)"
        }
      },
      "description": "Proxy configuration. WebRun-managed: { source: \"WebRun\", country: \"GB\" }. Custom: { source: \"custom\", type: \"http\"|\"socks\", host, port, username?, password? }. Omit for no proxy. Social/messaging automation (WhatsApp, Telegram, Instagram, Facebook, X, LinkedIn, TikTok): prefer country = the country the user is in right now — recommend it and confirm the country with them first; a mismatch is the usual cause of refused logins and sessions that log out repeatedly."
    },
    "debugC": {
      "type": "boolean",
      "description": "Enable debug mode on the instance (default: false)"
    },
    "prompt": {
      "type": "string",
      "description": "Task description in natural language"
    },
    "secrets": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Domain-matched secrets [{match, fields}] passed to instance (not stored)"
    },
    "webhook": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "HTTPS URL to receive webhook"
        },
        "auth": {
          "type": "string",
          "description": "Authorization header value"
        },
        "name": {
          "type": "string",
          "description": "Webhook identifier"
        },
        "submittedData": {
          "enum": [
            "full_response",
            "structured_output",
            "just_ping"
          ],
          "type": "string",
          "description": "Payload type"
        }
      },
      "description": "Webhook configuration for task completion notification"
    },
    "policyId": {
      "type": "string",
      "description": "Policy ID to apply automation guardrails (domain restrictions, capability controls, LLM role). Optional."
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone name for the session, e.g. \"America/New_York\", \"Europe/London\", \"Asia/Tokyo\". Date/time-sensitive instructions (e.g. \"tomorrow morning\", \"today\", \"in 2 hours\") are interpreted in this timezone. When omitted, follows the WebRun proxy country if one is set (e.g. country \"de\" → Europe/Berlin); otherwise the browser default."
    },
    "outputType": {
      "enum": [
        "text",
        "structured_json",
        "structured_csv"
      ],
      "type": "string",
      "description": "Response format (default: text)"
    },
    "maxDuration": {
      "type": "number",
      "description": "Max duration in minutes (default: 20, max: 60)"
    },
    "startingUrl": {
      "type": "string",
      "description": "Optional starting URL"
    },
    "outputSchema": {
      "type": "object",
      "description": "JSON Schema for structured output (required if outputType is structured_json)"
    },
    "environmentId": {
      "type": "string",
      "description": "Environment ID for persistent profile session. Use list_environments to find available IDs. Without this, a disposable instance is used."
    },
    "reach_out_mode": {
      "enum": [
        "off",
        "guardrail_only",
        "full"
      ],
      "type": "string",
      "description": "Controls proactive chat-platform messages (Telegram/WhatsApp/Slack/Discord/Teams) to bot users on the same environment. Default: \"off\" — no messages are sent unless this is set explicitly. \"guardrail_only\" forwards guardrail prompts (CAPTCHA/2FA/verification) to chat when the API caller is offline. \"full\" also forwards the task result on completion. Each bot user additionally filters by their own reachOutMode preference."
    }
  }
}

create_agent

Create a scheduled agent — a recurring or one-time automation that runs on a timer in a real Chrome browser. Two modes. WORKFLOW MODE: pass workflowId plus a schedule — the platform copies everything else (prompt, starting URL, output contract, model, proxy, policy, files) from the workflow and bakes your variables into the prompt; results and memory stay centralised on the workflow. STANDALONE MODE: omit workflowId and provide name, prompt (a Goal / Ground rules / Stages / Output browsing runbook — see the prompt field description), and a schedule; the connection's environment is used automatically. Ask the user only what it should do and when it should run, in plain language — pick sensible defaults for everything else and state them; never ask about environments or technical settings. Results are delivered to your connected chat and appear in session history.

Argument	Type	Description
name	string	Agent name. Required standalone; defaults to the workflow title in workflow mode.
proxy	object	STANDALONE MODE (workflow mode inherits the workflow proxy instead): Proxy for runs. {source:"WebRun", country?} or {source:"custom", type:"http"\|"socks", host, port, username?, password?}. Custom passwords are encrypted at rest and never returned. Social/messaging workflows (WhatsApp, Telegram, Instagram, Facebook, X, LinkedIn, TikTok): set country to the country the user is in right now — recommend it and confirm the country with them first; a mismatch is the usual cause of refused logins and sessions that log out repeatedly, and a scheduled workflow re-hits it every run, so keep the country stable once set.
memory	string	STANDALONE MODE: the agent's private notebook, shown to it every run and updated automatically after each run. Seed ONLY durable facts the next run must know (target descriptions, preferences, known state) — one short line each. Task steps belong in prompt, not here. Usually best left empty.

create_session

Create a persistent session in a real Chrome browser running in a WebRun cloud environment (docs.webrun.ai), for multi-step interactive work. Returns a sessionId for subsequent commands. With an initial task the browser may act on third-party websites immediately. Do NOT use this to run or test a saved workflow — use trigger_workflow instead: only a workflow run carries the workflow's own rules, tracking and memory, so a session run will behave differently.

destructive

Argument	Type	Description
mode	string	Session mode (default: default)
task	object	Initial task configuration
model	string	Optional model name or profile key (from global config). Falls back to the configured default.
proxy	object	Proxy configuration. WebRun-managed: { source: "WebRun", country: "GB" }. Custom: { source: "custom", type: "http"\|"socks", host, port, username?, password? }. Omit for no proxy. Social/messaging automation (WhatsApp, Telegram, Instagram, Facebook, X, LinkedIn, TikTok): prefer country = the country the user is in right now — recommend it and confirm the country with them first; a mismatch is the usual cause of refused logins and sessions that log out repeatedly.
debugC	boolean	Enable debug mode on the instance (default: false)
policyId	string	Policy ID to apply automation guardrails (domain restrictions, capability controls, LLM role). Optional.

create_workflow

Create a new saved workflow. READINESS BAR: if you could not execute the prompt yourself as a human in a browser — which site, which records, which fields, delivered where, matched to each recipient how — it is not ready; first collect the missing business facts from the user (see the TASK INTERVIEW in the server instructions), then create. Requires title and promptTemplate — write the prompt as a browsing runbook following the Goal / Ground rules / Stages / Output contract in the promptTemplate field description. For tasks that must handle each new item exactly once (new messages, forward once, skip seen), memoryContract is REQUIRED — three plain-English fields addressed to the agent: groundRules, memoryInstruction and itemIdentity (see the field descriptions); the platform wires the tracking itself — never write memory or tracking steps into the prompt. Created in the connection's environment automatically — omit environmentId and never ask the user to choose one. Write the user's concrete values (names, URLs, numbers) directly into the prompt; use {{variables}} ONLY when the user explicitly wants a reusable template with per-run inputs. Everything else is optional and defaults sensibly — do not quiz the user about settings. A supplied schedule is stored as a setting only — the workflow does not run on a timer until deployed via create_agent. To run or TEST the workflow, use trigger_workflow ONLY — never browser_task or create_session.

Argument	Type	Description
flow	object	Dashboard flow diagram: { trigger: {kind, phrase}, steps: [{ primary: {label, domain}, verb }] }.
model	string	Model profile key. Omit for the account default.
proxy	object	Proxy for runs. {source:"WebRun", country?} or {source:"custom", type:"http"\|"socks", host, port, username?, password?}. Custom passwords are encrypted at rest and never returned. Social/messaging workflows (WhatsApp, Telegram, Instagram, Facebook, X, LinkedIn, TikTok): set country to the country the user is in right now — recommend it and confirm the country with them first; a mismatch is the usual cause of refused logins and sessions that log out repeatedly, and a scheduled workflow re-hits it every run, so keep the country stable once set.

get_task_status

Check the status of a task previously started in a browser session. Use to poll for completion or detect guardrails. Read-only: reports on the task without affecting it.

read-only

Argument	Type	Description
taskId*	string	Task ID to check
sessionId*	string	Session ID

Input schema (JSON)

{
  "type": "object",
  "required": [
    "sessionId",
    "taskId"
  ],
  "properties": {
    "taskId": {
      "type": "string",
      "description": "Task ID to check"
    },
    "sessionId": {
      "type": "string",
      "description": "Session ID"
    }
  }
}

get_workflow

Full detail of one workflow: prompt template, {{variables}} and their defaults, trigger + schedule, run settings (starting URL, timezone, model, proxy, output contract, files), memory state, and any pending logins. Identify by workflowId or exact title. Read-only; proxy credentials are masked.

read-only

Argument	Type	Description
title	string	Exact workflow title (case-insensitive) — alternative to workflowId
workflowId	string	24-hex workflow id (from list_workflows or create_workflow)

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "title": {
      "type": "string",
      "description": "Exact workflow title (case-insensitive) — alternative to workflowId"
    },
    "workflowId": {
      "type": "string",
      "description": "24-hex workflow id (from list_workflows or create_workflow)"
    }
  }
}

guardrail_response

Respond to a guardrail trigger when the browser agent needs human input (credentials, clarification, approval). The response is handed to the live agent, which continues acting on it.

destructive

Argument	Type	Description
files	array	Optional file IDs to attach: ids returned by POST /files/upload, or any file already in one of the user's environment catalogs (GET /environments/:id/files). Max 5 files.
newState	string	How to continue: 'resume' (default) provides the requested input and continues the task; 'deny' declines the request (response text optional).
response	string	Your response/instructions to the agent. Required when newState is 'resume'.
sessionId*	string	Session ID

Input schema (JSON)

{
  "type": "object",
  "required": [
    "sessionId"
  ],
  "properties": {
    "files": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional file IDs to attach: ids returned by POST /files/upload, or any file already in one of the user's environment catalogs (GET /environments/:id/files). Max 5 files."
    },
    "newState": {
      "enum": [
        "resume",
        "deny"
      ],
      "type": "string",
      "description": "How to continue: 'resume' (default) provides the requested input and continues the task; 'deny' declines the request (response text optional)."
    },
    "response": {
      "type": "string",
      "description": "Your response/instructions to the agent. Required when newState is 'resume'."
    },
    "sessionId": {
      "type": "string",
      "description": "Session ID"
    }
  }
}

list_agents

List the account's scheduled agents (cron deployments): schedule, status, next/last run, and whether each is standalone or deployed from a workflow. Scoped to the bound environment when this connection has one; pass scope "all" for every environment. Read-only.

read-only

Argument	Type	Description
scope	string	'environment' (default when bound) lists agents in the bound environment; 'all' lists every agent on the account.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "scope": {
      "enum": [
        "environment",
        "all"
      ],
      "type": "string",
      "description": "'environment' (default when bound) lists agents in the bound environment; 'all' lists every agent on the account."
    }
  }
}

list_environments

List available browser environments (persistent profiles) for this account. Returns environment IDs needed for persistent sessions in browser_task or create_session. Read-only. NOTE: workflows and agents use the connection's environment automatically — you rarely need this tool for those, and should not ask the user to choose an environment.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {}
}

list_sessions

List all active browser sessions for this account. Read-only.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {}
}

list_workflows

List the user's saved workflows (prompt-templated browser automations, docs.webrun.ai). Shows each workflow's title, schedule, {{variables}}, and run stats. Scoped to the bound environment when this connection has one; pass scope "all" for every environment. Read-only.

read-only

Argument	Type	Description
scope	string	'environment' (default when this connection is bound to one) lists workflows deployed to the bound environment; 'all' lists every workflow on the account.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "scope": {
      "enum": [
        "environment",
        "all"
      ],
      "type": "string",
      "description": "'environment' (default when this connection is bound to one) lists workflows deployed to the bound environment; 'all' lists every workflow on the account."
    }
  }
}

pause_agent

Pause an active scheduled agent — it stops firing until resumed. Get agentId from list_agents.

destructive

Argument	Type	Description
agentId*	string	24-hex agent id (from list_agents or create_agent)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId"
  ],
  "properties": {
    "agentId": {
      "type": "string",
      "description": "24-hex agent id (from list_agents or create_agent)"
    }
  }
}

pause_session_task

Pause the task currently running in a browser session. Resume it later with resume_session_task.

destructive

Argument	Type	Description
sessionId*	string	Session ID

Input schema (JSON)

{
  "type": "object",
  "required": [
    "sessionId"
  ],
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "Session ID"
    }
  }
}

resume_agent

Resume a paused scheduled agent — recomputes its next run and reactivates it. A completed work-list agent restarts with a fresh full pass. Refuses if the agent's expiry has passed (extend it on the dashboard first).

destructive

Argument	Type	Description
agentId*	string	24-hex agent id (from list_agents)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId"
  ],
  "properties": {
    "agentId": {
      "type": "string",
      "description": "24-hex agent id (from list_agents)"
    }
  }
}

resume_session_task

Resume a previously paused task in a browser session.

destructive

Argument	Type	Description
sessionId*	string	Session ID

Input schema (JSON)

{
  "type": "object",
  "required": [
    "sessionId"
  ],
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "Session ID"
    }
  }
}

screenshot

Capture a screenshot of the current browser page in an active session. Returns the screenshot as an inline image. Read-only.

read-only

Argument	Type	Description
sessionId*	string	Session ID

Input schema (JSON)

{
  "type": "object",
  "required": [
    "sessionId"
  ],
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "Session ID"
    }
  }
}

send_task

Send a new task to an existing browser session (from create_session). The real Chrome browser may navigate, fill forms, and submit data on third-party websites as the task requires.

destructive

Argument	Type	Description
files	array	Optional file IDs to attach: ids returned by POST /files/upload, or any file already in one of the user's environment catalogs (GET /environments/:id/files). Max 5 files.
prompt*	string	Task description
secrets	array	Domain-matched secrets [{match, fields}] (not stored)
webhook	object	Webhook configuration
sessionId*	string	Session ID from create_session
outputType	string	Response format
maxDuration	number	Max duration for this task in minutes (3-60). Defaults to the value the session was created with.
startingUrl	string	URL to navigate to before starting this task (optional)

stop_session_task

Cancel the task currently running in a browser session, keeping the session alive for new tasks.

destructive

Argument	Type	Description
sessionId*	string	Session ID

Input schema (JSON)

{
  "type": "object",
  "required": [
    "sessionId"
  ],
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "Session ID"
    }
  }
}

terminate_session

End a browser session and free its resources. The session and any running task cannot be resumed afterwards.

destructive

Argument	Type	Description
sessionId*	string	Session ID

Input schema (JSON)

{
  "type": "object",
  "required": [
    "sessionId"
  ],
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "Session ID"
    }
  }
}

trigger_workflow

Run a workflow now in its deployed environment. This is the ONLY correct way to run or TEST a saved workflow — a run started here carries the workflow's rules, tracking and memory; browser_task/create_session runs do not. When the user says "run it", "run it once", "test it" or "try it" about a workflow, this is the tool they mean. Drives a real Chrome browser: the run may navigate, fill forms, and submit data on third-party websites as the workflow's prompt requires. Pass values for the workflow's {{variables}} in `variables` (stored variableValues defaults fill any gaps). Returns a sessionId — poll get_task_status for the result.

destructive

Argument	Type	Description
force	boolean	Work-list workflows only: when the list reports complete, re-open it for a fresh full pass.
title	string	Exact workflow title (case-insensitive) — alternative to workflowId
variables	object	Values for the workflow's {{variables}}, keyed by exact variable name. Merged over the workflow's stored variableValues defaults.
workflowId	string	24-hex workflow id

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "force": {
      "type": "boolean",
      "description": "Work-list workflows only: when the list reports complete, re-open it for a fresh full pass."
    },
    "title": {
      "type": "string",
      "description": "Exact workflow title (case-insensitive) — alternative to workflowId"
    },
    "variables": {
      "type": "object",
      "description": "Values for the workflow's {{variables}}, keyed by exact variable name. Merged over the workflow's stored variableValues defaults.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "workflowId": {
      "type": "string",
      "description": "24-hex workflow id"
    }
  }
}

update_workflow

Update an existing workflow. Supply workflowId plus only the fields to change: prompt, trigger, schedule, run settings, variables, presentation. Object and array fields are replaced whole; pass null to clear an optional field. Renaming via title keeps the slug stable. The stored schedule stays a saved setting — scheduled agents already deployed from this workflow keep their own timing. promptTemplate follows the same Goal / Ground rules / Stages / Output runbook contract as create_workflow (see that field's description). memoryContract is the exception to whole-replace: supplying its three fields updates them while platform tracking details are preserved.

destructive

Argument	Type	Description
flow	object	Dashboard flow diagram: { trigger: {kind, phrase}, steps: [{ primary: {label, domain}, verb }] }.
model	string	Model profile key. Omit for the account default.
proxy	object	Proxy for runs. {source:"WebRun", country?} or {source:"custom", type:"http"\|"socks", host, port, username?, password?}. Custom passwords are encrypted at rest and never returned. Social/messaging workflows (WhatsApp, Telegram, Instagram, Facebook, X, LinkedIn, TikTok): set country to the country the user is in right now — recommend it and confirm the country with them first; a mismatch is the usual cause of refused logins and sessions that log out repeatedly, and a scheduled workflow re-hits it every run, so keep the country stable once set.
title	string	Workflow title (shown on the dashboard).
memory

WebRun Browser Automation

Try it

browser_task Destructive

WebRun Browser Automation

Try it

browser_task Destructive

Tools (21)