09 / 开发者 API

浏览器代码 API：函数说明与调用示例

支持 Python、Node.js、Java、Go 四种 API 接入方式。本页依据 GitHub 接口调用手册，整理环境配置、会话管理、页面观察、输入操作、文件与 Skill 等函数说明。

安装与首次调用

pip install kingai-browser
python -m kingai_browser install

先登录 KingAI 账号，并准备好唯一的已有“默认环境”。下面示例启动该环境，读取网页，再释放控制并保留浏览器窗口。指定其他环境时，向 api.start() 传入真实 profile_id。

from kingai_browser import KingAI

with KingAI() as api:
    browser = api.start()
    try:
        browser.goto("https://www.kingaibrowser.cn/")
        print(browser.read())
    finally:
        browser.detach()

下方各节是独立用法，不应从头到尾连续执行。按需求选择操作，并替换为真实的环境、会话、元素和 Skill ID。示例用于说明文档中的接口，不代表已在你的目标网站完成实测。

调用方式与四种语言
环境列表与配置
启动、接管与生命周期
标签页与导航
页面读取、快照与查询
等待、点击、输入与滚动
JavaScript 求值与有限预览
截图、PDF 与文件传输
Cookie 与 Storage
已保存 Skill 工作流
安装版全部工具
错误处理与执行结果

01 · 调用方式与四种语言

Python、Node.js、Java、Go 共享工具名称和原始 JSON 字段。会话级 call 自动加入 session_id；原始参数名不会自动转换成 camelCase。后续示例以 Python 展示，api 表示已连接的 KingAI，browser 表示正在运行的会话。

调用方式与四种语言 — 函数说明
函数 / 调用方式	用途
`launch()`	简化连接与环境启动，返回 BrowserSession；适合普通 Python 自动化脚本。
`KingAI`	显式管理客户端连接、环境增删改查、工具发现与会话。
`BrowserAutomation`	接收 Agent action，调用同一 SDK，整理观察状态与错误；用于 Agent 适配层。
`agent_browser.execute(action, **arguments)`	派发 go_to_url、query、click_element、input_text、extract_content 或 mcp_call 等动作。元素动作需要已观察到的 ref 或精确 selector。
`agent_browser.get_current_state()`	实时读取页面、快照和标签页，返回含 interactive_elements 的状态字典；不是缓存查询。
`agent_browser.describe_error(error)`	把错误整理为 Agent 适配层使用的结构化信息。
`agent_browser.close()`	断开此适配层的 MCP 连接并保留窗口；上下文退出同样如此，不等于会话 close_browser()。
`browser.call(name, **arguments)`	Python 会话级工具调用。
`await browser.call(name, arguments)`	Node.js：每次操作都需要 await。
`browser.call(name, Map.of(...))`	Java：返回 Jackson JsonNode。
`browser.Call(ctx, name, kingai.Arguments{...})`	Go：传入 context，并处理返回的 error。

BrowserAutomation：Agent 动作与状态适配

这三个入口属于同一个 SDK，共用已安装的 MCP/Runtime，不是三种浏览器引擎。BrowserAutomation 从 kingai_browser 导入，负责接收动作、执行并整理状态，不是 AI 模型或自主规划器。页面变更动作会整理后续观察；观察失败不会自动重放输入，Agent 仍需根据页面结果判断业务是否成功。

import json
from kingai_browser import BrowserAutomation

with BrowserAutomation(profile_id="actual-saved-profile-id") as agent_browser:
    # Replace the ID with one from KingAI.profiles(); do not invent one.
    result = agent_browser.execute("go_to_url", url="https://example.com")
    state = agent_browser.get_current_state()
    print(state["url"], state["title"])

    snapshot = json.loads(state["interactive_elements"])
    for element in snapshot.get("elements", []):
        print(element.get("ref"), element.get("name"))

    # Query through the facade rather than guessing an element index.
    links = agent_browser.execute("query", arguments={"selector": "a", "limit": 10})
    print(links)

