Profiles

Profile 是一份整体的浏览器身份：cookies、localStorage、各个站点的登录态都存在同一份 Profile 里。它不按站点拆分——一个用户对应一份 Profile，agent 用它打开浏览器时，这个人在所有站点的登录态都在。

创建 session 或 monitor 时用 profile_id 引用它，agent 就带着这份身份打开浏览器，不用每次重新登录。没有 Profile，每个 session 都是一张白纸——撞到需要登录的页面就只能停下。

不要按站点拆 Profile

Profile 是整体的。需要哪些站点，就在同一份 Profile 里逐个登录一遍；后续所有任务共用这一份，不要为每个站点单独建 Profile。

什么时候用

• 任务要访问需要登录的站点（邮箱、社交平台、内部系统）。
• 你希望多个 session / monitor 共享同一份登录态，而不是各自登录。
• 登录态需要跨任务、跨天复用。

任务只访问公开页面、不需要登录时，不用 Profile。

创建并登录一个 Profile

第一次给 Profile 装登录态，推荐在 Console 里做：Console 会开一个受控浏览器，你在里面正常登录、过验证码、做想做的设置，登录态就落进 Profile。这一步天然需要人操作，Console 是最顺的形态。

之后这个 Profile 就能被代码反复引用。也可以用 API 管理 Profile 资源：

POST   /v1/projects/{pid}/profiles            创建 profile
GET    /v1/projects/{pid}/profiles            列出 profile
GET    /v1/projects/{pid}/profiles/{id}       查单个
PATCH  /v1/projects/{pid}/profiles/{id}       改名等
DELETE /v1/projects/{pid}/profiles/{id}       删除

创建时可带的字段：

字段	类型	说明
name	string	给 Profile 起个好认的名字，通常对应一个用户
customer_user_id	string	把 Profile 关联到你业务系统里的用户

交互式登录走 POST /v1/projects/{pid}/profiles/login 和 POST /v1/projects/{pid}/profiles/{id}/confirm——具体请求体见 OpenAPI spec。

API 里还有个 cookie_domains 字段，只服务旧的「自带 cookies」B2B 接入路径，整体 Profile 用不到，可忽略。

在 session / monitor 里用 Profile

拿到 profile_id 后，创建 session 时引用它：

from web_agent.v1 import Client
from web_agent.v1.types import CreateSessionRequest

async with Client(api_key="wa_...", project_id="proj_demo") as client:
    session = await client.sessions.create(CreateSessionRequest(
        instructions="打开 LinkedIn 收件箱，回复最新一条消息。",
        profile_id="prof_alice",
    ))

Track 的 monitor 同样接受 profile_id，监控需要登录的站点时用它。

Profile 状态

Profile 的 state 和这几个字段反映它还能不能用：

字段	说明
state	Profile 当前状态
last_used_at	最近一次被 session / monitor 使用的时间
last_alive_at	最近一次确认登录态仍有效的时间
last_failure_reason	最近一次使用失败的原因

cookies 和登录态会过期。如果 run 因为登录失效而失败，last_failure_reason 会说明原因——这时需要回到 Console 重新登录一次该 Profile。把这一步做成可观测的，比让 run 反复在登录页失败更省成本。

接下来

• DoAnything —— profile_id 怎么进 session
• Track —— 给长期监控复用登录态
• API 概览 —— 共享约定；字段全集见 OpenAPI spec