Skip to content

Agentic Browser Authentication

Overview

Agentic Browser Authentication leverages AI to automate complex login flows that cannot be handled by traditional deterministic approaches. Instead of manually scripting each interaction, you provide natural language instructions that guide an AI agent through the authentication process.

How It Works

The agentic mode uses an AI-powered browser agent that:

  1. Inspects the page to understand the current state
  2. Interprets your instructions to determine the next actions
  3. Executes browser actions like filling forms, clicking buttons, and navigating
  4. Adapts to dynamic flows such as multi-step logins, CAPTCHAs, and consent dialogs

When to Use Agentic Mode

Use agentic authentication when:

  • Login flows are complex or multi-step
  • The application has dynamic forms that change based on input
  • You need to handle edge cases like cookie consent banners, CAPTCHAs, or MFA
  • The login process requires conditional logic (e.g., "if popup appears, click Accept")
  • Traditional selector-based automation fails due to unpredictable DOM structures

Configuration

Preset-Level Configuration

Enable agentic mode in your browser_agent preset (under the top-level presets key of your authentication configuration):

presets:
  - type: browser_agent
    login_url: https://app.example.com/login
    agentic:
      enabled: true
      instructions: |
        Dismiss any cookie consent banners first.
        Look for a "Login with SSO" button and click it if present.

Configuration Options:

Property Type Default Description
enabled boolean false Enable agentic browser mode
instructions string "" Global natural-language instructions for the login flow

Per-User Instructions

Provide user-specific instructions for edge cases (same field as in the Browser Agent preset reference: instructions on each user):

presets:
  - type: browser_agent
    login_url: https://app.example.com/login
    agentic:
      enabled: true
      instructions: Handle any cookie banners or welcome dialogs.
    users:
      - username: admin@company.com
        password: admin-password
        instructions: After login, navigate to /admin to ensure admin privileges are active.
      - username: user@company.com
        password: user-password
        instructions: Accept the terms of service popup if it appears after login.

Per-User Configuration:

Property Type Description
instructions string Additional natural-language instructions for this user (agentic login only)

Pre-Login Actions

Execute actions before the main login step. The runner runs pre_login_actions first, then either deterministic form filling or the agentic login when agentic.enabled is true.

presets:
  - type: browser_agent
    login_url: https://app.example.com/login
    users:
      - username: user@example.com
        password: password123
        pre_login_actions:
          - action: click
            locator: button[id="accept-cookies"]
          - action: sleep
            seconds: 2

Common use cases:

  • Accepting cookie consent banners
  • Closing promotional popups
  • Navigating to the correct login page

Post-Login Actions

Execute actions after successful authentication:

presets:
  - type: browser_agent
    login_url: https://app.example.com/login
    users:
      - username: user@example.com
        password: password123
        post_login_actions:
          - action: fill_totp
            locator: input[id="totp-code"]
            secret: "JBSWY3DPEHPK3PXP"
            auto_submit: true
          - action: wait_text
            value: "Welcome back"
            timeout: 10

Common use cases:

  • Entering TOTP/MFA codes
  • Navigating to specific post-login pages
  • Handling "Remember this device" prompts

Complete Example

presets:
  - type: browser_agent
    login_url: https://app.example.com/login
    logged_in_detector_text: "Welcome back"
    logged_in_detector_timeout: 15
    stealth_mode: true
    agentic:
      enabled: true
      instructions: |
        Handle any cookie consent dialogs or promotional popups.
        If a "Continue with Google" button is present, prefer it over email/password.
    users:
      - username: admin@company.com
        password: SecureAdminPass123!
        role: admin
        main_user: true
        instructions: |
          After successful login, ensure the URL contains "/dashboard".
          If a "Verify your identity" prompt appears, complete it.
        pre_login_actions:
          - action: goto
            url: https://app.example.com/login
            timeout: 30
        post_login_actions:
          - action: wait_element
            locator: div.dashboard-header
            timeout: 10
          - action: click
            locator: button[id="dismiss-welcome"]
            allow_failure: true

      - username: standard@company.com
        password: StandardPass456!
        role: user
        instructions: |
          Accept the terms of service if a popup appears.
          Do not enable "Remember me" if prompted.
        pre_login_actions:
          - action: sleep
            seconds: 3

Best Practices

Writing Effective Instructions

  1. Be specific but concise: Describe exactly what the agent should do without unnecessary verbosity
  2. Use action-oriented language: "Click", "Fill", "Wait for", "Navigate to"
  3. Mention visual cues: "the red button", "the popup with title 'Welcome'"
  4. Handle conditionals: "If X appears, do Y"
  5. Include error recovery: "If not found, try alternative Z"

Security Considerations

  • Never include actual credentials in instructions
  • The agent will never echo credentials in its responses
  • Instructions are processed by the AI but credentials remain secure

Troubleshooting

Issue: Agent gets stuck on CAPTCHA Solution: Disable agentic mode for CAPTCHA-heavy sites or use stealth_mode: true

Issue: Login takes too long Solution: Increase logged_in_detector_timeout or add more specific instructions

Issue: Agent clicks wrong elements Solution: Provide more specific selectors in instructions or use pre_login_actions to prepare the page

Comparison: Agentic vs Deterministic Mode

Feature Agentic Mode Deterministic Mode
Complexity Handles complex, dynamic flows Best for simple, static forms
Configuration Natural language instructions Explicit selectors and actions
Flexibility Adapts to changes automatically Requires updates when UI changes
Speed Slightly slower (AI processing) Faster (direct automation)
Reliability Better for unpredictable flows Better for consistent flows
Use Case Modern SPAs, SSO flows, edge cases Traditional form-based logins

Migration from Deterministic to Agentic

If you're currently using browser_actions preset, you can migrate to browser_agent with agentic mode:

Before (browser_actions):

presets:
  - type: browser_actions
    login_url: https://example.com/login
    users:
      - username: user@example.com
        actions:
          - action: fill
            locator: input[name="email"]
            value: user@example.com
          - action: fill
            locator: input[name="password"]
            value: mypassword
          - action: click
            locator: button[type="submit"]

After (browser_agent with agentic):

presets:
  - type: browser_agent
    login_url: https://example.com/login
    agentic:
      enabled: true
      instructions: Fill the email and password fields, then submit the form.
    users:
      - username: user@example.com
        password: mypassword

For simple flows, agentic mode can replace many lines of action configuration with a single instruction.