What is TinyAgent? AI Web Automation API

A browser script starts with instructions. TinyAgent starts with an outcome.

Your application may know that it needs three product prices, a submitted form, or a result from an authenticated dashboard. What it may not know ahead of time is every click, page transition, field, or decision required to get there.

You can write those browser steps yourself. But when the path changes depending on what the website shows next, maintaining the workflow becomes more complicated.

TinyAgent is TinyFish’s AI web automation API for multi-step website tasks. Give it a starting URL and a goal in natural language, and it determines which browser actions to take, operates the website, and returns the result.

What is TinyAgent?

TinyAgent is TinyFish’s AI web automation API for completing tasks that require navigating and interacting with websites.

Instead of specifying every browser action yourself, you provide a website URL, a natural-language goal, and, optionally, a schema describing the result your application expects.

TinyAgent works through the website toward that outcome. This can involve navigating between pages, clicking controls, filling fields, scrolling, working through pagination, and reading rendered content.

The key difference is who decides the next browser action.

With TinyBrowser, your application controls what to click, type, or inspect. With TinyAgent, you describe the result you need and delegate those decisions. The Agent API documentation describes this as goal-based automation rather than low-level browser scripting.

Key takeaway: TinyBrowser gives your code a browser. TinyAgent takes a goal and works out what the browser needs to do.

For the broader category explanation, see What is a Web Agent?.

What problem does TinyAgent solve?

Some website tasks are easy to describe but difficult to maintain as fixed scripts.

Collecting the first 20 products that match specific criteria might require opening a category, applying filters, dismissing a modal, loading more results, and visiting individual product pages. The workflow then needs to collect prices and availability, return to the results, and continue until it has enough matches.

You can encode those steps in Playwright or Puppeteer. For a stable, predictable workflow, that may be the right approach.

The difficulty appears when the path depends on the website’s current state. Pagination may become infinite scroll. One product may require an extra click before its price appears. A form may reveal another step based on an earlier answer.

The application still knows what outcome it wants, but maintaining every intermediate action becomes increasingly brittle.

TinyAgent addresses workflows where the path is dynamic, authenticated, multi-step, or unknown in advance. It is useful when the outcome is easier to specify than the interactions required to reach it.

How does TinyAgent work?

A TinyAgent workflow has four parts: a starting URL, a goal, the browser actions needed to pursue it, and a result your application can inspect.

1. Give TinyAgent a URL and a goal

The URL tells TinyAgent where to begin. The goal describes what the completed task should produce.

Starting URL: https://scrapeme.live/shop

Goal: “Extract the first 2 product names and prices.”

You do not have to translate that goal into a sequence such as:

Find product card
Open product
Read price
Go back
Find next card
Repeat

The API uses url and goal as the core inputs for a run. Your application supplies the task rather than every intermediate browser command.

This small, read-only task demonstrates the input format. For a production workflow, use TinyFetch when retrieving the page content alone would complete the job.

2. TinyAgent decides the browser actions

Once the run starts, TinyAgent interprets the goal and determines what needs to happen on the website.

It may navigate to another page, click a button, fill a text field, select a dropdown option, check a box, or scroll through additional results. As the page changes, it can adjust the next action.

Your application does not need to supply a locator, such as a CSS selector or XPath expression, for every element involved in the workflow. TinyAgent operates at the task level rather than requiring a sequence of individual browser commands.

3. TinyAgent works through the website

The agent continues observing the page and choosing actions that move it toward the requested result. A simple task may require only a few interactions; a more involved workflow may span several screens.

Form filling illustrates the difference. TinyAgent can read the fields as they appear, enter supplied values, select options, and work through a multi-step form. For an authorized submission, it can then inspect the website’s confirmation.

See Fill Out Web Forms Automatically with TinyAgent for a dedicated example.

4. TinyAgent returns the result

A synchronous response includes the run status and task output within a response object. The task data is not the entire API response.

