TinyAgent Tutorial: Build Your First Web Agent with TinyFish in 10 Minutes

Traditional browser automation with Playwright or Selenium requires writing selectors that break whenever a website changes its layout, managing headless Chrome instances that consume server memory, configuring proxies, and handling dynamic JavaScript-rendered content. TinyFish takes a different approach: you provide a starting URL and a plain-English goal, and a remote agent handles the browser, proxies, and JavaScript execution, returning clean JSON. This trade-off gives up some fine-grained per-step control in exchange for far less code to write and maintain, and it scales to dozens of parallel runs without building your own infrastructure. For static pages, high-volume crawling where cost per page matters, or workflows requiring precise control over every interaction, Scrapy, httpx, or Playwright may still be the better fit. TinyFish is most useful when sites are dynamic, navigation is multi-step, or you need reliable parallel execution without operating browser fleets.

Create a free account at agent.tinyfish.ai/sign-up; no credit card is required, and new accounts receive $8 in free Wallet funds. In the API Keys page, create a key and copy it immediately, since keys are displayed only once. Store the key as an environment variable. On macOS or Linux, run export TINYFISH_API_KEY="your_api_key"; in PowerShell, run $env:TINYFISH_API_KEY="your_api_key". This single setup step is enough to make your first call with curl. For a no-code option, you can also connect the TinyFish plugin in ChatGPT or Claude via OAuth and run tasks conversationally before writing any code.

Send a request to the streaming endpoint with your target URL and goal, using the -N flag so events print as they arrive. The event sequence is STARTED, then STREAMING_URL, then one or more PROGRESS events, then COMPLETE. The STREAMING_URL provides a live browser preview that remains valid for 24 hours after the run. A typical run using 3 to 5 Agent steps costs roughly $0.048 to $0.08, deducted from your Wallet balance. Use this approach to verify behavior before moving to an SDK.

For production work, use the official SDKs, which handle SSE parsing, retries, and event routing. In Python (3.8+), install the package with pip install tinyfish; on macOS, create and activate a virtual environment first to avoid the externally-managed-environment error, and invoke scripts with python3. Initialize the synchronous client, call the stream method with url and goal, and inspect the events and final result. In TypeScript or Node.js (18+), install the SDK via npm and use the equivalent streaming call; the SDK also supports callback handlers such as onStarted, onProgress, and onComplete. Both languages follow the same pattern: initialize the client, provide the URL and goal, process events, and validate the output before use.

TinyFish has two distinct failure layers, and checking only the run status is a common mistake. Infrastructure failures return status FAILED, with an error object containing a code, message, and category (SYSTEM_FAILURE, AGENT_FAILURE, BILLING_FAILURE, or UNKNOWN), sometimes with a retry_after value. Goal failures return status COMPLETED, but the result object indicates the agent could not accomplish the task, for example because an unexpected login page appeared, a product was not found, or a CAPTCHA blocked extraction. A run that only checks status === COMPLETED and prints the result can silently pass empty data downstream, which is especially costly in batch jobs. Always check both the status and the result content, and validate expected fields and values before storing or passing data onward.

Goal quality determines consistency. A vague instruction such as "Get the products" leaves the agent to choose its own structure and relevance criteria. Specific goals complete faster and return less unnecessary data; the TinyFish prompting guide reports specific goals finishing 4.9 times faster and returning 16 times less extraneous data. A production-ready goal names each field with its type, specifies null handling, defines the return format as JSON, and includes guardrails such as "Do not click purchase buttons or enter payment details." For multi-step workflows, number the steps explicitly so the agent works through them in order, and instruct it to carry data forward between steps when needed. Keep in mind that runs have an approximate five-minute timeout, so complex workflows should fit within that window or be split into smaller runs.

Use /run-sse as the default during development, since it shows every action and provides the live preview URL. The /run endpoint blocks until completion and cannot be cancelled mid-execution, so prefer /run-sse or /run-async when cancellation matters. For production batch jobs, /run-async is the cleanest choice: submit many tasks at once, receive run IDs immediately, and collect results as they complete, either by polling or through webhook notifications. The async Python client is AsyncTinyFish, and submission uses client.agent.queue(). The TinyFish Cookbook on GitHub contains complete async examples, including webhook-based patterns.

For geo-restricted sites or region-specific content, add a proxy_config object to the request with a supported country_code such as US, GB, CA, DE, FR, JP, or AU. Residential proxies are included at no additional charge on all plans. For sites with stricter automation defenses, set browser_profile to stealth instead of the default lite; the two can be combined with proxy routing when both are needed. The Infrastructure Handling Guide and Proxy documentation list full options. TinyFish also offers an MCP integration for Claude and Cursor and an n8n node for no-code workflows, letting agents and automation tools call web runs directly.

If the shell reports python or pip as not found on macOS, use python3 and pip3, since macOS does not provide the unversioned commands by default. An externally-managed-environment error means you should create and activate a virtual environment before installing. A ModuleNotFoundError for tinyfish usually indicates the SDK is not installed or the virtual environment is not active; confirm the (venv) prompt before running scripts. A 401 Unauthorized response means TINYFISH_API_KEY is missing or incorrect; verify it with echo $TINYFISH_API_KEY and confirm the key begins with sk-tinyfish- without stray spaces or quotes. For npm: command not found, install Node.js LTS from nodejs.org and restart the terminal.

New accounts receive $8 in free Wallet funds with no credit card and no subscription. Agent steps cost $0.016 each, and Browser sessions cost $0.002 per minute. Search and Fetch remain free even when the Wallet balance reaches zero, subject to rate limits of 30 Search requests and 150 fetched URLs per minute. Standard accounts support two concurrent Agent runs and five concurrent Browser sessions, with higher limits available for enterprise customers. To begin, obtain an API key at agent.tinyfish.ai, run the curl example, then move to the Python or TypeScript SDK and validate every result before relying on it in production.