AI Integration Guide

Add TinyFish Web Agent as a tool for your AI agent or LLM application

This guide helps you integrate TinyFish Web Agent as a tool in AI agents, chatbots, and LLM-powered applications.

For AI agents: A machine-readable capability reference is available at /skills.md.

---

When to Use TinyFish Web Agent

TinyFish Web Agent excels at tasks that require a real browser with full JavaScript execution.

Use Case	Example
Multi-step workflows	Login → navigate to dashboard → extract account data
JavaScript-rendered content	SPAs, infinite scroll, lazy-loaded content
Interactive elements	Click dropdowns, dismiss modals, paginate results
Authenticated sessions	Access content behind login walls
Bot-protected sites	Cloudflare, DataDome protected pages

---

Writing Goals for AI

When your AI generates goals for TinyFish Web Agent, follow these patterns for reliable results.

Specify Output Schema

Define the exact JSON structure you want returned. This helps TinyFish Web Agent format data consistently.

Extract product data and return as JSON matching this structure:
{
  "product_name": "string",
  "price": number or null,
  "in_stock": boolean
}

Include Termination Conditions

Prevent infinite loops by specifying when the automation should stop.

Stop when ANY of these is true:
- You have extracted 20 items
- No more "Load More" button exists
- You have processed 5 pages
- The page shows a login prompt

Handle Edge Cases

Tell TinyFish Web Agent how to handle unexpected states like missing data or blocked access.

If price shows "Contact Us" or "Request Quote":
  Set price to null
  Set price_type to "contact_required"

If a CAPTCHA appears:
  Stop immediately
  Return partial results with an error flag

Request Structured Errors

Ask for error details in a parseable format so your agent can decide what to do next.

If extraction fails, return:
{
  "success": false,
  "error_type": "timeout" or "blocked" or "not_found",
  "error_message": "Description of what went wrong",
  "partial_results": [any data captured before failure]
}

---

Parsing Results

When your AI receives results from TinyFish Web Agent, handle both success and failure cases.

Success Response

The automation completed and the goal was achieved.

{
  "status": "COMPLETED",
  "result": {
    "products": [
      { "name": "Widget", "price": 29.99, "in_stock": true }
    ]
  }
}

Goal Failure

The browser worked, but the goal wasn’t achieved. Try a different approach or inform the user.

{
  "status": "COMPLETED",
  "result": {
    "success": false,
    "error_type": "not_found",
    "error_message": "No products found on this page"
  }
}

Infrastructure Failure

The browser itself failed. Retry with stealth mode or a proxy.

{
  "status": "FAILED",
  "error": {
    "message": "Navigation timeout"
  }
}

---

Related

Goal Prompting Guide

Write goals that succeed

MCP Integration

Connect with Claude and Cursor