This guide teaches you how to write goals that succeed on the first try. The examples are tested against real production traffic. The patterns work. Copy them, modify them, use them.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.
Quantified impact: In testing, specific goals completed 4.9x faster and returned 16x less unnecessary data compared to vague goals for the same task.
The Mental Model
Think of TinyFish Web Agent as a capable but literal-minded assistant sitting in front of a browser. What it can do:- See exactly what you would see on the screen
- Click, type, scroll, and navigate
- Wait for dynamic content to load
- Follow instructions precisely
- Return structured data
- Navigate multi-page PDFs and extract content
- Remember information across workflow steps
- Parse natural language into form fields
- Read your mind about what you meant
- Guess what to do when something unexpected happens
- Know your business context unless you tell it
- Decide on output format without explicit instructions
Match Goal Style to Task Type
Different tasks benefit from different goal-writing approaches:| Task Type | Recommended Style | Key Principle |
|---|---|---|
| Price/product extraction | Specific, constrained | List exact fields, exclude extras |
| Form filling | Natural language | Describe the person/entity, let agent map fields |
| Multi-step workflows | Numbered steps | Enable cross-step memory references |
| Batch execution | Minimal, strict schema | Only essential fields for consistency |
The Anatomy of a Great Goal
Every effective goal has up to seven components. Simple tasks may need only two or three. Complex extractions benefit from all seven.| Component | Purpose | Example |
|---|---|---|
| Objective | What to achieve | ”Extract pricing information” |
| Target | Where to focus | ”from the pricing table” |
| Fields | What data to extract | ”product name, price, availability” |
| Schema | Output structure | ”Return as JSON with keys: name, price” |
| Steps | Sequence of actions | ”Close the cookie banner first” |
| Guardrails | What NOT to do | ”Do not click purchase buttons” |
| Edge cases | Handle the unexpected | ”If price shows ‘Contact Us’, set to null” |
The Transformation Pattern
Here’s how the same task looks at three quality levels:- Vague (fails)
- Better (might work)
- Production-ready
Task-Specific Examples
- Data Extraction
- Form Filling
- Multi-Step Workflow
For extraction, be specific and constrained to prevent over-fetching:
Single Runs vs. Batch Execution
Understanding when you’re running a single task versus scaling to many is critical for goal design.Single Runs (Playground & Individual API Calls)
When you use this:- Testing and validating goals in the Playground
- One-off extractions or automations
- Prototyping before scaling
- Focus on completeness—you want rich results from this one run
- Include detailed edge case handling since you can iterate
- Add verbose output instructions for debugging
Batch Execution (Projects & Concurrent API Calls)
When you use this:- Processing hundreds or thousands of URLs
- Scheduled monitoring jobs
- Building datasets at scale
- Optimize for consistency—every run should return identical structure
- Minimize fields to only what you need
- Use strict schemas for reliable downstream processing
| Aspect | Single Run | Batch Execution |
|---|---|---|
| Field count | More fields, richer data | Minimal fields, only essentials |
| Error handling | Verbose, for debugging | Structured, for automation |
| Schema strictness | Flexible | Exact match required |
| Edge cases | Detailed instructions | Fail-fast with error flags |
| Goal length | Longer, comprehensive | Shorter, focused |
Schema Enforcement for Batch Runs
When running the same goal repeatedly, schema consistency is critical. Without explicit enforcement, the agent may return slightly different field names across runs. Best practice: Provide an example schema with exact field names AND sample values.- Field names alone can be ambiguous (
pricevs"price": "29.99"vs"price": 29.99) - Sample values clarify expected types (number vs string, boolean vs “yes/no”)
- The agent mirrors the pattern it sees
Goal Writing Tips
Specify output format
Specify output format
Tell TinyFish Web Agent how to structure the response:
Handle edge cases
Handle edge cases
Anticipate what might go wrong:
Use numbered steps for sequences
Use numbered steps for sequences
For multi-step workflows, number the steps:
Trigger cross-step memory explicitly
Trigger cross-step memory explicitly
When data from one step is needed later, tell the agent to remember it:Other phrases that work:
- “Remember these values—you’ll need them for verification”
- “Note the confirmation number displayed”
- “Save this for later”
Describe elements visually
Describe elements visually
When element IDs aren’t known, describe visually:Instead of:
Set explicit boundaries
Set explicit boundaries
Limit scope to avoid over-extraction:
Include termination conditions
Include termination conditions
Tell the agent when to stop:
Use explicit fallbacks
Use explicit fallbacks
When a page might have multiple layouts:
The Intern Test
Ask yourself: If I handed this goal to a smart but literal-minded intern who has never seen this website, would they:- Know exactly where to look first?
- Know when to stop?
- Know what to do if something unexpected happens?
- Know the exact format I want the answer in?
Ready-to-Use Templates
Copy and modify these templates for your use cases.Template A: Product Extraction
Template A: Product Extraction
Template B: Listing Extraction
Template B: Listing Extraction
Template C: Company Research
Template C: Company Research
Template D: Multi-Page Navigation
Template D: Multi-Page Navigation
Template E: Search and Filter
Template E: Search and Filter
Template F: PDF Extraction
Template F: PDF Extraction
Template G: Form with Verification
Template G: Form with Verification
Template H: Extraction with Fallbacks
Template H: Extraction with Fallbacks
Troubleshooting
Common issues and how to fix them:| Issue | Likely Cause | Solution |
|---|---|---|
| Empty results | JavaScript didn’t finish rendering | Add “Wait for [specific element] to fully load” |
| Missing fields | Data hidden until interaction | Add “Click [button] to expand” or “Scroll down first” |
| Wrong data | Goal was ambiguous | Be more specific about which section to extract from |
| Partial results | Pagination not handled | Add explicit “click Next” instructions with a limit |
| Blocked | Site has bot protection | Try browser_profile: "stealth" with proxy |
| Slow completion | Goal too vague | Add specific field constraints, reduce scope |
| Timeout | Task too complex | Break into smaller runs or add termination conditions |
Runs have a 10-minute timeout. Design goals to complete their core task well within that limit. For complex multi-step workflows, break them into smaller runs.
Observed Behaviors
TinyFish Web Agent handles common natural language variations automatically:| Input | Interpreted As |
|---|---|
| ”March 15, 1985” | 1985-03-15 |
| ”tech” | Technology |
| ”mornings” | Morning (9am-12pm) |
| “TX” | Texas |
Letter-based phone numbers like
555-WORK-123 may be converted to keypad digits (555-967-5123).Known Limitations
| Limitation | Notes |
|---|---|
| CAPTCHAs | Cannot solve reCAPTCHA or similar challenges |
| Infinite scroll | May not scroll to load all content automatically |
| Login persistence | Each run starts fresh—no session cookies carried over |
Related
AI Integration Guide
Integrate TinyFish Web Agent with your LLM
API Reference
Complete endpoint documentation
Examples
Real-world code examples
FAQ
Common questions answered