Sensitive Data
Handle sensitive information securely and avoid sending PII & passwords to the LLM.
Handling Sensitive Data
When working with sensitive information like passwords or PII, you can use the Agent(sensitive_data=...)
parameter to provide sensitive strings that the model can use in actions without ever seeing directly.
You should also configure BrowserSession(allowed_domains=...)
to prevent the Agent from visiting URLs not needed for the task.
Basic Usage
Here’s a basic example of how to use sensitive data:
In this example:
- The LLM only ever sees the
x_member_number
andx_passphrase
placeholders in prompts - When the model wants to use your password it outputs x_passphrase - and we replace it with the actual value in the DOM
- When sensitive data appear in the content of the current page, we replace it in the page summary fed to the LLM - so that the model never has it in its state.
- The browser will be entirely prevented from going to any site not under
https://*.example.com
This approach ensures that sensitive information remains secure while still allowing the agent to perform tasks that require authentication.
Best Practices
- Always restrict your sensitive data to only the exact domains that need it,
https://travel.example.com
is better than*.example.com
- Always restrict
BrowserSession(allowed_domains=[...])
to only the domains the agent needs to visit to accomplish its task. This helps guard against prompt injection attacks, jailbreaks, and LLM mistakes. - Only use
sensitive_data
for strings that can be inputted verbatim as text. The LLM never sees the actual values, so it can’t “understand” them, adapt them, or split them up for multiple input fields. For example, you can’t ask the Agent to click through a datepicker UI to input the sensitive value1990-12-31
. For these situations you can implement a custom function the LLM can call that updates the DOM using Python / JS. - Don’t use
sensitive_data
for login credentials, it’s better to usestorage_state
or auser_data_dir
to log into the sites the agent needs in advance & reuse the cookies:
Then use those cookies when the agent runs:
Warning: Vision models still see the screenshot of the page by default - where the sensitive data might be visible.
It’s recommended to set Agent(use_vision=False)
when working with sensitive_data
.
Allowed Domains
Domain patterns in sensitive_data
follow the same format as allowed_domains
:
example.com
- Matches onlyhttps://example.com/*
*.example.com
- Matcheshttps://example.com/*
and any subdomainhttps://*.example.com/*
http*://example.com
- Matches bothhttp://
andhttps://
protocols forexample.com/*
chrome-extension://*
- Matches any Chrome extension URL e.g.chrome-extension://anyextensionid/options.html
Security Warning: For security reasons, certain patterns are explicitly rejected:
- Wildcards in TLD part (e.g.,
example.*
) are not allowed (google.*
would matchgoogle.ninja
,google.pizza
, etc. which is a bad idea)- Embedded wildcards (e.g.,
g*e.com
) are rejected to prevent overly broad matches- Multiple wildcards like
*.*.domain
are not supported currently, open an issue if you need this feature
The default protocol when no scheme is specified is now https://
for enhanced security.
For convenience the system will validate that all domain patterns used in Agent(sensitive_data)
are also included in BrowserSession(allowed_domains)
.
Missing or Empty Values
When working with sensitive data, keep these details in mind:
- If a key referenced by the model (
<secret>key_name</secret>
) is missing from yoursensitive_data
dictionary, a warning will be logged but the substitution tag will be preserved. - If you provide an empty value for a key in the
sensitive_data
dictionary, it will be treated the same as a missing key. - The system will always attempt to process all valid substitutions, even if some keys are missing or empty.
Full Example
Here’s a more complex example demonstrating multiple domains and sensitive data values.
With this approach:
- The Google credentials (
x_email
andx_pass
) will only be used on Google domains (any subdomain, https only) - The API key (
x_api_key
) will only be used on pages served by the specific Chrome extensionabcd1243
- The auth code (
x_authcode
) will only be used onhttp://example.com/*
orhttps://example.com/*