An illustrative result for a two-product task could look like this. These names and prices are placeholders, not output from a recorded run:

{
  "products": [
    {
      "name": "Product A",
      "price": "$49"
    },
    {
      "name": "Product B",
      "price": "$59"
    }
  ]
}

When your application requires particular fields and types, provide an output_schema using TinyFish’s supported structured-output format. Asking the agent to “return JSON” does not define the same output contract.

The schema must use a top-level object. A list of products, for example, belongs inside an array field such as products. Your application should still validate the returned values before using them.

What does TinyAgent take and return?

TinyAgent does more than generate a text response: it operates a website and returns information about the resulting run.

The main inputs and outputs are:

You do not need to configure every option for a simple task. Start with the URL and goal, then add the settings your workflow requires.

Browser Context Profiles are different from Browser Profiles. Context profiles preserve browser state between runs. Browser Profiles select runtime modes through browser_profile, such as lite or stealth.

A completed run is not always a successful goal

A browser workflow can finish without achieving the result you requested.

For example, TinyAgent might open a website and inspect the available pages but discover that the requested product no longer exists. The browser executed the task, but the application did not receive the product information it needed.

That differs from an execution failure, such as a browser crash or a page that could not load. A run can report COMPLETED while its result indicates that the requested goal was not achieved.

Check the result as well as the run status before treating a task as successful.

For a product-extraction task, that means checking the requested item count, required fields, and returned values. For a form submission, it means checking the confirmation—not assuming that the final click proves success.

This distinction matters when TinyAgent results trigger downstream actions automatically.

What can you use TinyAgent for?

TinyAgent is most useful when a website needs to be operated, not simply searched or read. Its use cases include interactive data collection, form filling, and authorized work inside logged-in websites.

Work through paginated or interactive data

Some data becomes available only after interaction. A catalog might require selecting a category, applying filters, moving through pagination, expanding results, or opening individual records.

TinyAgent can include those actions in the task rather than requiring your application to script each one separately. The goal should still define what qualifies as a match and how many results are needed.

Fill and submit web forms

Reading a form tells you what is on the page. Completing it requires actions.

TinyAgent can work through text fields, dropdowns, checkboxes, validation, and multi-step forms when the workflow is authorized.

For testing, use a sandbox or ask the agent to stop before submission. Before allowing production changes, define which actions are permitted and what confirmation counts as success. If a run is interrupted, check whether the form was already submitted before retrying.

Work through authenticated workflows

An authorized workflow may need to enter a vendor portal, open an account dashboard, navigate to a report, or complete an approved action.

Browser Context Profiles let recurring TinyAgent runs reuse a saved login. Create the profile, sign in through its setup session, and save the browser state before attaching it to later runs.

Vault provides a separate credential-based recovery path when that saved session expires. Websites can still require additional verification or a fresh login, so test the authentication lifecycle on the target site rather than assuming a saved profile will always remain valid.

Extract data that requires interaction first

If the information is already available on a known webpage, TinyFetch may be enough.

TinyAgent becomes useful when reaching the answer requires an action first: navigating to a record, applying a filter, opening a panel, loading more results, or choosing which page to inspect next.

The distinction is not simply whether you want structured data. It is whether collecting that data requires operating the website. Using an agent for straightforward page retrieval adds complexity you may not need.

When should you use goal-based automation instead of a browser script?

TinyAgent is not automatically the right choice for every browser task. The useful question is who should decide the next action: your application or the agent?

Use TinyAgent when the outcome is clear but the steps may vary

Use TinyAgent when you can define the result but the route depends on what the website shows—for example, a form that reveals different fields based on an earlier answer.

The goal gives the workflow a destination without requiring your application to anticipate every intermediate interaction.

Use a browser script when the steps are predictable

A workflow that always opens the same URL, clicks a known button, fills specified fields, and captures a particular value may be easier to control directly with Playwright or Puppeteer.

In that case, TinyBrowser can provide the managed Chromium infrastructure while your application controls the actions. That controller can be your existing automation code; it does not need to be replaced with TinyAgent.

