Agent Class

The Agent class is the primary entry point for the mobile-use SDK, responsible for managing device interaction and executing tasks.

Import

from minitap.mobile_use.sdk import Agent

Constructor

Agent(config: AgentConfig | None = None)

Parameters

AgentConfig

Custom agent configuration. If not provided, default configuration is used.

Example

from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.builders import Builders
from minitap.mobile_use.sdk.types import AgentProfile

# With default configuration
agent = Agent()

# With custom configuration
profile = AgentProfile(name="default", from_file="llm-config.defaults.jsonc")
config = Builders.AgentConfig.with_default_profile(profile).build()
agent = Agent(config=config)

Methods

init

Initialize the agent by connecting to a device and starting required servers.

async def init(
    self,
    api_key: str | None = None,
    server_restart_attempts: int = 3,
    retry_count: int = 5,
    retry_wait_seconds: int = 5,
) -> bool

Parameters

str

Minitap API key for supported API-backed integrations. Can also be set via the MINITAP_API_KEY environment variable.

int

default:3

Maximum number of attempts to start servers if they fail

int

default:5

Number of retries for API calls

int

default:5

Seconds to wait between retries

Returns

bool

True if initialization succeeded, False otherwise

Example

import asyncio

async def main():
    agent = Agent()

    # Initialize for local execution
    if not await agent.init():
        print("Failed to initialize agent")
        exit(1)

    print("Agent initialized successfully")

asyncio.run(main())

Always check the return value of init() before running tasks. Note that init() is now an async method and must be awaited.

run_task

Execute a mobile automation task asynchronously.

async def run_task(
    self,
    *,
    goal: str | None = None,
    output: type[TOutput] | str | None = None,
    profile: str | AgentProfile | None = None,
    name: str | None = None,
    request: TaskRequest[TOutput] | None = None,
) -> str | dict | TOutput | None

Parameters

str

Natural language description of what to accomplish

type[TOutput] | str

Type of output:

Pydantic model class for structured output
String description for output format

str | AgentProfile

Agent profile to use (name or instance)

str

Optional name for the task (for logging/debugging)

TaskRequest[TOutput]

Pre-built task request (alternative to individual parameters)

Returns

str | dict | TOutput | None

Task result:

str: Simple text output
dict: Unstructured dictionary
TOutput: Instance of specified Pydantic model
None: Task failed or no output

Examples

result = await agent.run_task(
    goal="Open calculator and compute 5 * 7"
)
print(result)  # String output

from pydantic import BaseModel, Field

class CalculationResult(BaseModel):
    expression: str
    result: float

result = await agent.run_task(
    goal="Calculate 123 * 456 in calculator app",
    output=CalculationResult
)

print(f"{result.expression} = {result.result}")

result = await agent.run_task(
    goal="Analyze this complex interface",
    profile="detail_oriented",
    name="ui_analysis"
)

task = (
    agent.new_task("Check notifications")
    .with_max_steps(300)
    .with_trace_recording(True)
    .build()
)

result = await agent.run_task(request=task)

new_task

Create a new task request builder for fluent task configuration.

def new_task(self, goal: str) -> TaskRequestBuilder[None]

Parameters

str

required

Natural language description of what to accomplish

Returns

TaskRequestBuilder[None]

TaskRequestBuilder instance for fluent configuration

Example

from pathlib import Path

task = (
    agent.new_task("Open Gmail and count unread emails")
    .with_name("email_count")
    .with_max_steps(400)
    .with_trace_recording(enabled=True, path=Path("/tmp/traces"))
    .build()
)

result = await agent.run_task(request=task)

clean

Clean up resources, stop servers, and reset the agent state.

async def clean(self, force: bool = False) -> None

Parameters

bool

default:false

Set to True to clean zombie/pre-existing mobile-use servers

Example

import asyncio

async def main():
    agent = Agent()

    try:
        await agent.init()
        await agent.run_task(goal="Some task")
    finally:
        await agent.clean()  # Always clean up

asyncio.run(main())

Use force=True if you have zombie servers from previous runs:

await agent.clean(force=True)  # Kill any existing servers
await agent.init()              # Start fresh

Note that clean() is now an async method and must be awaited.

install_apk

Install an APK on the connected Android device.

async def install_apk(self, apk_path: str | Path) -> None

This method uses ADB to install the APK on the connected Android device.

Parameters

str | Path

required

Path to the local APK file to install

Raises

FileNotFoundError: If the APK file does not exist
AgentNotInitializedError: If the agent is not initialized
AgentError: If the device is not an Android device or ADB client is not initialized

APK installation is only supported on Android devices. Attempting to install an APK on an iOS device will raise an AgentError.

get_screenshot

Capture a screenshot from the mobile device.

async def get_screenshot(self) -> Image.Image

This method uses ADB (Android) or xcrun (iOS) to capture screenshots from the connected device.

Returns

Image.Image

Screenshot as a PIL Image object

Raises

AgentNotInitializedError: If the agent is not initialized
Exception: If screenshot capture fails

Example

import asyncio
from minitap.mobile_use.sdk import Agent

async def main():
    agent = Agent()

    try:
        await agent.init()

        # Capture a screenshot
        screenshot = await agent.get_screenshot()

        # Save the screenshot
        screenshot.save("device_screenshot.png")
        print("Screenshot saved!")

    finally:
        await agent.clean()

asyncio.run(main())

Use get_screenshot() for debugging, monitoring, or extracting visual data from your mobile device during automation workflows.

Complete Example

import asyncio
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 WeatherInfo(BaseModel):
    temperature: float = Field(..., description="Temperature in Celsius")
    condition: str = Field(..., description="Weather condition")

async def main():
    # Configure agent
    profile = AgentProfile(name="default", from_file="llm-config.defaults.jsonc")
    config = Builders.AgentConfig.with_default_profile(profile).build()
    agent = Agent(config=config)

    try:
        # Initialize
        if not await agent.init():
            print("Failed to initialize")
            return

        # Run task with structured output
        weather = await agent.run_task(
            goal="Open weather app and check current temperature",
            output=WeatherInfo,
            name="weather_check"
        )

        if weather:
            print(f"Temperature: {weather.temperature}°C")
            print(f"Condition: {weather.condition}")

    except Exception as e:
        print(f"Error: {e}")
    finally:
        await agent.clean()

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

Exception Handling

The Agent may raise the following exceptions:

AgentNotInitializedError: Agent methods called before initialization
DeviceNotFoundError: No device found or device disconnected
AgentProfileNotFoundError: Specified profile not found
ServerStartupError: Failed to start required servers
ExecutableNotFoundError: Required executable (adb, idb, xcrun) not found
AgentTaskRequestError: Invalid task request configuration
AgentInvalidApiKeyError: Invalid Minitap API key

See Exceptions for details.

Next Steps

Task Request Builder

Configure tasks with the builder pattern

Agent Config Builder

Configure agent behavior

Overview

Quickstarts

Core Concepts

SDK Reference

Examples

Resources

Import

Constructor

Parameters

Example

Methods

init

Parameters

Returns

Example

run_task

Parameters

Returns

Examples

new_task

Parameters

Returns

Example

clean

Parameters

Example

install_apk

Parameters

Raises

get_screenshot

Returns

Raises

Example

Complete Example

Exception Handling

Next Steps

Task Request Builder

Agent Config Builder

​Import

​Constructor

​Parameters

​Example

​Methods

​init

​Parameters

​Returns

​Example

​run_task

​Parameters

​Returns

​Examples

​new_task

​Parameters

​Returns

​Example

​clean

​Parameters

​Example

​install_apk

​Parameters

​Raises

​get_screenshot

​Returns

​Raises

​Example

​Complete Example

​Exception Handling

​Next Steps

Task Request Builder

Agent Config Builder

Import

Constructor

Parameters

Example

Methods

init

Parameters

Returns

Example

run_task

Parameters

Returns

Examples

new_task

Parameters

Returns

Example

clean

Parameters

Example

install_apk

Parameters

Raises

get_screenshot

Returns

Raises

Example

Complete Example

Exception Handling

Next Steps