真实环境 ID、会话复用与 OpenManus

运行前把示例 ID 替换为 KingAI.profiles() 返回的真实 ID；省略 profile_id 才会使用唯一的已有默认环境。接管已有会话可传 BrowserAutomation(session_id="实际活动会话ID")，需要接管权限且不能同时传 profile_id。普通脚本已有 BrowserSession 时，直接复用 query()/snapshot()，不要额外启动适配层。OpenManus 的 browser_use 是工具名称；其内部委托 BrowserAutomation.execute() 和 get_current_state()，二者不是同一个接口名称。

四种语言的通用调用

Python

# Python: arbitrary installed tool; keyword arguments bind to the current session.
result = browser.call("browser_query", selector="#name", include_html=True)

Node.js

// Node.js: same tool and raw arguments; await every operation.
const result = await browser.call('browser_query', { selector: '#name', include_html: true });

Java

// Java: Session.call injects session_id, Jackson JsonNode is returned.
JsonNode result = browser.call("browser_query", Map.of("selector", "#name", "include_html", true));

// Go: Session.Call injects session_id. Always propagate the returned error.
result, err := browser.Call(ctx, "browser_query", kingai.Arguments{"selector": "#name", "include_html": true})
if err != nil { return err }

02 · 环境列表与配置

创建和修改配置不会启动浏览器。环境名称必须唯一；更新前需先关闭对应环境。group_name 必须指向已有分组。patch 递归合并对象，数组整体替换。删除环境是独立且不可撤销的操作，请只针对你确实要删除的环境执行。

环境列表与配置 — 函数说明
函数 / 调用方式	用途
`api.profiles()`	列出已保存的环境摘要。
`api.create_profile(name, language="en-US")`	创建环境，返回 profileId。
`api.profile(profile_id)`	读取指定环境。
`api.update_profile(profile_id, name=..., patch=...)`	更新名称与配置。
`api.delete_profile(profile_id, confirm=True)`	确认删除已关闭的环境。

Python

saved = api.profiles()                        # profiles_list: saved summaries
created = api.create_profile("Unique example", language="en-US")
profile_id = created["profileId"]             # ID returned by creation
summary = api.profile(profile_id)             # profiles_get
api.update_profile(profile_id, name="Configured example", patch={
    "locale": {"language": "en-US", "accept_languages": "en-US,en"}
})
updated = api.profile(profile_id)
# Optional, destructive: only after explicitly closing this environment.
# api.delete_profile(profile_id, confirm=True)

03 · 启动、接管与生命周期

api.start() 使用唯一的已有“默认环境”；不存在时会报错，不会悄悄创建临时环境。临时环境必须明确传入 temporary=True。attach 受服务端所有权规则限制；异常断线后应先查看会话状态。Python with launch() 和 Java 自动 Session.close() 会断开其拥有的连接并保留窗口；显式关闭浏览器分别使用 Python close_browser()/close()、Node.js closeBrowser()/close()、Java closeBrowser()、Go CloseBrowser()/Close()。不要把不同语言中同名的 close 当成相同操作。

启动、接管与生命周期 — 函数说明
函数 / 调用方式	用途
`api.start(profile_id=..., headless=False)`	启动指定环境，返回浏览器会话。
`api.sessions()`	查看真实活动会话。
`api.attach(session_id)`	在所有权规则允许时接管已有会话。
`browser.detach()`	释放控制，保留浏览器窗口。
`browser.close() / browser.close_browser()`	Python：显式关闭浏览器。
`api.close()`	关闭本客户端的 MCP 连接。

Python

browser = api.start(profile_id=profile_id, headless=False)
session_id = browser.session_id
active = api.sessions()                       # inspect real active sessions
# Another client can request attach only if server ownership rules allow it:
# browser = api.attach(session_id)
browser.detach()                             # leave browser available
# browser.close()                            # explicitly close the browser
# api.close()                                # only close this client's MCP