Use TinyFetch when interaction is unnecessary

When you already know the URL and only need the page content, start with TinyFetch.

There is no need to introduce an agent when page retrieval completes the job. Use TinySearch when the problem is discovery

When you do not know which webpage contains the information, start with TinySearch.

Search finds relevant sources. TinyAgent becomes relevant when the next task requires interacting with those websites rather than simply finding or reading them.

Pro tip: Start with the smallest tool that completes the job. Use TinyAgent because the task requires decisions and interaction, not simply because a website is involved.

TinyAgent vs. TinySearch vs. TinyFetch vs. TinyBrowser

TinyFish separates web workflows into different products so developers can choose the level of automation each task needs.

The distinction is straightforward: TinySearch finds the page, TinyFetch reads it, TinyBrowser gives your application browser control, and TinyAgent handles the delegated task.

How much does TinyAgent cost?

TinyAgent costs $0.016 per agent step, billed against your prepaid TinyFish Wallet. There is no recurring subscription or monthly minimum.

Standard accounts support two concurrent runs, with higher limits available by arrangement.

A step is a tool-call action during the run, such as navigating, clicking, typing, scrolling, or extracting information. Total usage depends on how many steps the task requires, so a short extraction and a multi-page workflow can have different costs.

See the TinyFish pricing page for current rates, Wallet billing, and concurrency limits.

How to get started with TinyAgent

Begin with a small, read-only task whose result you can verify.

1. Create a TinyFish account and API key.
2. Choose the website where the task should begin.
3. Write a specific natural-language goal.
4. Choose how your application should receive progress and results.
5. Start the run.
6. Check the returned result and run status.

For a single task, TinyFish provides synchronous requests, asynchronous runs, and Server-Sent Events (SSE) streaming:

• POST /v1/automation/run waits for the final response.
• POST /v1/automation/run-async returns a run ID for later status checks.
• POST /v1/automation/run-sse streams progress events and the final outcome.

Install the Python SDK and configure your API key

The example below requires Python 3.11 or later and the official TinyFish Python SDK.

Install the package and set your API key in the environment before running the script. The client reads TINYFISH_API_KEY when no key is supplied directly. Keep the key out of source code and version control.

For a macOS or Linux terminal:

python -m pip install --upgrade tinyfish
export TINYFISH_API_KEY="replace-with-your-api-key"

Run a small streaming task

Save the following code as tinyagent_example.py:

from tinyfish import TinyFish

# Reads TINYFISH_API_KEY from your environment.
client = TinyFish()

with client.agent.stream(
    url="https://scrapeme.live/shop",
    goal="Extract the first 2 product names and prices. Return JSON.",
) as stream:
    for event in stream:
        print(event)

Run it from the same terminal where you set the API key:

python tinyagent_example.py

This example prints the stream events so you can inspect the run. It is a minimal demonstration, not a complete production result handler.

In an application, save the run ID, handle the final COMPLETE event, and check its status and returned data before using the result. The Python SDK exposes that event’s task output as result_json. If the connection drops after you receive a run ID, look up the existing run before starting another.

For this task, verify that the output contains two products with names and prices. A completed run or valid JSON alone does not establish that the requested information is correct.

For a more detailed walkthrough, see TinyAgent Tutorial: Build Your First Agent.

Give TinyAgent the outcome

TinyAgent is useful when you can describe what needs to happen more easily than you can script every browser step required to make it happen.

Start with a specific goal and a task you can verify. Define the expected result, keep the first run read-only, and inspect what came back before connecting the workflow to downstream actions.

Give TinyAgent the URL and the goal - Try TinyAgent in the Playground

Related reading

• What Is a Web Agent? How AI Browser Agents Work
• TinyAgent Tutorial: Build Your First Agent
• What Is TinyBrowser? Managed Browser Infrastructure for AI Agents
• What is TinySearch?
• What is TinyFetch?