Skip to main content
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.
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
What it cannot do:
  • 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
Your job is to remove ambiguity. The more explicit your goal, the higher your success rate.

Match Goal Style to Task Type

Different tasks benefit from different goal-writing approaches:
Task TypeRecommended StyleKey Principle
Price/product extractionSpecific, constrainedList exact fields, exclude extras
Form fillingNatural languageDescribe the person/entity, let agent map fields
Multi-step workflowsNumbered stepsEnable cross-step memory references
Batch executionMinimal, strict schemaOnly 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.
ComponentPurposeExample
ObjectiveWhat to achieve”Extract pricing information”
TargetWhere to focus”from the pricing table”
FieldsWhat data to extract”product name, price, availability”
SchemaOutput structure”Return as JSON with keys: name, price”
StepsSequence of actions”Close the cookie banner first”
GuardrailsWhat NOT to do”Do not click purchase buttons”
Edge casesHandle the unexpected”If price shows ‘Contact Us’, set to null”

The Transformation Pattern

Here’s how the same task looks at three quality levels:
The agent doesn’t know what “pricing” means to you. Annual vs monthly? Features included? What format?

Task-Specific Examples

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
Goal design principles:
  • 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
Goal design principles:
  • Optimize for consistency—every run should return identical structure
  • Minimize fields to only what you need
  • Use strict schemas for reliable downstream processing
AspectSingle RunBatch Execution
Field countMore fields, richer dataMinimal fields, only essentials
Error handlingVerbose, for debuggingStructured, for automation
Schema strictnessFlexibleExact match required
Edge casesDetailed instructionsFail-fast with error flags
Goal lengthLonger, comprehensiveShorter, 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.
Why sample values matter:
  • Field names alone can be ambiguous (price vs "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
Anti-pattern: Return as JSON with product name, price, and availability.This might return {"name": "..."} one time and {"product_name": "..."} another.

Goal Writing Tips

Tell TinyFish Web Agent how to structure the response:
Anticipate what might go wrong:
For multi-step workflows, number the steps:
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”
When element IDs aren’t known, describe visually:
Instead of:
Limit scope to avoid over-extraction:
Tell the agent when to stop:
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?
If any answer is “they would have to guess,” add more detail.

Ready-to-Use Templates

Copy and modify these templates for your use cases.

Troubleshooting

Common issues and how to fix them:
IssueLikely CauseSolution
Empty resultsJavaScript didn’t finish renderingAdd “Wait for [specific element] to fully load”
Missing fieldsData hidden until interactionAdd “Click [button] to expand” or “Scroll down first”
Wrong dataGoal was ambiguousBe more specific about which section to extract from
Partial resultsPagination not handledAdd explicit “click Next” instructions with a limit
BlockedSite has bot protectionTry browser_profile: "stealth" with proxy
Slow completionGoal too vagueAdd specific field constraints, reduce scope
TimeoutTask too complexBreak 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:
InputInterpreted 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

LimitationNotes
CAPTCHAsCannot solve reCAPTCHA or similar challenges
Infinite scrollMay not scroll to load all content automatically
Login persistenceUse Browser Context Profiles when runs should reuse saved session state

AI Integration Guide

Integrate TinyFish Web Agent with your LLM

API Reference

Complete endpoint documentation

Examples

Real-world code examples

FAQ

Common questions answered