Skip to content

Automate browser based workflows with AI

feat: persist user_context on credentials (#SKY-8074) (#5081)

Celal Zamanoğlua0d082da40ee
diff --git a/alembic/versions/2026_03_13_0122-b37f05a2bfbf_user_context_for_credentials_table.py b/alembic/versions/2026_03_13_0122-b37f05a2bfbf_user_context_for_credentials_table.py
new file mode 100644
index 000000000..d209bf017
--- /dev/null
+++ b/alembic/versions/2026_03_13_0122-b37f05a2bfbf_user_context_for_credentials_table.py
@@ -0,0 +1,31 @@
+"""user_context for credentials table
+
+Revision ID: b37f05a2bfbf
+Revises: 08f585f2e7a6
+Create Date: 2026-03-13 01:22:48.294533+00:00
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "b37f05a2bfbf"
+down_revision: Union[str, None] = "08f585f2e7a6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ # ### commands auto generated by Alembic - please adjust! ###
+ op.add_column("credentials", sa.Column("user_context", sa.String(length=1000), nullable=True))
+ # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+ # ### commands auto generated by Alembic - please adjust! ###
+ op.drop_column("credentials", "user_context")
+ # ### end Alembic commands ###
diff --git a/skyvern/forge/sdk/db/agent_db.py b/skyvern/forge/sdk/db/agent_db.py
index 37bc4a07d..71a709abd 100644
--- a/skyvern/forge/sdk/db/agent_db.py
+++ b/skyvern/forge/sdk/db/agent_db.py
@@ -5477,6 +5477,7 @@ class AgentDB(BaseAlchemyDB):
card_brand: str | None,
totp_identifier: str | None = None,
secret_label: str | None = None,
+ user_context: str | None = None,
) -> Credential:
async with self.Session() as session:
credential = CredentialModel(
@@ -5491,6 +5492,7 @@ class AgentDB(BaseAlchemyDB):
card_last4=card_last4,
card_brand=card_brand,
secret_label=secret_label,
+ user_context=user_context,
)
session.add(credential)
await session.commit()
@@ -5532,6 +5534,7 @@ class AgentDB(BaseAlchemyDB):
name: str | None = None,
browser_profile_id: str | None | object = _UNSET,
tested_url: str | None | object = _UNSET,
+ user_context: str | None | object = _UNSET,
) -> Credential:
async with self.Session() as session:
credential = (
@@ -5550,6 +5553,8 @@ class AgentDB(BaseAlchemyDB):
credential.browser_profile_id = browser_profile_id
if tested_url is not _UNSET:
credential.tested_url = tested_url
+ if user_context is not _UNSET:
+ credential.user_context = user_context
await session.commit()
await session.refresh(credential)
return Credential.model_validate(credential)
diff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.py
index ca5685dab..19109201d 100644
--- a/skyvern/forge/sdk/db/models.py
+++ b/skyvern/forge/sdk/db/models.py
@@ -975,6 +975,7 @@ class CredentialModel(Base):
secret_label = Column(String, nullable=True)
browser_profile_id = Column(String, nullable=True)
tested_url = Column(String, nullable=True)
+ user_context = Column(String(1000), nullable=True)
created_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)
modified_at = Column(DateTime, default=datetime.datetime.utcnow, onupdate=datetime.datetime.utcnow, nullable=False)
diff --git a/skyvern/forge/sdk/routes/credentials.py b/skyvern/forge/sdk/routes/credentials.py
index 5585db7be..d95a8976c 100644
--- a/skyvern/forge/sdk/routes/credentials.py
+++ b/skyvern/forge/sdk/routes/credentials.py
@@ -444,6 +444,8 @@ async def rename_credential(
}
if data.tested_url is not None:
update_kwargs["tested_url"] = data.tested_url
+ if data.user_context is not None:
+ update_kwargs["user_context"] = data.user_context
updated = await app.DATABASE.update_credential(**update_kwargs)
if not updated:
raise HTTPException(status_code=500, detail="Failed to update credential")
@@ -1774,6 +1776,7 @@ def _convert_to_response(credential: Credential) -> CredentialResponse:
name=credential.name,
browser_profile_id=credential.browser_profile_id,
tested_url=credential.tested_url,
+ user_context=credential.user_context,
)
elif credential.credential_type == CredentialType.CREDIT_CARD:
credential_response = CreditCardCredentialResponse(
@@ -1787,6 +1790,7 @@ def _convert_to_response(credential: Credential) -> CredentialResponse:
name=credential.name,
browser_profile_id=credential.browser_profile_id,
tested_url=credential.tested_url,
+ user_context=credential.user_context,
)
elif credential.credential_type == CredentialType.SECRET:
credential_response = SecretCredentialResponse(secret_label=credential.secret_label)
@@ -1797,6 +1801,7 @@ def _convert_to_response(credential: Credential) -> CredentialResponse:
name=credential.name,
browser_profile_id=credential.browser_profile_id,
tested_url=credential.tested_url,
+ user_context=credential.user_context,
)
else:
raise HTTPException(status_code=400, detail="Credential type not supported")
diff --git a/skyvern/forge/sdk/schemas/credentials.py b/skyvern/forge/sdk/schemas/credentials.py
index b933fe47d..02e90a18a 100644
--- a/skyvern/forge/sdk/schemas/credentials.py
+++ b/skyvern/forge/sdk/schemas/credentials.py
@@ -177,6 +177,10 @@ class CredentialResponse(BaseModel):
name: str = Field(..., description="Name of the credential", examples=["Amazon Login"])
browser_profile_id: str | None = Field(default=None, description="Browser profile ID linked to this credential")
tested_url: str | None = Field(default=None, description="Login page URL used during the credential test")
+ user_context: str | None = Field(
+ default=None,
+ description="User-provided context describing the login sequence (e.g., 'click SSO button first')",
+ )
class Credential(BaseModel):
@@ -208,6 +212,10 @@ class Credential(BaseModel):
secret_label: str | None = Field(default=None, description="For secret credentials: optional label")
browser_profile_id: str | None = Field(default=None, description="Browser profile ID linked to this credential")
tested_url: str | None = Field(default=None, description="Login page URL used during the credential test")
+ user_context: str | None = Field(
+ default=None,
+ description="User-provided context describing the login sequence (e.g., 'click SSO button first')",
+ )
created_at: datetime = Field(..., description="Timestamp when the credential was created")
modified_at: datetime = Field(..., description="Timestamp when the credential was last modified")
@@ -228,6 +236,16 @@ class UpdateCredentialRequest(BaseModel):
description="Optional login page URL associated with this credential",
examples=["https://example.com/login"],
)
+ user_context: str | None = Field(
+ default=None,
+ max_length=1000,
+ description="Optional user-provided context describing the login sequence (e.g., 'click SSO button first')",
+ )
+
+ @field_validator("user_context", mode="before")
+ @classmethod
+ def normalize_user_context(cls, v: str | None) -> str | None:
+ return _normalize_optional_str(v)
def _normalize_optional_str(v: str | None) -> str | None: