> ## Documentation Index
> Fetch the complete documentation index at: https://www.minitap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Builder Pattern

> Fluent APIs for configuring agents and tasks

The mobile-use SDK provides builder classes that offer a fluent, type-safe way to configure agents and tasks. Builders make complex configurations more readable and help prevent errors.

## Why Use Builders?

<CardGroup cols={2}>
  <Card title="Readable" icon="glasses">
    Chain methods for clear, self-documenting code
  </Card>

  <Card title="Type-Safe" icon="shield-check">
    Catch configuration errors at development time
  </Card>

  <Card title="Flexible" icon="wrench">
    Easy to adjust configurations without rewriting code
  </Card>

  <Card title="Discoverable" icon="lightbulb">
    IDE autocomplete shows all available options
  </Card>
</CardGroup>

## Builders Overview

The SDK provides access to builders through the `Builders` object:

```python theme={null}
from minitap.mobile_use.sdk.builders import Builders

# Agent configuration
agent_config = Builders.AgentConfig...

# Task defaults
task_defaults = Builders.TaskDefaults...
```

## Agent Config Builder

Configure how the agent connects to devices and servers:

### Basic Usage

```python theme={null}
from minitap.mobile_use.sdk.builders import Builders
from minitap.mobile_use.sdk.types import AgentProfile

profile = AgentProfile(name="default", from_file="llm-config.defaults.jsonc")

config = (
    Builders.AgentConfig
    .with_default_profile(profile)
    .build()
)

agent = Agent(config=config)
```

### Available Methods

<AccordionGroup>
  <Accordion title="with_default_profile" icon="user">
    Set the default agent profile for tasks

    ```python theme={null}
    config = (
        Builders.AgentConfig
        .with_default_profile(profile)
        .build()
    )
    ```
  </Accordion>

  <Accordion title="add_profile / add_profiles" icon="users">
    Register additional profiles

    ```python theme={null}
    config = (
        Builders.AgentConfig
        .add_profiles([fast_profile, accurate_profile])
        .with_default_profile(fast_profile)
        .build()
    )
    ```
  </Accordion>

  <Accordion title="for_device" icon="mobile">
    Target a specific device instead of auto-detection

    ```python theme={null}
    from minitap.mobile_use.sdk.types import DevicePlatform

    config = (
        Builders.AgentConfig
        .for_device(
            platform=DevicePlatform.ANDROID,
            device_id="emulator-5554"
        )
        .build()
    )
    ```
  </Accordion>

  <Accordion title="with_adb_server" icon="server">
    Configure ADB server connection

    ```python theme={null}
    config = (
        Builders.AgentConfig
        .with_adb_server(host="localhost", port=5037)
        .build()
    )
    ```
  </Accordion>

  <Accordion title="with_default_task_config" icon="list-check">
    Set default configuration for all tasks

    ```python theme={null}
    task_defaults = (
        Builders.TaskDefaults
        .with_max_steps(500)
        .build()
    )

    config = (
        Builders.AgentConfig
        .with_default_task_config(task_defaults)
        .build()
    )
    ```
  </Accordion>
</AccordionGroup>

### Complete Example

```python theme={null}
from minitap.mobile_use.sdk.builders import Builders
from minitap.mobile_use.sdk.types import AgentProfile, DevicePlatform

# Create profiles
fast_profile = AgentProfile(name="fast", from_file="fast-config.jsonc")
accurate_profile = AgentProfile(name="accurate", from_file="accurate-config.jsonc")

# Configure task defaults
task_defaults = (
    Builders.TaskDefaults
    .with_max_steps(500)
    .build()
)

# Build comprehensive agent configuration
config = (
    Builders.AgentConfig
    .for_device(platform=DevicePlatform.ANDROID, device_id="emulator-5554")
    .add_profiles([fast_profile, accurate_profile])
    .with_default_profile(fast_profile)
    .with_adb_server(host="localhost", port=5037)
    .with_default_task_config(task_defaults)
    .build()
)

agent = Agent(config=config)
```

## Task Request Builder

Create detailed task configurations:

### Basic Usage

```python theme={null}
task = (
    agent.new_task("Open settings and check notifications")
    .with_name("check_notifications")
    .build()
)

result = await agent.run_task(request=task)
```

### Available Methods