04 · 标签页与导航

操作作用于当前选中的标签页。标签页切换和输入应串行执行，会话不是可并行操作多个 Page 的模型。targetId 必须来自真实返回值，只关闭你明确要关闭的标签页。示例中的本地 demo.html 地址需要你先准备对应演示页面。

标签页与导航 — 函数说明
函数 / 调用方式	用途
`browser.new_tab(url)`	打开新标签页，读取返回的 targetId。
`browser.tabs()`	列出标签页。
`browser.activate_tab(target_id)`	激活指定标签页。
`browser.goto(url)`	导航当前标签页。
`browser.close_tab(target_id)`	显式关闭指定标签页。

Python

opened = browser.new_tab("http://127.0.0.1:8765/demo.html")
target_id = opened["targetId"]
all_tabs = browser.tabs()
browser.activate_tab(target_id)
browser.goto("http://127.0.0.1:8765/demo.html")
# Explicitly close ONLY a tab you created and no longer need:
# browser.close_tab(target_id)

05 · 页面读取、快照与查询

普通 Python 自动化脚本打开页面后，直接调用当前会话的 query() 和 snapshot()，不需要先创建 browser_state 或接入 Agent 框架。query() 无筛选时可枚举有限的 DOM 摘要；snapshot(mode="interactive") 聚焦交互候选，默认 compact 快照也可包含上下文文字和结构。

页面读取、快照与查询 — 函数说明
函数 / 调用方式	用途
`browser.read()`	读取可读页面内容。
`browser.snapshot(mode="interactive", limit=30, max_chars=12000)`	获取有限的交互元素快照。
`browser.query(selector=..., include_html=True, limit=20)`	查询元素；outerHTML 有大小限制。
`browser.query(cursor=next_cursor)`	续读同一次捕获的查询结果。

打开网页后获取 DOM 元素

示例实际执行部分只读取 example.com 的链接，不点击或提交内容。被注释的 #name 输入示例需要用于真实包含该输入框的页面。返回值是 JSON 观察摘要，不是能调用 element.click() 的实时 DOM 对象，也不是无限制的完整 HTML；动作应通过 SDK 的 click/fill 等方法执行。元素字段可包含 ref、tag、role、name、attributes、text、bounds、states 和 frameId，具体取决于安装版与观察模式。with launch() 退出保留窗口。

from kingai_browser import launch

with launch() as browser:
    browser.new_tab("https://example.com")
    browser.wait(selector="body", state="visible", timeout_ms=15000)

    # Read a compact DOM/accessibility observation with actionable refs.
    snapshot = browser.snapshot(mode="interactive", limit=30)
    print(snapshot.get("text", ""))

    # Query actual DOM elements and request bounded outerHTML when needed.
    result = browser.query(selector="a", include_html=True, limit=20)
    for element in result.get("elements", []):
        print(element.get("ref"), element.get("tag"), element.get("name"))
        print(element.get("attributes", {}))

    # On a page containing your own form, query the exact intended input:
    # found = browser.query(selector="#name", limit=2)["elements"]
    # if len(found) != 1:
    #     raise RuntimeError("Expected exactly one input")
    # browser.fill(ref=found[0]["ref"], text="KingAI", humanize=False)

interactive_elements 的来源与结构

interactive_elements 是可选 BrowserAutomation 适配层的字段，由 Python 的 capture_state() 临时整理，不保存在浏览器或环境数据库中。下面片段仅说明字段赋值；真实状态还包含 url、title、session_id、tabs、page_content 和 help。字段值是“整个有限快照响应”的 JSON 字符串，不是元素数组；当前适配层使用默认 compact 快照，名称并不意味着只包含可交互元素。

snapshot = browser.snapshot(max_chars=20000)
state = {"interactive_elements": json.dumps(snapshot, ensure_ascii=False)}

先解析字符串，再读取 elements

