WebAgent

WebAgent 是 Qoni 的网页行动层，用于让智能体在开放网页上完成搜索、抽取、浏览器操作、追踪和受控任务执行。读完本组文档后，你可以为自己的应用接入 WebAgent，创建 session，提交 run，并通过事件流获取执行结果。

WebAgent 不是传统爬虫 SDK。它面向的是 LLM 智能体的任务执行链路：开发者给出 instruction，WebAgent 管理运行时资源、页面状态、重试、结构化结果和 run 生命周期。Console 和 SDK 都只是同一组 API 的客户端。

Toward the agentic web

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，生成集成代码。