Skip to main content
The Agent class is the primary entry point for the SDK. It coordinates all components required for mobile automation.

​
Responsibilities

Device Management

Initializes and manages connections to Android/iOS devices

Server Lifecycle

Starts and stops required servers (Screen API, Hardware Bridge)

Task Execution

Creates and executes automation tasks

Resource Cleanup

Handles proper cleanup and resource release

​
Basic Usage

​
Creating an Agent

​
Agent Lifecycle

1

Creation

Instantiate the agent with optional configuration
agent = Agent()
2

Initialization

Connect to device and start servers
agent.init()
3

Execution

Run automation tasks
result = await agent.run_task(goal="Your task here")
4

Cleanup

Release resources
agent.clean()

​
Configuration Options

The agent can be configured using the AgentConfigBuilder: 
from minitap.mobile_use.sdk.builders import Builders
from minitap.mobile_use.sdk.types import AgentProfile, DevicePlatform

# Create profiles
default_profile = AgentProfile(name="default", from_file="llm-config.defaults.jsonc")

# Configure the agent
config = (
    Builders.AgentConfig
    .with_default_profile(default_profile)
    .for_device(platform=DevicePlatform.ANDROID, device_id="emulator-5554")
    .build()
)

agent = Agent(config=config)

​
Initialization Options

The init() method accepts several parameters for robust initialization: 
agent.init(
    server_restart_attempts=3,  # Retry server startup if it fails
    retry_count=5,              # Number of API call retries
    retry_wait_seconds=5        # Seconds between retries
)
If you have zombie servers from previous runs, use agent.clean(force=True) before initializing.

​
Device Selection

By default, the agent connects to the first available device. You can specify a device explicitly: 
from minitap.mobile_use.sdk.types import DevicePlatform

config = (
    Builders.AgentConfig
    .for_device(
        platform=DevicePlatform.ANDROID,
        device_id="your_device_id"
    )
    .build()
)

​
Server Configuration

The agent manages two servers:
Captures screenshots and UI hierarchies
config = (
    Builders.AgentConfig
    .with_screen_api(url="http://localhost:8000")
    .build()
)
Executes device actions via Maestro
config = (
    Builders.AgentConfig
    .with_hw_bridge(url="http://localhost:8001")
    .build()
)

​
Complete Example

  • Platform
  • Local
import asyncio
from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.types import PlatformTaskRequest

async def main():
    # Create agent (uses MINITAP_API_KEY from .env)
    agent = Agent()
    
    try:
        # Initialize
        if not agent.init():
            print("Failed to initialize agent")
            return
        
        # Run platform task (configured on platform.minitap.ai)
        result = await agent.run_task(
            request=PlatformTaskRequest(task="check-notifications")
        )
        print(f"Result: {result}")
        
    except Exception as e:
        print(f"Error: {e}")
    finally:
        # Always clean up
        agent.clean()

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

​
Best Practices

Ensure agent.clean() is called even if errors occur
try:
    agent.init()
    await agent.run_task(...)
finally:
    agent.clean()
Check the return value of init()
if not agent.init():
    print("Failed to initialize")
    return
Consider wrapping in a context manager for automatic cleanup

​
Next Steps

Tasks

Learn about task creation and execution

SDK Reference

Detailed Agent SDK documentation
⌘I