> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Build with AI
> Give your AI coding assistant context on TinyFish Web Agent
Set up TinyFish Web Agent in minutes using your AI coding assistant. Just copy the prompt below, drop it into Claude, Cursor, or ChatGPT, and start building your web agent.
## Three Ways to Get Started
Let your AI assistant run web automations directly
Give your AI assistant searchable access to TinyFish docs
Paste into any AI assistant to generate custom integration code
## Automation MCP Server
Connect TinyFish as a tool in your AI assistant so it can browse websites, extract data, and complete multi-step automations on your behalf. Supports Claude Code, Claude Desktop, Cursor, and Windsurf.
See the [MCP Integration guide](/mcp-integration) for setup instructions, available tools, and troubleshooting.
***
## Docs MCP Server
Give your AI assistant searchable access to TinyFish documentation so it can look up API references, code examples, and guides while helping you build integrations.
### Quick Install
```bash theme={null}
npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client claude-code
```
Restart Claude Code for the MCP to load.
```bash theme={null}
npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client cursor
```
```bash theme={null}
npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client windsurf
```
```bash theme={null}
npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client claude
```
```bash theme={null}
claude mcp add --transport http tinyfish-docs https://docs.tinyfish.ai/mcp
```
Add to your Cursor MCP settings:
```json theme={null}
{
"mcpServers": {
"tinyfish-docs": {
"url": "https://docs.tinyfish.ai/mcp"
}
}
}
```
Add to `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows):
```json theme={null}
{
"mcpServers": {
"tinyfish-docs": {
"serverUrl": "https://docs.tinyfish.ai/mcp"
}
}
}
```
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json theme={null}
{
"mcpServers": {
"tinyfish-docs": {
"url": "https://docs.tinyfish.ai/mcp"
}
}
}
```
***
## Integration Prompt
Use this prompt to have your AI assistant generate TinyFish Web Agent integration code tailored to your project.
Copy the entire code block and paste it into Claude, ChatGPT, Cursor, or any AI coding assistant.
````
I need help integrating TinyFish Web Agent into my project. TinyFish Web Agent is a web automation API that uses natural language to control browsers - no CSS selectors or XPath needed.
**TinyFish Web Agent capabilities:**
- Navigate to websites and perform actions (clicks, form fills, scrolling)
- Extract structured data from any page as JSON
- Handle multi-step workflows with a single API call
- Work on authenticated and bot-protected sites
Please ask me these questions first:
1. What am I building?
- Data extraction / scraping
- Form automation
- Web monitoring
- AI agent with web browsing
- Something else
2. Which endpoint should I use?
- Synchronous (/run) - wait for result, simple code
- Async (/run-async) - start task, poll for result later
- Streaming (/run-sse) - real-time progress updates
3. What's my tech stack?
- TypeScript / JavaScript
- Python
- Other
4. Will I need anti-detection?
- No - standard websites
- Yes - sites with Cloudflare, CAPTCHAs, or bot protection
Then generate code using these patterns:
---
**Environment Setup**
```bash
# Get your API key at https://agent.tinyfish.ai/api-keys
# Add to .env file:
TINYFISH_API_KEY=sk-tinyfish-*****
```
---
**TypeScript - Streaming (Recommended)**
```typescript
import { TinyFish, EventType, RunStatus } from "@tiny-fish/sdk";
const client = new TinyFish(); // Reads TINYFISH_API_KEY from environment
async function runAutomation(url: string, goal: string) {
const stream = await client.agent.stream({ url, goal });
for await (const event of stream) {
if (event.type === EventType.PROGRESS) {
console.log(`Action: ${event.purpose}`);
} else if (event.type === EventType.COMPLETE) {
if (event.status === RunStatus.COMPLETED) {
return event.result;
}
throw new Error(event.error?.message || "Automation failed");
}
}
}
// Example usage
const products = await runAutomation(
"https://example.com/products",
"Extract all product names and prices as JSON"
);
```
---
**TypeScript - Synchronous**
```typescript
import { TinyFish, RunStatus } from "@tiny-fish/sdk";
const client = new TinyFish(); // Reads TINYFISH_API_KEY from environment
async function runAutomation(url: string, goal: string) {
const run = await client.agent.run({ url, goal });
if (run.status === RunStatus.COMPLETED) return run.result;
throw new Error(run.error?.message || "Automation failed");
}
```
---
**Python - Streaming**
```python
from tinyfish import TinyFish, EventType, RunStatus
client = TinyFish() # Reads TINYFISH_API_KEY from environment
def run_automation(url: str, goal: str):
with client.agent.stream(url=url, goal=goal) as stream:
for event in stream:
if event.type == EventType.PROGRESS:
print(f"Action: {event.purpose}")
elif event.type == EventType.COMPLETE:
if event.status == RunStatus.COMPLETED:
return event.result_json
raise Exception(event.error)
# Example usage
products = run_automation(
"https://example.com/products",
"Extract all product names and prices as JSON"
)
```
---
**Python - Synchronous**
```python
from tinyfish import TinyFish, RunStatus
client = TinyFish() # Reads TINYFISH_API_KEY from environment
def run_automation(url: str, goal: str):
result = client.agent.run(url=url, goal=goal)
if result.status == RunStatus.COMPLETED:
return result.result
raise Exception(result.error)
```
---
**Anti-Detection Mode**
For sites with bot protection, add stealth mode and proxy:
```typescript
import { BrowserProfile, ProxyCountryCode } from "@tiny-fish/sdk";
const run = await client.agent.run({
url: "https://protected-site.com",
goal: "Extract pricing data",
browser_profile: BrowserProfile.STEALTH,
proxy_config: {
enabled: true,
country_code: ProxyCountryCode.US, // Also: GB, CA, DE, FR, JP, AU
},
});
```
---
**Writing Good Goals**
Be specific about what you want:
```
// Good - specific output format
"Extract product name, price, and availability. Return as JSON array."
// Good - multi-step with numbered actions
"1. Click 'Load More' 3 times 2. Extract all product cards 3. Return as JSON"
// Bad - too vague
"Get the data"
```
---
**Quick Test**
```bash
curl -N -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://scrapeme.live/shop",
"goal": "Extract the first 3 product names and prices"
}'
```
---
After asking the questions, generate the appropriate code for my use case. Reference https://docs.tinyfish.ai for additional details.
````
***
## 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 Agents
When your AI generates goals for TinyFish Web Agent, follow these patterns for reliable results.
### Specify Output Schema
Pass an `output_schema` field to make TinyFish enforce a supported structured-output schema at the API level. See
[Structured Output](/key-concepts/structured-output).
```
Extract product data and return as JSON matching this structure:
{
"product_name": "string",
"price": number or null,
"in_stock": boolean
}
```
### Include Termination Conditions
```
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
```
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
```
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
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"status": "FAILED",
"error": {
"message": "Navigation timeout"
}
}
```
***
## Next Steps
Manual step-by-step setup
Write goals that work on the first try
Connect with Claude and Cursor
Full endpoint documentation