# 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:

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 and consent dialogs
5. **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):

```yaml
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](<https://docs.escape.tech/documentation/platform/authentication/browseragent/index.md>): `instructions` on each user):

```yaml
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.

```yaml
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 |

## 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.

```yaml
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:

```yaml
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

```yaml
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

- 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](<https://docs.escape.tech/documentation/platform/authentication/multi-factor-authentication/index.md>)

### Troubleshooting

**Issue**: Agent gets stuck on CAPTCHA **Solution**: Advanced CAPTCHA systems aren't solved automatically. Configure allowlisting as described in [Captcha Authentication](<https://docs.escape.tech/documentation/platform/authentication/captcha-authentication/index.md>).

**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):**

```yaml
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):**

```yaml
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.

## Related Documentation

- [Browser Agent Preset](<https://docs.escape.tech/documentation/platform/authentication/browseragent/index.md>): Full reference for browser\_agent preset
- [Browser Actions Preset](<https://docs.escape.tech/documentation/platform/authentication/browseractions/index.md>): Deterministic browser automation
- [Multi-User Testing](<https://docs.escape.tech/documentation/dast/multi-user-testing/index.md>): Testing with multiple user accounts