抓取页面以获取干净的数据，然后调用 /interact 在该页面中开始执行 actions——点击按钮、填写表单、提取动态内容，或进一步深入导航。只需描述你想做什么；如果需要完全控制，也可以编写代码。
代码执行 通过代码安全地与 playwright、agent-browser 交互
Live view 通过可嵌入的流实时观看或与浏览器交互
使用 POST /v2/scrape 抓取 一个 URL。响应会在 data.metadata.scrapeId 中返回 scrapeId。你也可以选择传入 profile，以在不同会话间持久保存浏览器状态。
调用 POST /v2/scrape/{scrapeId}/interact，并传入 prompt 或 Playwright code 进行交互 。首次调用时，会恢复已抓取的会话，此时你可以开始与页面交互。
完成后，使用 DELETE /v2/scrape/{scrapeId}/interact 停止 该会话。
抓取页面、与其交互，然后停止会话：
from firecrawl import Firecrawl app = Firecrawl( api_key = "fc-YOUR-API-KEY" ) # 1. 抓取 Amazon 首页 result = app.scrape( "https://www.amazon.com" , formats = [ "markdown" ]) scrape_id = result.metadata[ "scrapeId" ] # 2. 交互 — 搜索商品并获取价格 app.interact(scrape_id, prompt = "Search for iPhone 16 Pro Max" ) response = app.interact(scrape_id, prompt = "Click on the first result and tell me the price" ) print (response.output) # 3. 停止会话 app.stop_interaction(scrape_id)
{ "success" : true , "liveViewUrl" : "https://liveview.firecrawl.dev/..." , "interactiveLiveViewUrl" : "https://liveview.firecrawl.dev/..." , "output" : "The iPhone 16 Pro Max (256GB) is priced at $1,199.00." , "exitCode" : 0 , "killed" : false }
这是与页面交互的最简单方式。用自然语言描述你的需求，它会自动点击、输入、滚动并提取数据。
response = app.interact(scrape_id, prompt = "What are the customer reviews saying about battery life?" ) print (response.output)
响应中包含一个 output 字段，其中包含代理的答案：
{ "success" : true , "liveViewUrl" : "https://liveview.firecrawl.dev/..." , "interactiveLiveViewUrl" : "https://liveview.firecrawl.dev/..." , "output" : "Customers are generally positive about battery life. Most reviewers report 8-10 hours of use on a single charge. A few noted it drains faster with heavy multitasking." , "stdout" : "..." , "result" : "..." , "stderr" : "" , "exitCode" : 0 , "killed" : false }
当每个 prompt 都是单一且明确的任务 时，效果最好。不要一次性要求代理完成复杂的多步骤工作流，而应将其拆分为单独的交互调用。每次调用都会复用同一个浏览器会话，因此状态会在调用之间延续。
若要实现完全控制，你可以直接在浏览器沙箱中执行代码。page 变量 (一个 Playwright Page 对象) 可在 Node.js 和 Python 中使用。Bash 模式已预装 agent-browser 。
默认语言。可直接编写 Playwright 代码——page 已连接到浏览器。
response = app.interact(scrape_id, code = """ // 点击按钮并等待页面导航 await page.click('#next-page'); await page.waitForLoadState('networkidle'); // 从新页面提取内容 const title = await page.title(); const content = await page.$eval('.article-body', el => el.textContent); JSON.stringify({ title, content }); """ ) print (response.result)
将 language 设置为 "python"，以使用 Playwright 的 Python API。
response = app.interact( scrape_id, code = """ import json await page.click('#load-more') await page.wait_for_load_state('networkidle') items = await page.query_selector_all('.item') data = [] for item in items: text = await item.text_content() data.append(text.strip()) print(json.dumps(data)) """ , language = "python" , ) print (response.stdout)
agent-browser 是一个预装在沙箱中的 CLI 工具，提供 60 多个命令。它会提供带有元素引用 (@e1、@e2 等) 的辅助功能树，非常适合由 LLM 驱动的自动化。# 拍摄快照以查看交互元素 snapshot = app.interact( scrape_id, code = "agent-browser snapshot -i" , language = "bash" , ) print (snapshot.stdout) # 输出： # [document] # @e1 [input type="text"] "Search..." # @e2 [button] "Search" # @e3 [link] "About" # 使用 @refs 与元素交互 app.interact( scrape_id, code = 'agent-browser fill @e1 "firecrawl" && agent-browser click @e2' , language = "bash" , )
常见的 agent-browser 命令：
命令 描述 snapshot带元素引用的完整辅助功能树 snapshot -i仅显示可交互元素 click @e1通过引用点击元素 fill @e1 "text"清空字段并输入文本 type @e1 "text"不清空直接输入 press Enter按下键盘按键 scroll down 500向下滚动 500 像素 get text @e1获取文本内容 get url获取当前 URL wait @e1等待元素出现 wait --load networkidle等待网络空闲 find text "X" click按文本查找元素并点击 eval "js code"在页面中运行 JavaScript
每个交互响应都包含可用于实时查看浏览器会话的 URL。
字段 描述 liveViewUrl只读流 — 可嵌入以观看会话 interactiveLiveViewUrl交互式流 — 观看者可以点击、输入并进行交互
<!-- Read-only view --> < iframe src = "LIVE_VIEW_URL" width = "100%" height = "600" / > <!-- Interactive view — viewers can control the browser --> < iframe src = "INTERACTIVE_LIVE_VIEW_URL" width = "100%" height = "600" / >
交互式实时视图对于构建面向用户的 UI 非常有用，这类 UI 需要让最终用户看到浏览器并与之交互，例如登录流程、CAPTCHA 处理或引导式工作流。
首次调用 POST /v2/scrape/{scrapeId}/interact 会创建一个沙盒浏览器会话，其页面状态与抓取时相同。
对同一个 scrapeId 的后续 interact 调用会复用现有会话。浏览器会保持打开状态，并在调用之间保留其状态，因此你可以将多个交互串联起来：
# 第一次调用——点击一个标签页 app.interact(scrape_id, code = "await page.click('#tab-2')" ) # 第二次调用——该标签页仍保持选中状态，提取其内容 result = app.interact(scrape_id, code = "await page.$eval('#tab-2-content', el => el.textContent)" ) print (result.result)
完成后请显式停止会话：
app.stop_interaction(scrape_id)
会话也会根据 TTL (默认值：10 分钟) 或无活动 timeout (默认值：5 分钟) 自动过期。
请务必在使用完毕后停止会话，以避免不必要的计费。额度按秒折算。
默认情况下，每个 scrape + interact 会话都会从全新的浏览器状态开始。使用 profile，你可以在多次抓取之间保存并复用浏览器状态 (cookies、localStorage、会话) 。这对于保持登录状态和保留偏好设置非常有用。
调用 scrape 时传入 profile 参数。profile 名称相同的会话会共享状态。
from firecrawl import Firecrawl app = Firecrawl( api_key = "fc-YOUR-API-KEY" ) # 会话 1：使用配置文件进行抓取，登录，然后停止（状态已保存） result = app.scrape( "https://app.example.com/login" , formats = [ "markdown" ], profile = { "name" : "my-app" , "save_changes" : True }, ) scrape_id = result.metadata[ "scrapeId" ] app.interact(scrape_id, prompt = "Fill in user@example.com and password, then click Login" ) app.stop_interaction(scrape_id) # 会话 2：使用相同配置文件进行抓取——已处于登录状态 result = app.scrape( "https://app.example.com/dashboard" , formats = [ "markdown" ], profile = { "name" : "my-app" , "save_changes" : True }, ) scrape_id = result.metadata[ "scrapeId" ] response = app.interact(scrape_id, prompt = "Extract the dashboard data" ) print (response.output) app.stop_interaction(scrape_id)
参数 默认值 描述 name— 持久化配置文件的名称。名称相同的抓取会共享浏览器状态。 saveChangestrue当为 true 时，interact 会话停止后会将浏览器状态保存回该配置文件。设为 false 可在不写入的情况下加载现有数据——适用于你需要多个并发只读会话的场景。
同一时间只能有一个会话保存到某个配置文件。如果另一个会话已在保存，你将收到 409 错误。你仍然可以使用 saveChanges: false 打开同一个配置文件，或稍后重试。
浏览器状态会在 interact 会话停止时保存。完成后请务必停止该会话，以便该配置文件可以被复用。
使用场景 推荐 原因 网页搜索 Search 专用搜索端点 从 URL 获取干净内容 Scrape 一次 API 调用，无需会话 在页面上点击、输入、导航 交互 (prompt)只需用英文描述即可 提取交互后的数据 交互 (prompt)无需选择器 复杂的抓取逻辑 交互 (code)完整的 Playwright 控制能力
交互 与 浏览器沙箱 ：交互构建在与 浏览器沙箱 相同的基础设施之上，但针对最常见的使用模式提供了更好的界面——先抓取页面，再进一步深入。当你需要一个不绑定到特定抓取任务的独立浏览器会话时，浏览器沙箱更合适。每个会话分钟 2 个额度 ，按秒折算。抓取本身单独计费 (每次抓取 1 个额度，外加任何特定格式的费用) 。
执行交互 — POST /v2/scrape/{scrapeId}/interact停止交互 — DELETE /v2/scrape/{scrapeId}/interact
字段 类型 默认值 描述 promptstring— 提供给 AI 代理的自然语言任务。若未设置 code，则此项必填。最多 10,000 个字符。 codestring— 要执行的代码 (Node.js、Python 或 Bash) 。若未设置 prompt，则此项必填。最多 100,000 个字符。 languagestring"node""node"、"python" 或 "bash"。仅在使用 code 时生效。timeoutnumber30超时时间，单位为秒 (1–300) 。 originstring— 用于活动追踪的调用方标识符。
字段 描述 success如果执行已完成且未出现错误，则为 true liveViewUrl浏览器会话的只读实时视图 URL interactiveLiveViewUrl交互式实时视图 URL (查看者可控制浏览器) output代理对你的 prompt 给出的自然语言回答。仅在使用 prompt 时返回。 stdout代码执行的标准输出 resultsandbox 的原始返回值。对于 code：最后一个求值的表达式。对于 prompt：代理用于生成 output 的原始页面快照。 stderr标准错误输出 exitCode退出码 (0 = 成功) killed如果执行因超时而终止，则为 true
有反馈或需要帮助？请发送邮件至 help@firecrawl.com ，或通过 Discord 联系我们。 
