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

# Types

> Core types and data structures

Reference for core types and data structures used in the mobile-use SDK.

## AgentProfile

Represents a profile for the mobile-use agent with LLM configuration.

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

### Constructor

```python theme={null}
AgentProfile(
    *,
    name: str,
    llm_config: LLMConfig | None = None,
    from_file: str | None = None,
)
```

<ParamField path="name" type="str" required>
  Name of the profile
</ParamField>

<ParamField path="llm_config" type="LLMConfig" optional>
  LLM configuration for the agent
</ParamField>

<ParamField path="from_file" type="str" optional>
  Path to a file containing LLM configuration (JSONC format)
</ParamField>

<Warning>
  `llm_config` and `from_file` are mutually exclusive - use only one.
</Warning>

### Examples

```python theme={null}
# From file
profile = AgentProfile(
    name="default",
    from_file="llm-config.defaults.jsonc"
)

# Programmatic
from minitap.mobile_use.config import LLM, LLMConfig

profile = AgentProfile(
    name="custom",
    llm_config=LLMConfig(
        planner=LLM(provider="openai", model="gpt-5-nano"),
        cortex=LLM(provider="openai", model="gpt-5"),
        # ... other components
    )
)
```

***

## TaskRequest

Represents a mobile automation task request.

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

### Attributes

<ResponseField name="goal" type="str">
  Natural language description of the task goal
</ResponseField>

<ResponseField name="profile" type="str | None">
  Name of the agent profile to use
</ResponseField>

<ResponseField name="task_name" type="str | None">
  Name of the task for logging
</ResponseField>

<ResponseField name="output_description" type="str | None">
  Description of the expected output format
</ResponseField>

<ResponseField name="output_format" type="type[TOutput] | None">
  Pydantic model class for typed output
</ResponseField>

<ResponseField name="max_steps" type="int">
  Maximum number of steps the agent can take
</ResponseField>

<ResponseField name="record_trace" type="bool">
  Whether to record execution traces
</ResponseField>

<ResponseField name="trace_path" type="Path">
  Directory to save trace data
</ResponseField>

<ResponseField name="llm_output_path" type="Path | None">
  Path to save LLM outputs
</ResponseField>

<ResponseField name="thoughts_output_path" type="Path | None">
  Path to save agent thoughts
</ResponseField>

### Usage

TaskRequest objects are typically created via `TaskRequestBuilder`:

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

***

## PlatformTaskRequest

Task request for execution via the Minitap Platform.

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

<Note>
  With `PlatformTaskRequest`, you only reference a task by name. The SDK
  automatically fetches the task configuration (goal, max\_steps, output format)
  and LLM profile from the platform, then executes the task and streams
  observability data back.
</Note>

<Note>
  It also automatically upload **animated GIF traces at the end of the task** to
  cloud storage for easy viewing. See [Observability &
  Tracing](/docs/mobile-use-sdk/core-concepts/observability) for details.
</Note>

### Constructor

```python theme={null}
PlatformTaskRequest(
    task: str,
    profile: str | None = None,
    api_key: str | None = None,
    record_trace: bool = True,
    trace_path: Path = Path(tempfile.gettempdir()) / "mobile-use-traces",
    llm_output_path: Path | None = None,
    thoughts_output_path: Path | None = None,
    max_steps: int = 400
)
```

### Attributes

