Agentic Mode¶

Overview¶

Agentic Browser Authentication uses AI to automate complex login flows. Provide natural language instructions to guide the agent through forms, consent dialogs, and authentication challenges.

How It Works¶

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

Inspects the page to understand the current state
Interprets your instructions to determine the next actions
Executes browser actions like filling forms, clicking buttons, and navigating
Adapts to dynamic flows such as multi-step logins and consent dialogs
Reads email codes and magic links from the Escape scan mailbox and generates TOTP codes when you provide the authenticator secret in instructions

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 or MFA
The login process requires conditional logic (for example, "if popup appears, click Accept")
Page structures change between login attempts

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.
    users:
      - username: user@example.com
        password: password123

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)

Logout Detection Instructions¶

Use logout_detection.instructions to describe the page state that confirms authentication and the signals that indicate logout.

presets:
  - type: browser_agent
    login_url: https://app.example.com/login
    agentic:
      enabled: true
      instructions: Handle cookie banners and SSO prompts.
    logout_detection:
      enabled: true
      instructions: |
        A successful login lands on /dashboard and shows the left navigation.
        Ignore the onboarding modal if it appears.
        Treat redirects back to /login or "session expired" banners as logout.
    users:
      - username: user@example.com
        password: password123

Which Instruction Field To Use¶

Field	Scope	Best used for
`agentic.instructions`	Shared across all users in the preset	Common login steps, SSO choices, cookie banners, global popups
`users[].instructions`	One specific user	Role-specific branches, post-login checks, user-only prompts
`logout_detection.instructions`	Post-login verification	What success looks like, expected redirects, signals of failed login or logout

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

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¶

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

Security Considerations¶

The username, password, additional fields, and instructions are sent to the AI model as part of the login request
Escape redacts username, password, and additional-field values from agentic login events. Don't assume every log or agent output is fully redacted
If the agent needs to generate TOTP codes, provide the base32 secret in the login instructions. See Multi-Factor Authentication

Troubleshooting¶

Issue: Agent gets stuck on CAPTCHA Solution: Advanced CAPTCHA systems aren't solved automatically. Configure allowlisting as described in Captcha Authentication.

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

Choosing Agentic or Deterministic Mode¶

Feature	Agentic Mode	Deterministic Mode
Configuration	Natural language instructions	Explicit selectors and actions
Navigation	Chooses actions from page state	Follows configured steps
Maintenance	Update instructions for your flow	Update selectors when UI changes
Use Case	Dynamic forms, SSO, consent dialogs	Forms with stable selectors

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.

Browser Agent Preset: Full reference for browser_agent preset
Browser Actions Preset: Deterministic browser automation
Multi-User Testing: Testing with multiple user accounts