The Agent class is the primary entry point for the mobile-use SDK, responsible for managing device interaction and executing tasks.
from minitap.mobile_use.sdk import Agent
Constructor
Agent(config: AgentConfig | None = None)
Parameters
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
Initialize the agent by connecting to a device and starting required servers.
def init(
self,
server_restart_attempts: int = 3,
retry_count: int = 5,
retry_wait_seconds: int = 5,
) -> bool
Parameters
Maximum number of attempts to start servers if they fail
Number of retries for API calls
Seconds to wait between retries
Returns
True if initialization succeeded, False otherwise
Example
agent = Agent()
if not agent.init():
print("Failed to initialize agent")
exit(1)
print("Agent initialized successfully")
Always check the return value of init() before running tasks.
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] | PlatformTaskRequest[TOutput] | None = None,
) -> str | dict | TOutput | None
Parameters
Natural language description of what to accomplish
Type of output:
- Pydantic model class for structured output
- String description for output format
Agent profile to use (name or instance)
Optional name for the task (for logging/debugging)
request
TaskRequest[TOutput] | PlatformTaskRequest[TOutput]
Pre-built TaskRequest or PlatformTaskRequest (alternative to individual parameters)
Returns
result
str | dict | TOutput | None
Task result:
str: Simple text outputdict: Unstructured dictionaryTOutput: Instance of specified Pydantic modelNone: Task failed or no output
Examples
result = await agent.run_task(
goal="Open calculator and compute 5 * 7"
)
print(result) # String output
new_task
Create a new task request builder for fluent task configuration.
def new_task(self, goal: str) -> TaskRequestBuilder[None]
Parameters
Natural language description of what to accomplish
Returns
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 up resources, stop servers, and reset the agent state.
def clean(self, force: bool = False) -> None
Parameters
Set to True to clean zombie/pre-existing mobile-use servers
Example
agent = Agent()
try:
agent.init()
await agent.run_task(goal="Some task")
finally:
agent.clean() # Always clean up
Use force=True if you have zombie servers from previous runs:agent.clean(force=True) # Kill any existing servers
agent.init() # Start fresh
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 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:
agent.clean()
if __name__ == "__main__":
asyncio.run(main())
Exception Handling
The Agent may raise the following exceptions:
AgentNotInitializedError: Agent methods called before initializationDeviceNotFoundError: No device found or device disconnectedAgentProfileNotFoundError: Specified profile not foundServerStartupError: Failed to start required serversExecutableNotFoundError: Required executable (adb, maestro, xcrun) not foundAgentTaskRequestError: Invalid task request configurationPlatformServiceUninitializedError: Platform service not initialized (missing API key)AgentInvalidApiKeyError: Invalid Minitap API key
See Exceptions for details.
Next Steps