<ResponseField name="task" type="str">
  Name of the task configured on the Minitap Platform.

  Must exactly match a task name from [platform.mobile-use.ai/tasks](https://platform.mobile-use.ai/tasks).
</ResponseField>

<ResponseField name="profile" type="str | None">
  Name of the LLM profile to use for this task.

  If not specified, uses the Minitap-managed default profile.
</ResponseField>

<ResponseField name="api_key" type="str | None">
  API key for authentication with the Minitap Platform.

  If not provided, uses the `MINITAP_API_KEY` environment variable.
</ResponseField>

<ResponseField name="record_trace" type="bool" default={true}>
  When enabled, an animated GIF of the task execution is saved locally. In case
  of `PlatformTaskRequest`, the GIF is also uploaded to Minitap cloud storage
  for viewing in the platform.
</ResponseField>

<ResponseField name="trace_path" type="Path">
  Directory to save local trace files (steps and GIF run trajectory). Defaults
  to system temp directory.
</ResponseField>

<ResponseField name="llm_output_path" type="Path | None">
  Path to save the final LLM output locally.
</ResponseField>

<ResponseField name="thoughts_output_path" type="Path | None">
  Path to save agent thoughts/reasoning locally.
</ResponseField>

<ResponseField name="max_steps" type="int">
  Maximum number of steps (overridden by platform configuration).
</ResponseField>

<Warning>
  `PlatformTaskRequest` does **not** support `locked_app_package` as a parameter. The app lock must be configured on the platform task itself at [platform.mobile-use.ai/tasks](https://platform.mobile-use.ai/tasks).
</Warning>

### Usage

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

agent = Agent()
agent.init()

# Simple task execution
result = await agent.run_task(
    request=PlatformTaskRequest(task="check-notifications")
)

agent.clean()
```

***

## AgentConfig

Configuration for the agent.

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

Created via `AgentConfigBuilder`:

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

agent = Agent(config=config)
```

***

## DevicePlatform

Enum for device platforms.

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

# Available values
DevicePlatform.ANDROID
DevicePlatform.IOS
```

### Usage

```python theme={null}
config = (
    Builders.AgentConfig
    .for_device(platform=DevicePlatform.ANDROID, device_id="emulator-5554")
    .build()
)
```

***

## ServerConfig

Configuration for agent servers.

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

### Attributes

<ResponseField name="adb_server_host" type="str">
  ADB server host
</ResponseField>

<ResponseField name="adb_server_port" type="int">
  ADB server port
</ResponseField>

### Usage

```python theme={null}
servers = ServerConfig(
    adb_server_host="localhost",
    adb_server_port=5037
)

config = Builders.AgentConfig.with_servers(servers).build()
```

***

## LLMConfig

Configuration for LLM models used by different agent components.

```python theme={null}
from minitap.mobile_use.config import LLM, LLMConfig, LLMConfigUtils, LLMWithFallback
```

### Structure

```python theme={null}
llm_config = LLMConfig(
    planner=LLM(provider="openai", model="gpt-5-nano"),
    orchestrator=LLM(provider="openai", model="gpt-5-nano"),
    cortex=LLMWithFallback(
        provider="openai",
        model="gpt-5",
        fallback=LLM(provider="openai", model="gpt-5")
    ),
    executor=LLM(provider="openai", model="gpt-5-nano"),
    utils=LLMConfigUtils(
        hopper=LLM(provider="openai", model="gpt-5-nano"),
        outputter=LLM(provider="openai", model="gpt-5-nano")
    )
)
```

### Components

<CardGroup cols={2}>
  <Card title="planner" icon="list-check">
    Creates high-level plans from goals
  </Card>

  <Card title="orchestrator" icon="diagram-project">
    Coordinates execution steps
  </Card>

  <Card title="cortex" icon="brain">
    Visual understanding and decision-making
  </Card>

  <Card title="executor" icon="play">
    Performs specific actions
  </Card>

  <Card title="hopper" icon="forward">
    Extracts relevant information from large data batches
  </Card>

  <Card title="outputter" icon="file-export">
    Extracts structured output
  </Card>
</CardGroup>

***

## LLM

Basic LLM configuration.

```python theme={null}
from minitap.mobile_use.config import LLM

llm = LLM(provider="openai", model="gpt-5")
```

<ParamField path="provider" type="str" required>
  Provider name: `openai`, `google`, `xai`, `openrouter`
</ParamField>

<ParamField path="model" type="str" required>
  Model identifier (e.g., `gpt-5`, `gemini-2.5-flash`)
</ParamField>

***

## LLMWithFallback

LLM configuration with a fallback model.

```python theme={null}
from minitap.mobile_use.config import LLM, LLMWithFallback

llm = LLMWithFallback(
    provider="openai",
    model="o4-mini",
    fallback=LLM(provider="openai", model="gpt-5")
)
```

If the primary model fails, the fallback is used automatically.

***

## TaskRequestCommon

Common configuration shared across tasks.

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

Created via `TaskDefaults` builder:

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

## Next Steps

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

  <Card title="Exceptions" icon="triangle-exclamation" href="/docs/mobile-use-sdk/sdk-reference/exceptions">
    Error handling reference
  </Card>
</CardGroup>