用 json.loads() 得到快照字典，再遍历其中的 elements，并留意 text 与 truncated。不要直接遍历整个 interactive_elements 字符串。如果已经通过 launch()/KingAI 打开页面，继续使用同一会话；不要为了获得此字段重复启动默认环境。确需新建适配层时，应显式接管有权限的已有 session_id。导航或 DOM 替换后重新获取 ref，分页只传服务器返回的 cursor，不重新发送筛选条件。

import json
from kingai_browser import BrowserAutomation

with BrowserAutomation() as agent_browser:
    agent_browser.execute("go_to_url", url="https://example.com")
    browser_state = agent_browser.get_current_state()
    snapshot = json.loads(browser_state["interactive_elements"])
    for element in snapshot.get("elements", []):
        print(element.get("ref"), element.get("tag"), element.get("name"))
    print(snapshot.get("text", ""))
    print("Snapshot truncated:", snapshot.get("truncated", False))

快照预算与查询分页

Python

page = browser.read()                         # readable page content
snapshot = browser.snapshot(mode="interactive", limit=30, max_chars=12000)
query = browser.query(selector="input, textarea, button", include_html=True, limit=20)
elements = query["elements"]                 # bounded DOM summaries, not live DOM objects
for element in elements:
    print(element.get("ref"), element.get("tag"), element.get("name"))
# Follow the SAME captured observation without resending filters:
if query.get("nextCursor"):
    next_page = browser.query(cursor=query["nextCursor"])

06 · 等待、点击、输入与滚动

selector 与 ref 二选一，不要同时传。示例中的表单选择器需要替换为目标页面真实元素。fill 替换内容，type 追加内容。humanize=False 用于基础示例；启用拟人化需要有效会员权益。操作已派发不代表业务已成功，应再观察页面结果。Java/Go 的输入便捷方法也支持 options。

等待、点击、输入与滚动 — 函数说明
函数 / 调用方式	用途
`browser.wait(selector=..., state="visible", timeout_ms=15000)`	等待页面条件。
`browser.fill(ref=..., text=..., humanize=False)`	替换输入内容。
`browser.type(ref=..., text=..., humanize=False)`	追加输入内容。
`browser.click(selector, humanize=False)`	点击元素。
`browser.key("Tab", humanize=False)`	发送按键。
`browser.hover(selector, humanize=False)`	悬停元素。
`browser.scroll(300, humanize=False)`	滚动页面。

Python

browser.wait(selector="#name", state="visible", timeout_ms=15000)
found = browser.query(selector="#name", limit=2)
if len(found["elements"]) != 1:
    raise RuntimeError("Expected exactly one name input")
name_ref = found["elements"][0]["ref"]
browser.fill(ref=name_ref, text="KingAI", humanize=False)     # replace existing text
browser.type(ref=name_ref, text=" SDK", humanize=False)      # append text
browser.key("Tab", humanize=False)
browser.hover("#submit", humanize=False)
browser.scroll(300, humanize=False)
browser.click("#submit", humanize=False)
browser.wait(selector='#result[data-submitted="true"]', timeout_ms=10000)
result_text = browser.evaluate("document.querySelector('#result').textContent")

07 · JavaScript 求值与有限预览

evaluate 保留原始求值语义。evaluate_preview 返回有限预览，truncated 表示结果不完整。较大的 evaluate 结果可能在表达式已经执行后返回 RESULT_TOO_LARGE，不能为拿到结果而重复执行带副作用的表达式。Node.js/Java 对应 evaluatePreview，Go 对应 EvaluatePreview。

JavaScript 求值与有限预览 — 函数说明
函数 / 调用方式	用途
`browser.evaluate(expression)`	执行 JavaScript 表达式。
`browser.evaluate_preview(expression)`	获取有限的结果预览。

Python

title = browser.evaluate("document.title")
preview = browser.evaluate_preview("({title:document.title,text:document.body.innerText})")
if preview.get("truncated"):
    print("Preview is partial; request selected fields or read-only pages of data")

