TinyFish Web Agent

Requires:

TINYFISH_API_KEY

environment variable

要求：设置

TINYFISH_API_KEY

环境变量

Pre-flight Check (REQUIRED)

预检检查（必填）

Before making any API call, always run this first to verify the key is available:

bash

[ -n "$TINYFISH_API_KEY" ] && echo "TINYFISH_API_KEY is set" || echo "TINYFISH_API_KEY is NOT set"

If the key is not set, you MUST stop and ask the user to add their API key. Do NOT fall back to other tools or approaches — the task requires TinyFish.

Tell the user:

You need a TinyFish API key. Get one at: https://agent.tinyfish.ai/api-keys

Then set it so the agent can use it:

Option 1 — Environment variable (works everywhere):
bash
export TINYFISH_API_KEY="your-key-here"
Option 2 — Claude Code settings (Claude Code only): Add to
~/.claude/settings.local.json
:
json
{
  "env": {
    "TINYFISH_API_KEY": "your-key-here"
  }
}

Do NOT proceed until the key is confirmed available.

在发起任何API调用之前，务必先运行以下命令验证密钥是否可用：

bash

[ -n "$TINYFISH_API_KEY" ] && echo "TINYFISH_API_KEY is set" || echo "TINYFISH_API_KEY is NOT set"

如果密钥未设置，你必须停止操作并要求用户添加他们的API密钥。不要改用其他工具或方法——本任务必须使用TinyFish。

请告知用户：

你需要一个TinyFish API密钥。获取地址：https://agent.tinyfish.ai/api-keys

然后按以下方式设置，以便Agent可以使用：

选项1 — 环境变量（全场景适用）：
bash
export TINYFISH_API_KEY="your-key-here"
选项2 — Claude Code设置（仅适用于Claude Code）： 添加到
~/.claude/settings.local.json
：
json
{
  "env": {
    "TINYFISH_API_KEY": "your-key-here"
  }
}

在确认密钥可用前，请勿继续操作。

Best Practices

最佳实践

Specify JSON format: Always describe the exact structure you want returned
Parallel calls: When extracting from multiple independent sites, make separate parallel calls instead of combining into one prompt

指定JSON格式：始终明确描述你想要返回的精确结构
并行调用：当从多个独立网站提取数据时，发起独立的并行调用，而非合并到同一个请求中

Basic Extract/Scrape

基础提取/爬取

Extract data from a page. Specify the JSON structure you want:

bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "goal": "Extract product info as JSON: {\"name\": str, \"price\": str, \"in_stock\": bool}"
  }'

从页面提取数据。指定你需要的JSON结构：

bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "goal": "Extract product info as JSON: {\"name\": str, \"price\": str, \"in_stock\": bool}"
  }'

Multiple Items

多条目提取

Extract lists of data with explicit structure:

bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "goal": "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]"
  }'

提取带有明确结构的数据集：

bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "goal": "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]"
  }'

Stealth Mode

隐身模式

For bot-protected sites, add

"browser_profile": "stealth"

to the request body:

bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://protected-site.com",
    "goal": "Extract product data as JSON: {\"name\": str, \"price\": str, \"description\": str}",
    "browser_profile": "stealth"
  }'

针对有反爬保护的网站，在请求体中添加

"browser_profile": "stealth"

：

bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://protected-site.com",
    "goal": "Extract product data as JSON: {\"name\": str, \"price\": str, \"description\": str}",
    "browser_profile": "stealth"
  }'

Proxy

代理设置

Route through a specific country by adding

"proxy_config"

to the body:

bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://geo-restricted-site.com",
    "goal": "Extract pricing data as JSON: {\"item\": str, \"price\": str, \"currency\": str}",
    "browser_profile": "stealth",
    "proxy_config": {"enabled": true, "country_code": "US"}
  }'

通过在请求体中添加

"proxy_config"

，指定特定国家的代理路由：

bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://geo-restricted-site.com",
    "goal": "Extract pricing data as JSON: {\"item\": str, \"price\": str, \"currency\": str}",
    "browser_profile": "stealth",
    "proxy_config": {"enabled": true, "country_code": "US"}
  }'

Output

输出结果

The SSE stream returns

data: {...}

lines. The final result is the event where

type == "COMPLETE"

and

status == "COMPLETED"

— the extracted data is in the

resultJson

field. Claude reads the raw SSE output directly; no script-side parsing is needed.

SSE流会返回

data: {...}

格式的行。最终结果是

type == "COMPLETE"

且

status == "COMPLETED"

的事件——提取的数据位于

resultJson

字段中。Claude会直接读取原始SSE输出，无需在脚本端进行解析。

Parallel Extraction

并行提取

When extracting from multiple independent sources, make separate parallel curl calls instead of combining into one prompt:

Good - Parallel calls:

bash

undefined

当从多个独立来源提取数据时，发起独立的并行curl调用，而非合并到同一个请求中：

推荐方式 - 并行调用：

bash

undefined

Compare pizza prices - run these simultaneously

对比披萨价格 - 同时运行以下命令

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse"
-H "X-API-Key: $TINYFISH_API_KEY"
-H "Content-Type: application/json"
-d '{ "url": "https://pizzahut.com", "goal": "Extract pizza prices as JSON: [{"name": str, "price": str}]" }'

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse"
-H "X-API-Key: $TINYFISH_API_KEY"
-H "Content-Type: application/json"
-d '{ "url": "https://dominos.com", "goal": "Extract pizza prices as JSON: [{"name": str, "price": str}]" }'


**Bad** - Single combined call:
```bash

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse"
-H "X-API-Key: $TINYFISH_API_KEY"
-H "Content-Type: application/json"
-d '{ "url": "https://pizzahut.com", "goal": "Extract pizza prices as JSON: [{"name": str, "price": str}]" }'

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse"
-H "X-API-Key: $TINYFISH_API_KEY"
-H "Content-Type: application/json"
-d '{ "url": "https://dominos.com", "goal": "Extract pizza prices as JSON: [{"name": str, "price": str}]" }'


**不推荐方式** - 单一合并调用：
```bash

Don't do this - less reliable and slower

请勿这样做 - 可靠性更低且速度更慢

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse"
-H "X-API-Key: $TINYFISH_API_KEY"
-H "Content-Type: application/json"
-d '{ "url": "https://pizzahut.com", "goal": "Extract prices from Pizza Hut and also go to Dominos..." }'


Each independent extraction task should be its own API call. This is faster (parallel execution) and more reliable.

curl -N -s -X POST "https://agent.tinyfish.ai/v1/automation/run-sse"
-H "X-API-Key: $TINYFISH_API_KEY"
-H "Content-Type: application/json"
-d '{ "url": "https://pizzahut.com", "goal": "Extract prices from Pizza Hut and also go to Dominos..." }'


每个独立的提取任务都应作为单独的API调用。这样速度更快（并行执行）且可靠性更高。

tinyfish

Original

Translation

TinyFish Web Agent

TinyFish Web Agent

Pre-flight Check (REQUIRED)

预检检查（必填）

Best Practices

最佳实践

Basic Extract/Scrape

基础提取/爬取

Multiple Items

多条目提取

Stealth Mode

隐身模式

Proxy

代理设置

Output

输出结果

Parallel Extraction

并行提取

Compare pizza prices - run these simultaneously

对比披萨价格 - 同时运行以下命令

Don't do this - less reliable and slower

请勿这样做 - 可靠性更低且速度更慢