Tasks and Task Requests

Tasks represent automation workflows to be executed on a mobile device. They are defined using natural language goals and can return structured, type-safe results. Define tasks directly in code with natural language goals. This keeps prompts, outputs, and review history in your codebase.

Hosted task definitions and PlatformTaskRequest execution have been removed. Migrate hosted tasks to goals and task requests defined in your codebase.

Task Characteristics

Goal-based

Define what you want using natural language

Traceable

Record execution for debugging and visualization

Structured Output

Return typed Pydantic models

Running Tasks

For local development, define tasks directly in code:

Simple String Output

The most basic way to run a local task:

result = await agent.run_task(
    goal="Open settings and enable dark mode"
)
print(result)  # String output

Structured Output with Pydantic

Get type-safe, validated output:

from pydantic import BaseModel, Field

class ThemeSettings(BaseModel):
    dark_mode_enabled: bool = Field(..., description="Whether dark mode is enabled")
    theme_name: str = Field(..., description="Name of the current theme")

result = await agent.run_task(
    goal="Check the current theme settings",
    output=ThemeSettings
)

print(f"Dark mode: {result.dark_mode_enabled}")
print(f"Theme: {result.theme_name}")

With Output Description

Provide guidance for unstructured output:

result = await agent.run_task(
    goal="Find all my unread emails",
    output="A comma-separated list of email subjects"
)

Task Options

Naming Tasks

Give your tasks descriptive names for logging:

await agent.run_task(
    goal="Send a message to John",
    name="send_message_john"
)

Using Different Profiles

Switch agent profiles for specific tasks:

await agent.run_task(
    goal="Analyze this complex form",
    profile="detail_oriented"  # Uses a different LLM configuration
)

Maximum Steps

Control how many actions the agent can take:

task = (
    agent.new_task("Complete checkout process")
    .with_max_steps(500)  # Default is 400
    .build()
)

await agent.run_task(request=task)

App Lock

Restrict task execution to a specific app:

task = (
    agent.new_task("Send a message to Alice")
    .with_locked_app_package("com.whatsapp")  # Android package or iOS bundle ID
    .build()
)

await agent.run_task(request=task)

When app lock is enabled, the agent will:

Verify the app is open before starting
Attempt to launch it if not in foreground
Monitor app changes during execution
Automatically relaunch if needed

Task Builder Pattern

For advanced configuration, use the builder pattern:

task_request = (
    agent.new_task("Open settings and check notifications")
    .with_name("check_notification_settings")
    .with_max_steps(300)
    .with_output_description("Summary of notification settings")
    .with_locked_app_package("com.android.settings")
    .with_trace_recording(enabled=True)
    .build()
)

result = await agent.run_task(request=task_request)

Tracing and Debugging

Enable trace recording to capture screenshots and execution steps:

from pathlib import Path

task = (
    agent.new_task("Navigate to profile settings")
    .with_trace_recording(
        enabled=True,
        path=Path("/tmp/my-traces")
    )
    .build()
)

await agent.run_task(request=task)

Traces include screenshots at each step, making it easy to debug failed tasks.

Saving Output

Save LLM Output

Save the final LLM response to a file:

task = (
    agent.new_task("Extract product information")
    .with_llm_output_saving(path="/tmp/llm_output.json")
    .build()
)

Save Agent Thoughts

Capture the agent’s reasoning process:

task = (
    agent.new_task("Book a restaurant reservation")
    .with_thoughts_output_saving(path="/tmp/agent_thoughts.txt")
    .build()
)

Complex Output Structures

Define complex, nested output structures:

from pydantic import BaseModel, Field
from typing import List

class Email(BaseModel):
    sender: str
    subject: str
    preview: str
    is_unread: bool

class InboxSummary(BaseModel):
    total_emails: int = Field(..., description="Total number of emails")
    unread_count: int = Field(..., description="Number of unread emails")
    emails: List[Email] = Field(..., description="List of recent emails")

result = await agent.run_task(
    goal="Open Gmail and analyze my inbox",
    output=InboxSummary
)

for email in result.emails:
    if email.is_unread:
        print(f"Unread: {email.subject} from {email.sender}")

Task Execution Flow

Goal Analysis

LLM analyzes the goal and creates a plan

Screen Observation

Agent captures current screen state

Action Decision

LLM decides next action based on goal and screen

Action Execution

Hardware bridge performs the action

Verification

Agent checks if goal is achieved

Output Extraction

If specified, extract structured output

Best Practices

Be specific in your goals

# ✅ Good - specific
goal="Open Weather app, check temperature for New York, and tell me if it will rain tomorrow"

# ❌ Bad - vague
goal="Check weather"

Use Pydantic for structured output

Define clear field descriptions to help the LLM understand what to extract

class WeatherInfo(BaseModel):
    temperature: float = Field(..., description="Current temperature in Celsius")
    will_rain_tomorrow: bool = Field(..., description="Whether rain is forecast for tomorrow")

Break complex tasks into simpler ones

Instead of one complex task, run multiple simpler tasks in sequence

# Step 1: Navigate
await agent.run_task(goal="Open banking app and go to transactions")

# Step 2: Extract data
transactions = await agent.run_task(
    goal="Get the last 5 transactions",
    output=TransactionList
)

Enable tracing for debugging

Always enable tracing when developing or debugging tasks

task = agent.new_task(goal).with_trace_recording(enabled=True).build()

Example: Multi-Step Workflow

from pydantic import BaseModel
from typing import List

class Product(BaseModel):
    name: str
    price: float
    in_stock: bool

class ShoppingResults(BaseModel):
    products: List[Product]
    total_found: int

async def shop_online():
    agent = Agent(...)  # Configure with a local profile
    agent.init()

    try:
        await agent.run_task(
            goal="Open Amazon app and search for 'bluetooth headphones'",
            name="search_products"
        )

        results = await agent.run_task(
            goal="Get the first 5 product results with names, prices, and availability",
            output=ShoppingResults,
            name="extract_products"
        )

        for product in results.products:
            if product.in_stock and product.price < 50:
                print(f"Good deal: {product.name} - ${product.price}")
    finally:
        agent.clean()

Overview

Quickstarts

Core Concepts

SDK Reference

Examples

Resources

Tasks and Task Requests

Task Characteristics

Goal-based

Traceable

Structured Output

Running Tasks

Simple String Output

Structured Output with Pydantic

With Output Description

Task Options

Naming Tasks

Using Different Profiles

Maximum Steps

App Lock

Task Builder Pattern

Tracing and Debugging

Saving Output

Save LLM Output

Save Agent Thoughts

Complex Output Structures

Task Execution Flow

Best Practices

Example: Multi-Step Workflow

Next Steps

Profiles

Task Builder SDK

​Task Characteristics

Goal-based

Traceable

Structured Output

​Running Tasks

​Simple String Output

​Structured Output with Pydantic

​With Output Description

​Task Options

​Naming Tasks

​Using Different Profiles

​Maximum Steps

​App Lock

​Task Builder Pattern

​Tracing and Debugging

​Saving Output

​Save LLM Output

​Save Agent Thoughts

​Complex Output Structures

​Task Execution Flow

​Best Practices

​Example: Multi-Step Workflow

​Next Steps

Profiles

Task Builder SDK

Task Characteristics

Running Tasks

Simple String Output

Structured Output with Pydantic

With Output Description

Task Options

Naming Tasks

Using Different Profiles

Maximum Steps

App Lock

Task Builder Pattern

Tracing and Debugging

Saving Output

Save LLM Output

Save Agent Thoughts

Complex Output Structures

Task Execution Flow

Best Practices

Example: Multi-Step Workflow

Next Steps