<AccordionGroup>
  <Accordion title="with_name" icon="tag">
    Set a descriptive name for logging

    ```python theme={null}
    task = agent.new_task(goal).with_name("my_task").build()
    ```
  </Accordion>

  <Accordion title="with_max_steps" icon="list-ol">
    Limit the number of actions

    ```python theme={null}
    task = agent.new_task(goal).with_max_steps(300).build()
    ```
  </Accordion>

  <Accordion title="with_output_format" icon="file-code">
    Specify Pydantic model for output

    ```python theme={null}
    task = (
        agent.new_task(goal)
        .with_output_format(MyModel)
        .build()
    )
    ```
  </Accordion>

  <Accordion title="with_output_description" icon="message">
    Describe expected output format

    ```python theme={null}
    task = (
        agent.new_task(goal)
        .with_output_description("A comma-separated list")
        .build()
    )
    ```
  </Accordion>

  <Accordion title="using_profile" icon="user-gear">
    Use a specific agent profile

    ```python theme={null}
    task = (
        agent.new_task(goal)
        .using_profile("accurate")
        .build()
    )
    ```
  </Accordion>

  <Accordion title="with_trace_recording" icon="video">
    Enable execution tracing

    ```python theme={null}
    from pathlib import Path

    task = (
        agent.new_task(goal)
        .with_trace_recording(enabled=True, path=Path("/tmp/traces"))
        .build()
    )
    ```
  </Accordion>

  <Accordion title="with_llm_output_saving" icon="floppy-disk">
    Save final LLM output to file

    ```python theme={null}
    task = (
        agent.new_task(goal)
        .with_llm_output_saving(path="/tmp/output.json")
        .build()
    )
    ```
  </Accordion>

  <Accordion title="with_thoughts_output_saving" icon="brain">
    Save agent reasoning to file

    ```python theme={null}
    task = (
        agent.new_task(goal)
        .with_thoughts_output_saving(path="/tmp/thoughts.txt")
        .build()
    )
    ```
  </Accordion>
</AccordionGroup>

### Complete Example

```python theme={null}
from pathlib import Path
from pydantic import BaseModel, Field

class EmailSummary(BaseModel):
    total: int = Field(..., description="Total number of emails")
    unread: int = Field(..., description="Number of unread emails")

task = (
    agent.new_task("Open Gmail and analyze my inbox")
    .with_name("gmail_analysis")
    .with_max_steps(400)
    .with_output_format(EmailSummary)
    .using_profile("accurate")
    .with_trace_recording(enabled=True, path=Path("/tmp/gmail-trace"))
    .with_llm_output_saving(path="/tmp/gmail-output.json")
    .with_thoughts_output_saving(path="/tmp/gmail-thoughts.txt")
    .build()
)

result = await agent.run_task(request=task)
```

## Task Defaults Builder

Set defaults that apply to all tasks:

```python theme={null}
from minitap.mobile_use.sdk.builders import Builders

# Configure defaults
defaults = (
    Builders.TaskDefaults
    .with_max_steps(500)
    .with_trace_recording(enabled=True)
    .build()
)

# Apply to agent
config = (
    Builders.AgentConfig
    .with_default_task_config(defaults)
    .build()
)

agent = Agent(config=config)

# All tasks will inherit these defaults
await agent.run_task(goal="Any task here")
```

## Method Chaining

Builders use method chaining for fluent configuration:

```python theme={null}
# Each method returns the builder instance
result = (
    agent.new_task("My goal")
    .with_name("task_1")          # Returns TaskRequestBuilder
    .with_max_steps(300)          # Returns TaskRequestBuilder
    .with_trace_recording(True)   # Returns TaskRequestBuilder
    .build()                      # Returns TaskRequest
)
```

<Tip>
  Use parentheses and line breaks for readability when chaining many methods.
</Tip>

## Type Safety

Builders provide compile-time type checking:

```python theme={null}
from pydantic import BaseModel

class MyOutput(BaseModel):
    value: str

# Type-safe: MyOutput or None
task = agent.new_task(goal).with_output_format(MyOutput).build()
result: MyOutput | None = await agent.run_task(request=task)

# Can safely access fields
if result:
    print(result.value)  # IDE knows 'value' exists
```

## Comparison: With vs Without Builders

<Tabs>
  <Tab title="With Builders (Recommended)">
    ```python theme={null}
    task = (
        agent.new_task("Check notifications")
        .with_name("notification_check")
        .with_max_steps(200)
        .with_trace_recording(True)
        .build()
    )

    result = await agent.run_task(request=task)
    ```

    ✅ Clear and readable\
    ✅ Type-safe\
    ✅ Easy to modify
  </Tab>

  <Tab title="Without Builders">
    ```python theme={null}
    # Direct method call with many parameters
    result = await agent.run_task(
        goal="Check notifications",
        name="notification_check",
        # max_steps needs TaskRequest...
        # trace recording needs TaskRequest...
    )
    ```

    ❌ Limited options via direct call\
    ❌ Less discoverable\
    ❌ Harder to customize
  </Tab>
</Tabs>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use builders for complex configs" icon="check">
    Builders shine when you need multiple configuration options
  </Card>

  <Card title="Simple tasks can use direct calls" icon="bolt">
    For basic tasks, `agent.run_task(goal="...")` is fine
  </Card>

  <Card title="Create reusable configurations" icon="recycle">
    Build common configs once and reuse them
  </Card>

  <Card title="Leverage IDE autocomplete" icon="keyboard">
    Let your IDE suggest available builder methods
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent SDK" icon="robot" href="/docs/mobile-use-sdk/sdk-reference/agent">
    Detailed Agent SDK reference
  </Card>

  <Card title="Task Builder SDK" icon="list-check" href="/docs/mobile-use-sdk/sdk-reference/task-request-builder">
    Complete TaskRequestBuilder reference
  </Card>
</CardGroup>