humanbrowser

{
  "name": "humanbrowser",
  "description": "Stealth cloud browser-agent with residential proxies. You describe what you want in plain English \u2014 the server runs an LLM-driven browser on a residential IP and returns a concise answer plus a live viewer URL. Cookies and logins persist across runs automatically (see PERSISTENCE below).\n\n=== HOW TO USE ===\n\nminimal call: send a message/send with one TextPart containing your goal. Example: 'Log into adsy.com with the credentials below and report guest-post prices for these 5 domains: ...'. Credentials go in a DataPart with metadata.sensitive=true. The server returns a Task \u2014 poll tasks/get OR receive a push on metadata.callback_url. That's it.\n\n=== WHAT THE SERVER HANDLES FOR YOU (do NOT pass knobs for these) ===\n\n\u2022 CAPTCHA solving (recaptcha v2/v3, hCaptcha, Turnstile, Cloudflare WAF) \u2014 automatic via CapSolver + 2captcha race.\n\u2022 Cloudflare challenge bypass \u2014 automatic engine selection per site.\n\u2022 Anti-bot fingerprint \u2014 automatic stealth profile.\n\u2022 Residential proxy stickiness \u2014 automatic per-session sticky IP.\n\u2022 Engine choice (patchright/cloak), execution mode (fast/stealth), LLM model, warmup \u2014 automatic from goal + site-rules.\n\u2022 Profile / cookie persistence \u2014 automatic from goal domain (see below).\n\nYou will NOT find these in the message/send metadata schema. If you think you need them you are usually wrong \u2014 call without them first; the right setting is picked from your goal text. (For genuine power-user overrides, see ADVANCED at the bottom.)\n\n=== PERSISTENCE (automatic) ===\n\nThe server canonicalises a profile from the first domain in your goal: 'collaborator.pro' \u2192 profile 'collaborator', 'cp.adsy.com' \u2192 'adsy', 'gogetlinks.net' \u2192 'gogetlinks'. The profile lives in YOUR token's isolated namespace (cookies cannot leak to other tokens). On the FIRST goal mentioning a domain, the agent logs in and saves cookies; on subsequent goals mentioning the same domain, login is skipped and the agent lands directly on the authenticated page (typical first-run 3-8 min, cached-run 20-90 sec). Response includes metadata.profile so you can see exactly which profile was chosen. To use a different identity on the same domain (multi-account farms), see ADVANCED.\n\nWHAT PERSISTS across tasks on the same profile: HTTP cookies (per-row merged into the profile's master Chromium UserDataDir on every successful task \u2014 concurrent logins for the same site coexist without one wiping the others), saved logins, history, and Preferences. WHAT DOES NOT PERSIST across parallel tasks: localStorage, sessionStorage, IndexedDB and Service Worker registrations \u2014 these are Chromium LevelDB stores which OS-level forbid concurrent writers, so each task gets its own in-memory copy that is discarded at task end (this is the same restriction every production multi-session browser farm imposes). For COOKIE-based auth (the vast majority of sites \u2014 Adsy, GoGetLinks, Collaborator, Reddit, Quora, Twitter, most SaaS dashboards) parallel tasks work seamlessly. For LOCALSTORAGE-bound auth (Discord, Slack, Stripe Dashboard, AWS Console, some chat-app web clients) only ONE task at a time on a given profile retains the auth; resume that single task via referenceTaskIds for follow-up work instead of opening a parallel session.\n\nPARALLELISM: send N tasks on the same profile and the server allocates N independent Chromium sessions, each cloned from the warm master profile. Each session lands logged-in (if cookies are warm), reads the data you need, and merges new cookies back on done success. Failed/canceled tasks do NOT pollute master cookies. Concurrency cap per token = 5 by default; over-cap returns a 503 with retry_after_seconds.\n\n=== VIEWER URL ===\n\nEvery response includes a live viewer URL of the form https://humanbrowser.cloud/a/s_<id>?k=<key>, returned as metadata.viewer_url and as the first artifact. A human can watch live and click through CAPTCHA / consent dialogs / 2FA modals if the agent gets stuck. Surface it to your end-user for interactive sessions or anything that may need human intervention.\n\n=== HUMAN-IN-THE-LOOP (input-required) ===\n\nWhen the agent needs something it can't derive autonomously (OTP code from an email inbox, magic-link URL, a credential you didn't pre-provide), it pauses with state=input-required and final=true. The SSE stream closes per A2A 1.0 spec; the task remains in the registry. Resume by sending a fresh message/send with message.referenceTaskIds=[taskId] and message.metadata.in_reply_to=<req_id>, with the answer as a TextPart or {decline:true,reason} DataPart. Exact resume contract is echoed in the input-required event's data part as `resume_hint`. While paused, a human operator can also answer directly from the viewer modal \u2014 first writer wins. Server-side timeout (default 300s, max 1800s) auto-declines. The agent asks ONCE and blocks; decline/timeout is terminal \u2014 no spam follow-ups.\n\n=== MOBILE UA ===\n\nFor mobile-only flows (Instagram webviews, TikTok login, mobile-specific layouts) pass metadata.mobile_ua=true on message/send. Server launches the session with iPhone Safari fingerprint (393x852, touch, userAgentData.mobile=true). Default is desktop Chrome. Fixed at spawn time.\n\n=== REPORTING CONTRACT \u2014 READ BEFORE RELAYING TO YOUR USER ===\n\nA task is one of: working | submitted | input-required | completed | failed | canceled. ONLY the last four are terminal. While state=working, the task IS still running \u2014 do NOT tell your user it failed, do NOT generate a 'probably stuck on CAPTCHA' narrative; poll tasks/get and wait for a terminal state, or use metadata.callback_url for push delivery. Expected wall-clock duration: first-run authenticated tasks on hostile sites (Cloudflare/recaptcha-gated) 3\u20138 minutes; cached subsequent runs 20\u201390 seconds.\n\nstatus.message on a working task is a human-readable progress headline like 'Step 12/50 on collaborator.pro \u2014 Submit the goodmenproject.com search'. Quote it verbatim to your user; do not paraphrase or interpret.\n\nOn terminal=failed, tasks/get attaches metadata.postmortem ({root_cause_category, observed_blockers, working_strategies, retry_recommendation}) within ~30 sec \u2014 quote those FACTS instead of inventing failure modes. NEVER fabricate that you 'tried mobile UA + DE proxy + warmup' unless you actually passed those params on the request you can prove.\n\n=== ADVANCED (rarely needed) ===\n\nPower-user overrides on message/send.metadata: profile=<slug> to pick a non-default profile (multi-account farms, A/B testing); country=<iso2> to force a proxy egress country (geo-blocked sites like BBC iPlayer\u2192uk, Polymarket\u2192jp); callback_url=<https://...> for push delivery of the terminal task envelope instead of polling. Other knobs (mode/engine/model/warmup/proxy) are accepted for backward compatibility but you should not need them \u2014 let the server choose.",
  "url": "https://agent.humanbrowser.cloud/a2a",
  "preferredTransport": "JSONRPC",
  "version": "0.1.0",
  "protocolVersion": "0.3.0",
  "provider": {
    "organization": "Virix Labs",
    "url": "https://humanbrowser.cloud"
  },
  "documentationUrl": "https://humanbrowser.cloud/a2a",
  "iconUrl": "https://humanbrowser.cloud/favicon.ico",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "securitySchemes": {
    "http_bearer": {
      "type": "http",
      "scheme": "bearer",
      "description": "Skill token issued by humanbrowser.cloud. Required on every /a2a call."
    }
  },
  "security": [
    {
      "http_bearer": []
    }
  ],
  "skills": [
    {
      "id": "browser_task",
      "name": "Browser Task",
      "description": "Execute a free-form natural-language web automation task. The agent navigates, clicks, fills forms, scrolls and reads pages on a stealth browser with a residential IP. Returns natural-language answer + structured findings. The response includes a live viewer URL (viewer_url metadata + first artifact) at https://humanbrowser.cloud/a/s_<id>?k=...; surface it to the end user when human intervention may be useful.",
      "tags": [
        "browser",
        "automation",
        "scraping",
        "navigation",
        "stealth"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ],
      "examples": [
        "Find the cheapest flight from Bangkok to Tokyo next weekend on skyscanner.com",
        "Open polymarket.com and report current odds on the top US politics market",
        "Visit reddit.com/r/programming and list the top 5 post titles"
      ]
    },
    {
      "id": "login_and_scrape",
      "name": "Login and Scrape",
      "description": "Login to a website using provided credentials (TextPart + DataPart sensitive=true with {login,password,totp?}), then perform a scraping/data-extraction task on the authenticated session. Credentials are injected at execution time and never echoed in artifacts or logs. Login flows often need human intervention (CAPTCHA, 2FA, device-trust prompts), so relaying the response's viewer URL to the end user is typically helpful for this skill.",
      "tags": [
        "browser",
        "login",
        "scraping",
        "authenticated"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ],
      "examples": [
        "Login to quora.com with the provided credentials and list questions in my feed",
        "Login to reddit.com and read my notifications inbox"
      ]
    },
    {
      "id": "fill_form",
      "name": "Fill Form",
      "description": "Open a URL and fill the form with the provided structured data (DataPart with field map). Submit and report the resulting URL/message. The response includes a viewer URL \u2014 useful to relay if a field may need human input (CAPTCHA, validation popups).",
      "tags": [
        "browser",
        "form",
        "submit"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ],
      "examples": [
        "Open https://example.com/contact and submit { name, email, message }"
      ]
    }
  ],
  "additionalInterfaces": [
    {
      "url": "https://agent.humanbrowser.cloud/a2a",
      "transport": "JSONRPC"
    }
  ],
  "customActions": [
    {
      "name": "switch_proxy_country",
      "description": "Switch the residential proxy egress country for the live session. Closes Chromium and relaunches it on a new sticky residential IP from the requested country (~5s). When a profile is in use, the chosen country is persisted onto the profile meta and inherited by future spawns. Use this when a site geo-blocks (need US for DoorDash, UK for BBC iPlayer), when an account is locked to a region (Polymarket \u2192 JP), or when warming an identity with a stable household IP.",
      "params": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "enum": [
              "us",
              "uk",
              "gb",
              "ro",
              "de",
              "nl",
              "jp",
              "fr",
              "ca",
              "au",
              "sg",
              "br",
              "in"
            ],
            "description": "ISO-3166-alpha-2 country code (lowercase)."
          }
        },
        "required": [
          "country"
        ]
      }
    }
  ]
}