> ## 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.

# TaskRequestBuilder

> Fluent builder for configuring task requests

The `TaskRequestBuilder` class provides a fluent interface for configuring task requests with detailed options.

## Import

```python theme={null}
# Access through agent.new_task()
task_builder = agent.new_task("Your goal here")

# Or import directly
from minitap.mobile_use.sdk.builders import TaskRequestBuilder
```

## Creating a Builder

Use `agent.new_task()` to create a builder:

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

## Methods

### with\_name

Set a descriptive name for the task (used in logging and tracing).

```python theme={null}
def with_name(self, name: str) -> TaskRequestBuilder[TOutput]
```

<ParamField path="name" type="str" required>
  Task name for identification
</ParamField>

```python theme={null}
task = agent.new_task(goal).with_name("notification_check")
```

***

### with\_max\_steps

Set the maximum number of steps (actions) the task can take.

```python theme={null}
def with_max_steps(self, max_steps: int) -> TaskRequestBuilder[TOutput]
```

<ParamField path="max_steps" type="int" required>
  Maximum number of steps (default is 400)
</ParamField>

```python theme={null}
task = agent.new_task(goal).with_max_steps(500)
```

<Info>
  Each step corresponds to one action (tap, swipe, etc.) executed by the agent.
</Info>

***

### with\_output\_format

Specify a Pydantic model class for structured, type-safe output.

```python theme={null}
def with_output_format(
    self, 
    output_format: type[TNewOutput]
) -> TaskRequestBuilder[TNewOutput]
```

<ParamField path="output_format" type="type[BaseModel]" required>
  Pydantic model class defining the output structure
</ParamField>

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

class EmailSummary(BaseModel):
    total: int = Field(..., description="Total emails")
    unread: int = Field(..., description="Unread count")

task = (
    agent.new_task("Check my inbox")
    .with_output_format(EmailSummary)
)
```

<Tip>
  Use detailed field descriptions to help the LLM extract correct data.
</Tip>

***

### with\_output\_description

Provide a natural language description of the expected output format.

```python theme={null}
def with_output_description(self, description: str) -> TaskRequestBuilder[TOutput]
```

<ParamField path="description" type="str" required>
  Description of the expected output format
</ParamField>

```python theme={null}
task = (
    agent.new_task("List my contacts")
    .with_output_description("A comma-separated list of contact names")
)
```

***

### using\_profile

Specify which agent profile to use for this task.

```python theme={null}
def using_profile(self, profile: str | AgentProfile) -> TaskRequestBuilder[TOutput]
```

<ParamField path="profile" type="str | AgentProfile" required>
  Profile name (string) or AgentProfile instance
</ParamField>

```python theme={null}
# Using profile name
task = agent.new_task(goal).using_profile("accurate")

# Using profile instance
from minitap.mobile_use.sdk.types import AgentProfile
profile = AgentProfile(name="fast", from_file="fast.jsonc")
task = agent.new_task(goal).using_profile(profile)
```

***

### with\_trace\_recording

Enable or disable execution tracing for debugging and visualization.

```python theme={null}
def with_trace_recording(
    self, 
    enabled: bool = True, 
    path: str | Path | None = None
) -> TaskRequestBuilder[TOutput]
```

<ParamField path="enabled" type="bool" default={true}>
  Whether to enable trace recording
</ParamField>

<ParamField path="path" type="str | Path" optional>
  Directory path to save traces (defaults to temp directory)
</ParamField>

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

task = (
    agent.new_task(goal)
    .with_trace_recording(enabled=True, path=Path("/tmp/my-traces"))
)
```

<Info>
  Traces include screenshots at each step, making debugging much easier.
</Info>

***

### with\_llm\_output\_saving

Configure where to save the final LLM output.

```python theme={null}
def with_llm_output_saving(self, path: str) -> TaskRequestBuilder[TOutput]
```

<ParamField path="path" type="str" required>
  File path where LLM output will be saved (will be overwritten)
</ParamField>

```python theme={null}
task = (
    agent.new_task(goal)
    .with_llm_output_saving(path="/tmp/llm_output.json")
)
```

***

### with\_thoughts\_output\_saving

Configure where to save the agent's thought process.

```python theme={null}
def with_thoughts_output_saving(self, path: str) -> TaskRequestBuilder[TOutput]
```

<ParamField path="path" type="str" required>
  File path where agent thoughts will be saved (will be overwritten)
</ParamField>

```python theme={null}
task = (
    agent.new_task(goal)
    .with_thoughts_output_saving(path="/tmp/agent_thoughts.txt")
)
```

<Tip>
  Agent thoughts reveal the reasoning process, helpful for understanding decisions.
</Tip>

***

### without\_llm\_output\_saving

Disable LLM output saving (if it was previously enabled).

```python theme={null}
def without_llm_output_saving(self) -> TaskRequestBuilder[TOutput]
```

```python theme={null}
task = agent.new_task(goal).without_llm_output_saving()
```

***

### without\_thoughts\_output\_saving

Disable agent thoughts saving (if it was previously enabled).

```python theme={null}
def without_thoughts_output_saving(self) -> TaskRequestBuilder[TOutput]
```

