WebAgent
WebAgent 是 Qoni 的网页行动层，用于让智能体在开放网页上完成搜索、抽取、浏览器操作、追踪和受控任务执行。读完本组文档后，你可以为自己的应用接入 WebAgent，创建 session，提交 run，并通过事件流获取执行结果。
WebAgent 不是传统爬虫 SDK。它面向的是 LLM 智能体的任务执行链路：开发者给出 instruction，WebAgent 管理运行时资源、页面状态、重试、结构化结果和 run 生命周期。Console 和 SDK 都只是同一组 API 的客户端。
一个活在你浏览器里的智能体
你只需要说清楚想完成什么，WebAgent 就会把请求拆成一连串浏览器可执行的动作：打开页面、登录、搜索、填写、点击、读取结果，再把结果交回业务系统。
在企业生产环境里，约 90% 的电脑操作发生在浏览器中。WebAgent 让 AI 接手这部分工作：人不必逐个点击、复制、切换页面，只需要给出目标，浏览器里的智能体就能替你把事情做完。
WebAgent 不只是替你点几下页面，而是把浏览器变成业务系统可以直接调用的执行入口：
- 更快：复用 session、Profile 和浏览器上下文，减少重复启动、登录和等待。
- 更稳：统一管理页面状态、重试、超时和人工确认，失败可观察，也能继续执行。
- 更可控：按 project 隔离权限和成本，通过 SSE 事件流追踪每一步动作。
- 更容易接入：用一句 instruction 创建 run，Console、OpenAPI 和 raw HTTP 共享同一份契约。
传统浏览器 vs WebAgent
| 对比维度 | 传统浏览器 | WebAgent |
|---|---|---|
| 主要角色 | 展示网页，等待人操作 | 理解目标并在浏览器中执行任务 |
| 操作方式 | 人逐步点击、输入、切换页面 | 把请求拆成可执行动作，连续推进 |
| 谁来完成工作 | 人完成每一步 | Agent 代替人完成重复操作，关键节点再让人确认 |
| 任务连续性 | 页面关掉，状态往往也要重新找 | session / Profile / run 保留上下文 |
| 结果回传 | 结果停留在页面上 | 结构化结果 + SSE 事件回到业务系统 |
使用场景
WebAgent 适合那些“人每天都在浏览器里做，但不应该每天手动做”的工作：
- 企业营销：收集渠道和客户反馈，整理成洞察，自动生成并发布内容。
- 销售与客户成功：登录 CRM、汇总客户动态、更新跟进记录，触发下一步动作。
- 运营与电商：跨站点采集价格、库存和活动信息，批量更新后台，发现异常及时提醒。
- 研究与情报：检索公开网页，交叉核对来源，持续跟踪竞争对手和行业变化。
- 内部流程：在后台系统中查询、填表、下载、核对，并把结果回写到业务系统。
迈向智能体网络
Qoni 的目标是让智能体成为 Web 的一等公民。WebAgent 不只是在后台模拟点击，也不只把页面渲染给人看；它把用户、智能体和 Web 放进同一个可审计的协作层，让智能体能在授权边界内读取、行动、产出结果，并在需要时把状态渲染回用户。
什么时候使用 WebAgent
- 你的智能体需要访问实时网页数据，而不是只依赖模型训练数据或固定知识库。
- 你需要把搜索、网页抽取、浏览器动作和长程任务封装成可审计的 API。
- 你希望 Console、SDK 和后端服务都走同一份 REST API 契约。
- 你需要通过 session / run 模型保存运行状态、订阅事件流，或处理需要人工确认的步骤。
什么时候不要使用 WebAgent
- 任务只需要调用你自己的后端 API，不需要访问开放网页。
- 你需要的是大规模离线爬取、数据仓库同步或搜索引擎索引构建。
- 目标站点的使用条款不允许自动化访问，且你没有取得必要授权。
- 你还没有定义 API key、project scope、run 预算和失败重试策略。
核心能力
| 能力 | 说明 |
|---|---|
| DoAnything API | 给出自然语言 instruction，由 WebAgent 选择工具、执行步骤并返回结果。 |
| Shaped APIs | 对 DeepResearch、WebSearch、Track 等固定产物形态提供更明确的 API 契约。 |
| Session / Run model | 用 session 持有运行时资源，用 run 表达一次任务或后续动作。 |
| Event stream | 通过 SSE 订阅 run 状态、输出片段、错误和人工确认请求。 |
| SDK and raw HTTP | Python、TypeScript 和 cURL 文档使用同一份 API 语义。 |
文档入口
- 什么是 WebAgent：理解 WebAgent 的定位、边界和 API 形态。
- 快速开始：用 Python、TypeScript 或 cURL 跑通第一个 run。
- 鉴权与 API key：了解
wa_key、project scope 和轮换策略。 - DoAnything：理解 session、run、event 和 profile 的生命周期。
- 错误与重试：查看错误码、重试策略和幂等处理。
- API 参考：查看 base URL、鉴权、错误、限流和分页约定。
- Vibecoding：把文档和 OpenAPI 交给 IDE 中的 LLM，生成集成代码。