08 · 截图、PDF 与文件传输

构造客户端时可配置绝对路径 file_roots、download_dir、artifact_dir。上传文件必须位于允许的目录内。截图和 PDF 返回服务端产物描述，不应假定返回值是字节数组。上传和下载示例需要真实的文件控件或下载链接。

截图、PDF 与文件传输 — 函数说明
函数 / 调用方式	用途
`browser.screenshot()`	生成页面截图。
`browser.pdf()`	生成页面 PDF。
`browser.upload(paths, selector=...)`	向实际文件上传控件提供文件。
`browser.download(selector=...)`	通过实际下载链接发起下载。

Python

# Configure absolute trusted paths when constructing the client:
# KingAI(file_roots=[r"D:\demo\uploads"],
#        download_dir=r"D:\demo\downloads", artifact_dir=r"D:\demo\artifacts")
image = browser.screenshot()
document = browser.pdf()
# Target-page examples; the local form does not contain these elements:
# browser.upload([r"D:\demo\uploads\document.txt"], selector='input[type="file"]')
# browser.download(selector="#download-link")

09 · Cookie 与 Storage

以下方法用于读取站点状态。不要将 Cookie 或 Storage 输出到公开日志。修改状态的扩展操作应先读取当前安装版工具 schema，不猜测 setter 参数。

Cookie 与 Storage — 函数说明
函数 / 调用方式	用途
`browser.cookies()`	读取 Cookie。
`browser.storage()`	读取站点 Storage。

Python

cookies = browser.cookies()
storage = browser.storage()
# Do not print/export cookies or storage into public logs.

10 · 已保存 Skill 工作流

先列出 Skill，再用真实 skill_id 读取说明，按实际参数定义启动回放。runId 必须取自启动返回值。不同 Skill 的参数并不相同；Java/Go 缺少便捷方法时可使用通用 call / Call。

已保存 Skill 工作流 — 函数说明
函数 / 调用方式	用途
`api.skills()`	列出保存的 Skill。
`api.describe_skill(skill_id)`	读取 Skill 说明与参数。
`api.run_skill(profile_id, skill_id, **options)`	按实际定义启动回放。
`api.skill_status(run_id)`	查询运行状态。
`api.cancel_skill(run_id)`	明确取消某次运行。
`api.skill_runs()`	列出 Skill 运行记录。

Python

skills = api.skills()
# Use a real skill_id from the list, then inspect required parameters:
# description = api.describe_skill(skill_id)
# started = api.run_skill(profile_id, skill_id, **options_from_description)
# status = api.skill_status(started["runId"])
# api.cancel_skill(started["runId"])  # only if you intend to cancel
runs = api.skill_runs()

11 · 安装版全部工具

便捷方法不代表安装版所有能力。iframe、网络、控制台等接口可通过工具目录查看名称、必填字段与描述，再使用通用调用。下面的命令从 GitHub 仓库根目录运行，需要先取得仓库中的示例脚本；它们不是 pip 包自带的命令。

仓库示例命令

python python/examples/mcp_tool_catalog.py
python python/examples/mcp_tool_catalog.py --tool browser_query

12 · 错误处理与执行结果

KingAIError 提供稳定错误码。不要用自动重试重放一次结果未知的点击或输入。只有服务端提供真实 Runtime 请求 ID 时才能使用 request_status，JSON-RPC ID 不是替代品。PAGE_NOT_VISIBLE 需要恢复并激活目标页面；跨客户端所有权、账号额度与 Lease 仍然生效。

错误处理与执行结果 — 函数说明
函数 / 调用方式	用途
`KingAIError.code`	读取错误码，避免公开敏感详情。

Python

from kingai_browser import KingAIError
try:
    page = browser.read()
except KingAIError as error:
    print(error.code)  # keep structured details private unless sanitized
    raise             # no automatic replay of a previous click/type

具体代码使用可以参照GITHUB：接口调用手册 →