Skip to content

Automate browser based workflows with AI

Let Copilot use a connected inbox for sign-in codes, not just saved credentials (#8200)

Andrew Neilson22a3292f8b15
diff --git a/skyvern/forge/prompts/skyvern/workflow-copilot-system.j2 b/skyvern/forge/prompts/skyvern/workflow-copilot-system.j2
index 24c4ca358..c6d290d46 100644
--- a/skyvern/forge/prompts/skyvern/workflow-copilot-system.j2
+++ b/skyvern/forge/prompts/skyvern/workflow-copilot-system.j2
@@ -82,7 +82,7 @@ IMPORTANT RULES:
- Put the credential ID in the default_value field, NOT in the key field
- Reference the descriptive key in parameter_keys, NOT the credential ID
- - If login fails with TOTP/2FA errors (including rate limiting), ask the user for a TOTP-enabled credential (e.g., cred_123)
+ - If login fails with TOTP/2FA errors (including rate limiting), offer two options: ask the user for a TOTP-enabled credential (e.g., cred_123), or use identifier-based OTP (`await otp("<email>")` in code mode, or `totp_identifier: <email>` in standard login block mode) if the org has an active Gmail or Outlook connection for that email address
Note that user usually works with UI and not aware of YAML, avoid mentioning YAML in user-facing response.
diff --git a/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt b/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt
index 220c22a3d..c366ba9e7 100644
--- a/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt
+++ b/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt
@@ -435,6 +435,8 @@ error_code_mapping: {} # Optional: Custom error codes
max_retries: 0 # Optional: Retry attempts
max_steps_per_run: null # Optional: Step limit
parameter_keys: [] # Required: Should include credential parameters
+totp_identifier: <email_addr> # Optional: Email or phone for inbox-integration OTP (no saved credential required)
+totp_verification_url: <url> # Optional: URL where the TOTP code must be entered
complete_criterion: null # Optional: Completion condition
terminate_criterion: null # Optional: Termination condition
complete_verification: true # Optional: Verify successful login
@@ -444,10 +446,11 @@ Use Cases:
- Handle 2FA/TOTP authentication
- Manage credential-protected workflows
- Session initialization
+- Passwordless email-code sign-in (using totp_identifier with an active Gmail/Outlook connection)
Important Notes:
-- Credentials should be stored as parameters (credential, bitwarden_login_credential, etc.)
-- TOTP is automatically handled if the credential parameter has TOTP configured
+- **Credential-bound TOTP:** Credentials should be stored as parameters (credential, bitwarden_login_credential, etc.). TOTP is automatically handled if the credential parameter has TOTP configured (totp_type: authenticator/email/text).
+- **Identifier-based TOTP:** For passwordless email-code sign-in, set totp_identifier to the email address and ensure an active Gmail or Outlook connection exists for that mailbox. No saved credential is required. The system will automatically poll the connected mailbox for the verification code.
Example:
workflow_definition:
@@ -467,6 +470,13 @@ workflow_definition:
key: my_credentials
default_value: "cred_uuid_here"
+Login Goal Authoring Guidance for Email-Code Flows:
+
+For passwordless email-code sign-in (using totp_identifier with a connected Gmail/Outlook inbox):
+- **Completion condition:** Anchor to the logged-in state, not the code screen. Set complete_criterion to recognize a post-login page or URL pattern (e.g., "Current URL is 'https://example.com/dashboard' or page contains 'Welcome'"). Do NOT use 'a code field is now visible' or 'user pressed Enter' as a completion condition, as these occur mid-flow.
+- **Code entry as agent action:** The login block automatically detects code fields and enters codes fetched from the connected inbox. Phrase the goal as the agent's own work: "Enter the verification code sent to the email" is sufficient; avoid stating the code fetch itself as a separate user action.
+- **Magic-link alternatives:** If the challenge screen offers "Use another method" or similar, prefer an email-code path over a magic link. Magic links often redirect, and the system may lose sync with the redirect target. An email code, once typed, offers a simple, synchronous path to completion.
+
** VALIDATION BLOCK (validation) **
Purpose: Validate workflow state and decide whether to continue or terminate.
diff --git a/skyvern/forge/sdk/copilot/tools/__init__.py b/skyvern/forge/sdk/copilot/tools/__init__.py
index 44bdd7230..89e0e873b 100644
--- a/skyvern/forge/sdk/copilot/tools/__init__.py
+++ b/skyvern/forge/sdk/copilot/tools/__init__.py
@@ -509,8 +509,8 @@ async def list_credentials_tool(
@function_tool(name_override="list_integrations")
async def list_integrations_tool(ctx: RunContextWrapper) -> str:
"""List the organization's connected Google and Microsoft accounts (metadata only —
- never tokens). Each entry has `connection_id`, `provider`, `name`, `state`, and
- `scopes_granted`.
+ never tokens). Each entry has `connection_id`, `provider`, `name`, `state`,
+ `email_address`, and `scopes_granted`.
These are OAuth connections made on the Integrations page, NOT the stored
login credentials returned by `list_credentials` — the two lists are disjoint,
@@ -940,12 +940,17 @@ async def fill_credential_field_tool(
This tool only fills; it never clicks or submits. Each successful fill is
recorded as a scouted interaction with the credential identity and field.
- In model-authored code blocks, one-time codes must use
- `await <parameter_key>.otp()` so authenticator, email, and SMS OTP sources
- all resolve at runtime. Choose and declare the workflow parameter key, then
- cite the observed `credential_id` and `credential_field` in
- `code_artifact_metadata.input_bindings`; use that declared parameter in the
- authored code rather than guessing a key or reading an inbox integration.
+ In model-authored code blocks, one-time codes resolve via two paths:
+ **credential-bound:** `await <parameter_key>.otp()` for a saved credential whose
+ totp_type is authenticator, email, or text — sources are specified at credential
+ creation. **identifier-based:** `await otp("<address>")` for passwordless email-code
+ sign-in, where the code lands in a connected Gmail or Outlook inbox and address is
+ a bare email (no saved credential required). For the credential-bound path, choose and
+ declare the workflow parameter key, then cite the observed `credential_id` and
+ `credential_field` in `code_artifact_metadata.input_bindings`; use that declared
+ parameter in the authored code. For the identifier-based path, pass only the email
+ address string to `otp()` and ensure an active Gmail or Outlook connection exists
+ for that mailbox.
"""
result = await _fill_credential_field_impl(ctx.context, selector, credential_id, field)
return json.dumps(scrub_secrets_from_structure(ctx.context, result))
diff --git a/skyvern/forge/sdk/copilot/tools/credentials.py b/skyvern/forge/sdk/copilot/tools/credentials.py
index b516a03d0..a5bf1653c 100644
--- a/skyvern/forge/sdk/copilot/tools/credentials.py
+++ b/skyvern/forge/sdk/copilot/tools/credentials.py
@@ -254,6 +254,8 @@ def _serialize_credential(credential: Credential) -> dict[str, Any]:
if credential.username:
entry["username"] = credential.username
entry["totp_type"] = str(credential.totp_type) if credential.totp_type else None
+ if credential.totp_identifier:
+ entry["totp_identifier"] = credential.totp_identifier
elif credential.card_last4:
entry["card_last_four"] = credential.card_last4
entry["card_brand"] = credential.card_brand
diff --git a/skyvern/forge/sdk/copilot/tools/integrations.py b/skyvern/forge/sdk/copilot/tools/integrations.py
index 35d570939..cd7864524 100644
--- a/skyvern/forge/sdk/copilot/tools/integrations.py
+++ b/skyvern/forge/sdk/copilot/tools/integrations.py
@@ -14,13 +14,16 @@ def _serialize(
) -> dict[str, Any]:
# Allowlist rather than a model dump: both source models are token-free today,
# so a dump would start leaking the day either one gains a token field.
- return {
+ result: dict[str, Any] = {
"connection_id": credential.id,
"provider": provider,
"name": credential.credential_name,
"state": credential.state,
"scopes_granted": list(credential.scopes_granted),
}
+ if credential.email_address:
+ result["email_address"] = credential.email_address
+ return result
async def _list_integrations(params: dict[str, Any], ctx: AgentContext) -> dict[str, Any]:
diff --git a/tests/unit/test_copilot_request_policy_workflow_credentials.py b/tests/unit/test_copilot_request_policy_workflow_credentials.py
index a36c38162..64f1d9286 100644
--- a/tests/unit/test_copilot_request_policy_workflow_credentials.py
+++ b/tests/unit/test_copilot_request_policy_workflow_credentials.py
@@ -17,6 +17,7 @@ def _cred(name: str, credential_id: str, *, tested_url: str | None = None) -> Si
credential_type=CredentialType.PASSWORD,
username="[email protected]",
totp_type=None,
+ totp_identifier=None,
card_last4=None,
card_brand=None,
secret_label=None,
diff --git a/tests/unit/test_copilot_tools_list_credentials.py b/tests/unit/test_copilot_tools_list_credentials.py
new file mode 100644
index 000000000..f2fc10817
--- /dev/null
+++ b/tests/unit/test_copilot_tools_list_credentials.py
@@ -0,0 +1,60 @@
+from datetime import datetime
+
+from skyvern.forge.sdk.copilot.tools.credentials import _serialize_credential
+from skyvern.forge.sdk.schemas.credentials import Credential, CredentialType, TotpType
+
+SECRET_MARKER = "SECRET_VALUE"
+
+
+def _password_credential(**overrides: object) -> Credential:
+ defaults = {
+ "credential_id": "cred_1",
+ "organization_id": "o_test_org",
+ "name": "Portal login",
+ "vault_type": "bitwarden",
+ "item_id": "6e3e136a-f457-44ea-8462-b49700735145",
+ "credential_type": CredentialType.PASSWORD,
+ "username": "[email protected]",
+ "card_last4": None,
+ "card_brand": None,
+ "created_at": datetime(2026, 8, 13),
+ "modified_at": datetime(2026, 8, 13),
+ }
+ return Credential(**{**defaults, **overrides})
+
+
+def test_surfaces_the_two_fa_identifier_so_the_agent_can_see_which_credential_carries_which() -> None:
+ entry = _serialize_credential(_password_credential(totp_type=TotpType.EMAIL, totp_identifier="[email protected]"))
+
+ assert entry["totp_identifier"] == "[email protected]"
+ assert entry["totp_type"] == str(TotpType.EMAIL)
+
+
+def test_omits_the_identifier_when_the_credential_carries_none() -> None:
+ entry = _serialize_credential(_password_credential(totp_type=TotpType.AUTHENTICATOR))
+
+ assert "totp_identifier" not in entry
+ assert entry["totp_type"] == str(TotpType.AUTHENTICATOR)
+
+
+def test_serializes_metadata_only_so_no_secret_or_vault_material_reaches_the_agent() -> None:
+ entry = _serialize_credential(
+ _password_credential(
+ totp_type=TotpType.EMAIL,
+ totp_identifier="[email protected]",
+ tested_url="https://portal.example.com/login",
+ item_id=SECRET_MARKER,
+ user_context=SECRET_MARKER,
+ )
+ )
+
+ assert set(entry) == {
+ "credential_id",
+ "name",
+ "credential_type",
+ "tested_url",
+ "username",
+ "totp_type",
+ "totp_identifier",
+ }
+ assert not any(SECRET_MARKER in str(value) for value in entry.values())
diff --git a/tests/unit/test_copilot_tools_list_integrations.py b/tests/unit/test_copilot_tools_list_integrations.py
index f01543e12..fd76e63b3 100644
--- a/tests/unit/test_copilot_tools_list_integrations.py
+++ b/tests/unit/test_copilot_tools_list_integrations.py
@@ -113,18 +113,34 @@ def test_serializer_is_an_allowlist_so_a_new_token_field_cannot_leak() -> None:
id="goac_1",
credential_name="Sheets account",
state="active",
+ email_address="[email protected]",
scopes_granted=["https://www.googleapis.com/auth/spreadsheets"],
**{name: f"SECRET_{name}" for name in TOKEN_FIELD_NAMES},
)
entry = _serialize(leaky_google, "google")
- assert set(entry) == {"connection_id", "provider", "name", "state", "scopes_granted"}
+ assert set(entry) == {"connection_id", "provider", "name", "state", "scopes_granted", "email_address"}
for name in TOKEN_FIELD_NAMES:
assert name not in entry
assert not any("SECRET_" in str(value) for value in entry.values())
+async def test_surfaces_the_mailbox_address_so_the_agent_can_bind_an_identifier(patched_services) -> None:
+ patched_services(
+ [_google(email_address="[email protected]")],
+ [_microsoft(email_address="[email protected]")],
+ )
+ ctx = SimpleNamespace(organization_id=ORGANIZATION_ID)
+
+ result = await _list_integrations({}, ctx)
+
+ google_entry, microsoft_entry = result["data"]["integrations"]
+ assert google_entry["email_address"] == "[email protected]"
+ assert microsoft_entry["email_address"] == "[email protected]"
+
+
@pytest.mark.asyncio
async def test_lists_a_google_connection_whose_grant_expired(patched_services) -> None:
patched_services([_google(state="error")], [])