```python theme={null}
task = agent.new_task(goal).without_thoughts_output_saving()
```

***

### with\_locked\_app\_package

Lock task execution to a specific app package (Android) or bundle ID (iOS).

```python theme={null}
def with_locked_app_package(self, package_name: str) -> TaskRequestBuilder[TOutput]
```

<ParamField path="package_name" type="str" required>
  The app package name (Android) or bundle ID (iOS)

  <Warning>
    Only the package name should be specified, not the full path to the app or activity name.
  </Warning>
</ParamField>

When enabled:

* Verifies the app is open before starting
* Attempts to launch the app if not in foreground
* Monitors app changes during execution
* Automatically relaunches if user accidentally leaves the app

**Android Example:**

```python theme={null}
task = agent.new_task("Send a message")
    .with_locked_app_package("com.whatsapp")
    .build()
```

**iOS Example:**

```python theme={null}
task = agent.new_task("Send a message")
    .with_locked_app_package("com.apple.MobileSMS")
    .build()
```

<Info>
  The app lock feature requires the Contextor agent to be configured in your LLM profile. See the [Tasks and Task Requests](/docs/mobile-use-sdk/core-concepts/tasks) guide for more details.
</Info>

<Tip>
  Use `adb shell pm list packages` on Android or consult iOS documentation to find the correct package/bundle ID.
</Tip>

***

### build

Build and return the final `TaskRequest` object.

```python theme={null}
def build(self) -> TaskRequest[TOutput]
```

<ResponseField name="task_request" type="TaskRequest[TOutput]">
  The constructed task request ready for execution
</ResponseField>

```python theme={null}
task_request = (
    agent.new_task("Your goal")
    .with_name("my_task")
    .build()
)

# Execute the task
result = await agent.run_task(request=task_request)
```

## Complete Example

```python theme={null}
import asyncio
from pathlib import Path
from pydantic import BaseModel, Field
from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.types import AgentProfile
from minitap.mobile_use.sdk.builders import Builders

class AppInfo(BaseModel):
    name: str = Field(..., description="App name")
    version: str = Field(..., description="App version")
    size_mb: float = Field(..., description="App size in MB")

async def main():
    # Setup agent
    profile = AgentProfile(name="default", from_file="llm-config.defaults.jsonc")
    config = Builders.AgentConfig.with_default_profile(profile).build()
    agent = Agent(config=config)
    
    try:
        agent.init()
        
        # Build comprehensive task configuration
        task = (
            agent.new_task("Go to App Store, search for Instagram, and get app details")
            .with_name("instagram_info")
            .with_max_steps(500)
            .with_output_format(AppInfo)
            .using_profile("default")
            .with_locked_app_package("com.android.vending")  # Lock to Google Play Store
            .with_trace_recording(enabled=True, path=Path("/tmp/instagram-trace"))
            .with_llm_output_saving(path="/tmp/instagram-output.json")
            .with_thoughts_output_saving(path="/tmp/instagram-thoughts.txt")
            .build()
        )
        
        # Execute
        result = await agent.run_task(request=task)
        
        if result:
            print(f"App: {result.name}")
            print(f"Version: {result.version}")
            print(f"Size: {result.size_mb} MB")
        
    finally:
        agent.clean()

if __name__ == "__main__":
    asyncio.run(main())
```

## Method Chaining

All builder methods (except `build()`) return the builder instance, allowing fluent method chaining:

```python theme={null}
task = (
    agent.new_task("Goal")
    .with_name("task_1")              # Returns TaskRequestBuilder
    .with_max_steps(400)              # Returns TaskRequestBuilder
    .with_output_format(MyModel)      # Returns TaskRequestBuilder
    .with_trace_recording(True)       # Returns TaskRequestBuilder
    .build()                          # Returns TaskRequest
)
```

## Type Safety

The builder maintains type information for output:

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

class MyOutput(BaseModel):
    value: str

# Builder knows output type
task_builder = agent.new_task(goal).with_output_format(MyOutput)

# TaskRequest is typed as TaskRequest[MyOutput]
task_request = task_builder.build()

# Result is typed as MyOutput | None
result: MyOutput | None = await agent.run_task(request=task_request)
```

## Comparison

<Tabs>
  <Tab title="With Builder">
    ```python theme={null}
    task = (
        agent.new_task("Check notifications")
        .with_name("notif_check")
        .with_max_steps(300)
        .with_trace_recording(True)
        .with_output_format(NotificationSummary)
        .build()
    )

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

    ✅ Full control over all options\
    ✅ Type-safe\
    ✅ Self-documenting
  </Tab>

  <Tab title="Direct Call">
    ```python theme={null}
    result = await agent.run_task(
        goal="Check notifications",
        name="notif_check",
        output=NotificationSummary
    )
    ```

    ✅ Simpler for basic tasks\
    ❌ Limited options available\
    ❌ Can't configure tracing, max steps, etc.
  </Tab>
</Tabs>

## Next Steps

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

  <Card title="Types" icon="shapes" href="/docs/mobile-use-sdk/sdk-reference/types">
    Explore TaskRequest and other types
  </Card>
</CardGroup>