Skip to main content
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 CaseExample
Multi-step workflowsLogin → navigate to dashboard → extract account data
JavaScript-rendered contentSPAs, infinite scroll, lazy-loaded content
Interactive elementsClick dropdowns, dismiss modals, paginate results
Authenticated sessionsAccess content behind login walls
Bot-protected sitesCloudflare, 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"
  }
}

Goal Prompting Guide

Write goals that succeed

MCP Integration

Connect with Claude and Cursor