TinyFish:给AI Agent装上「上网能力」的企业级基础设施

在AI Agent飞速发展的今天，大模型越来越聪明，但它们有一个共同的短板——上不了网。无法实时搜索信息、无法浏览网页、无法自动操作网站，这让AI Agent的能力被大大限制。

TinyFish 就是为了解决这个问题而生的。它提供了一套企业级的 Web API，让任何 AI Agent 都能获得搜索、浏览、提取网页内容甚至自动操作网站的能力。

一个API Key，四大核心能力

TinyFish 的核心设计理念是「简单集成」。一个 API Key，统一的 credit 池，四个独立的 API 覆盖从搜索到自动化操作的全链路场景。

1. Search API — 网页搜索

输入查询关键词，返回结构化的搜索结果（标题、摘要、URL），直接可供 LLM 消费或程序化处理。

核心特性：

• 支持地区和语言偏好设置，获取本地化搜索结果
• 完全免费，不消耗 credits
• 速率限制：60次/分钟

使用示例（Python）：

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(
    query="2024年最佳AI编程工具",
    location="CN",
    language="zh"
)
for r in response.results:
    print(r.title, "→", r.url)

cURL 调用：

curl "https://api.search.tinyfish.ai?query=2024年最佳AI编程工具&location=CN&language=zh" \
  -H "X-API-Key: $TINYFISH_API_KEY"

2. Fetch API — 网页内容提取

用真实浏览器渲染网页（包括 JS 动态渲染的 SPA 页面），提取干净的页面内容。单次请求最多支持 10 个 URL，每个 URL 独立处理。

核心特性：

• 完全免费，不消耗 credits
• 速率限制：300个URL/分钟
• 支持三种输出格式：Markdown、HTML、JSON
• 支持 PDF 文本提取、代理请求

基础使用：

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=[
        "https://example.com/article1",
        "https://example.com/article2",
    ]
)

for page in result.results:
    print(page.url, "→", page.title)
    print(page.text)  # 干净的 Markdown 格式

3. Agent API — 自然语言驱动的网页自动化

这是 TinyFish 最核心的能力。用自然语言描述任务目标，TinyFish 会在真实的浏览器中自动执行操作——点击、输入、导航、提取数据，全程自动化。

三种调用模式：

• /run — 同步模式，适合简单快速的任务
• /run-async — 异步模式，适合长时间任务和批量处理
• /run-sse — SSE实时事件流，适合需要实时反馈的应用

数据提取示例：

from tinyfish import TinyFish, CompleteEvent

client = TinyFish()

with client.agent.stream(
    url="https://scrapeme.live/shop",
    goal="提取前2个商品名称和价格，返回JSON格式",
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            print(event.result_json)

多步骤工作流：

with client.agent.stream(
    url="https://example.com/login",
    goal="""
    1. 在登录页面输入用户名和密码
    2. 点击登录按钮
    3. 等待仪表盘加载完成
    4. 提取页面上的账户余额信息
    5. 返回JSON格式的余额数据
    """,
) as stream:
    for event in stream:
        print(event)

4. Browser API — 远程浏览器会话

创建一个远程 Chrome 浏览器实例，通过 CDP WebSocket 连接，可以用 Playwright、Puppeteer 等工具直接驱动。

from tinyfish import TinyFish
import asyncio
from playwright.async_api import async_playwright

client = TinyFish()
session = client.browser.sessions.create(url="https://example.com")

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(session.cdp_url)
        page = browser.contexts[0].pages[0]
        await page.wait_for_load_state("domcontentloaded")
        print(await page.title())

asyncio.run(main())

Goal 编写指南：如何写出高质量的任务指令

Agent API 的核心参数是 goal（目标）。TinyFish 官方测试数据显示，精确的 goal 比模糊的 goal 执行速度快 4.9 倍，返回数据量减少 16 倍。

一个好 goal 的七个要素：

• 目标 — 要完成什么
• 对象 — 关注哪个区域
• 字段 — 要哪些数据
• 格式 — 输出结构
• 步骤 — 操作顺序
• 约束 — 不要做什么
• 异常处理 — 遇到意外怎么办

生产级 Goal 示例：

从该产品页面提取以下信息：
- 产品名称（页面显示的完整标题）
- 当前价格（仅数字，不含货币符号）
- 如有原价则提取，否则设为null
- 货币代码
- 是否有库存（true/false）

如果出现cookie弹窗，先关闭它。
不要点击任何"加入购物车"或"立即购买"按钮。

返回以下结构的JSON：
{
  "product_name": "string",
  "current_price": number或null,
  "original_price": number或null,
  "currency": "string",
  "in_stock": boolean
}

实战教程：5分钟从零开始

Step 1：注册账号
访问 agent.tinyfish.ai/sign-up，注册即送 500 免费 credits。

Step 2：获取 API Key
进入 agent.tinyfish.ai/api-keys，点击「Create API Key」：

export TINYFISH_API_KEY="你的API密钥"

Step 3：安装 SDK

# Python
pip install tinyfish

# Node.js / TypeScript
npm install @tiny-fish/sdk

Step 4：运行第一个自动化任务

from tinyfish import TinyFish, CompleteEvent

client = TinyFish()

with client.agent.stream(
    url="https://scrapeme.live/shop",
    goal="提取前2个商品名称和价格，返回JSON格式",
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            print(event.result_json)

运行后你会看到实时事件流：

{'type': 'STARTED', 'run_id': 'abc123'}
{'type': 'PROGRESS', 'purpose': 'Visit the page'}
{'type': 'COMPLETE', 'result': {
    "products": [
        {"name": "Bulbasaur", "price": "$63.00"},
        {"name": "Ivysaur", "price": "$87.00"}
    ]
}}

与主流 AI Agent 框架集成

与 OpenClaw 集成：让 AI 助手具备联网能力

OpenClaw 是一个开源的多通道 AI Agent 网关，支持 Discord、Telegram、WhatsApp、飞书、iMessage 等十多个聊天平台。通过集成 TinyFish，可以让 AI 助手直接获得搜索和网页浏览能力。

配置方法：在 openclaw.json 中添加：

{
  "plugins": {
    "entries": {
      "tinyfish": {
        "enabled": true,
        "config": {
          "apiKey": "你的TinyFish API Key"
        }
      }
    }
  }
}

实际使用场景：

• 用户在飞书问「帮我查一下xxx的最新消息」→ 调用 Search API
• 用户说「帮我看看这个网页讲了什么」→ 调用 Fetch API
• 用户说「帮我自动填写这个表单」→ 调用 Agent API

与 Hermes Agent 集成：给自主Agent装上"眼睛和手"

Hermes Agent 是由 Nous Research 开发的开源自主 AI Agent（MIT 协议）。它的核心理念是"一个能成长的Agent"——具备持久记忆、自动技能创建、多平台网关等能力。

集成方式一：通过 API Key 直接调用

export TINYFISH_API_KEY="你的TinyFish API Key"

from tinyfish import TinyFish

client = TinyFish()
results = client.search.query(query="最新AI研究进展")
content = client.fetch.get_contents(urls=["https://arxiv.org/abs/..."])

集成方式二：通过 MCP 协议
TinyFish 原生提供 MCP Server，Hermes Agent 可通过 MCP 集成以下工具：

• search — 网页搜索
• fetch_content — 网页内容提取
• run_web_automation — 多步骤网页自动化
• create_browser_session — 远程浏览器会话

集成方式三：利用 Hermes 的自动技能创建
当你首次通过 TinyFish 完成某个复杂任务后，Hermes 会自动生成 SKILL.md 记录这个能力。下次遇到类似任务直接复用——Hermes + TinyFish 的组合会越用越强。

与 MCP 兼容工具集成

一行命令即可接入 Claude、Cursor、Windsurf：

# Claude Code
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code

# Cursor
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client cursor

# Windsurf
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client windsurf

与低代码平台集成

Dify：在 Plugin Marketplace 安装 TinyFish Web Agent 插件，输入 API Key 授权即可使用。

n8n：在 Community Nodes 搜索安装 n8n-nodes-tinyfish，添加节点配置 URL 和 Goal 即可。

价格方案

注意：Search API 和 Fetch API 完全免费，只有 Agent API 和 Browser API 消耗 credits。

总结

TinyFish 的定位非常清晰：为 AI Agent 提供企业级的 Web 基础设施。

核心优势：

1. 简单 — 一个 API Key，四行代码跑通
2. 免费起步 — Search 和 Fetch 永远免费，注册送 500 credits
3. 生态丰富 — 原生支持 MCP、Python/Node SDK、CLI、Dify、n8n
4. 企业级 — 隐身浏览器、反Bot、代理、密钥管理一应俱全

无论你是想给 Claude 加上搜索能力，还是在 OpenClaw 里构建多平台 AI 助手，或是搭配 Hermes Agent 打造持续进化的自主Agent——TinyFish 都是值得认真尝试的 Web 基础设施。

🔗 官网：www.tinyfish.ai
📄 文档：docs.tinyfish.ai