Mobile Automation as Agent Tool

Beta Feature — Mobile automation is currently in beta. Please report any issues to founders@morphllm.com.

While we recommend direct execution for better control and trace access, you can also use mobile tasks as agent tools in your AI applications.

Quick Start

import Anthropic from '@anthropic-ai/sdk';
import { createMobileTool } from '@morphllm/morphsdk/tools/mobile/anthropic';

const anthropic = new Anthropic();
const { tool, execute } = createMobileTool({
  apiKey: "YOUR_API_KEY",
  defaultAppUrl: "bs://your-app-hash",
  defaultDevice: { name: "iPhone 16 Pro", version: "18" }
});

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 12000,
  tools: [tool],
  messages: [{
    role: "user",
    content: "Test the login flow in our iOS app"
  }]
});

// Handle tool calls
const toolUse = response.content.find(b => b.type === 'tool_use');
if (toolUse) {
  const result = await execute(toolUse.input);
  console.log(result.result);
  console.log('Trace:', result.trace_url);
}

import OpenAI from 'openai';
import { createMobileTool } from '@morphllm/morphsdk/tools/mobile/openai';

const openai = new OpenAI();
const { tool, execute } = createMobileTool({
  apiKey: "YOUR_API_KEY",
  defaultAppUrl: "bs://your-app-hash",
  defaultDevice: { name: "iPhone 16 Pro", version: "18" }
});

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  tools: [tool],
  messages: [{
    role: "user",
    content: "Test the login flow in our iOS app"
  }]
});

// Handle tool calls
const toolCall = response.choices[0].message.tool_calls?.[0];
if (toolCall) {
  const result = await execute(toolCall.function.arguments);
  console.log(result.result);
}

import { generateText, stepCountIs } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { createMobileTool } from '@morphllm/morphsdk/tools/mobile/vercel';

const result = await generateText({
  model: anthropic('claude-sonnet-4-5-20250929'),
  tools: {
    mobileTask: createMobileTool({
      apiKey: "YOUR_API_KEY",
      defaultAppUrl: "bs://your-app-hash"
    })
  },
  prompt: "Test the login flow in our iOS app",
  stopWhen: stepCountIs(5)
});

console.log(result.text);

Tradeoffs

Agent tools (simpler integration):

✅ Easy to add to existing agent workflows
✅ Let the LLM decide when to use mobile testing
❌ No live session monitoring
❌ Adds extra LLM call overhead
❌ Limited debugging capabilities

Direct execution (recommended):

✅ Full control over device and app configuration
✅ Access to BrowserStack session URLs
✅ GIF trace recordings
✅ Better error handling
❌ Requires explicit calls (not agent-driven)

For most use cases, we recommend direct execution for better control and debugging capabilities.

Tool Configuration

All tool adapters support the same configuration options:

import { createMobileTool } from '@morphllm/morphsdk/tools/mobile/anthropic';

const { tool, execute } = createMobileTool({
  apiKey: "YOUR_API_KEY",
  apiUrl: 'https://mobile.morphllm.com',  // Override API URL

  // Default device configuration
  defaultPlatform: 'ios',
  defaultDevice: {
    name: 'iPhone 16 Pro',
    version: '18'
  },

  // Default app (can be overridden per-call)
  defaultAppUrl: 'bs://your-app-hash',

  // Execution defaults
  defaultMaxSteps: 30,
  defaultRecordTrace: true
});

Example: Multi-tool Agent

Combine mobile automation with other tools:

import Anthropic from '@anthropic-ai/sdk';
import { createMobileTool } from '@morphllm/morphsdk/tools/mobile/anthropic';
import { createBrowserTool } from '@morphllm/morphsdk/tools/browser/anthropic';

const anthropic = new Anthropic();

const { tool: mobileTool, execute: executeMobile } = createMobileTool({
  defaultAppUrl: 'bs://your-app-hash'
});

const { tool: browserTool, execute: executeBrowser } = createBrowserTool();

const tools = [mobileTool, browserTool];

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 12000,
  tools,
  messages: [{
    role: "user",
    content: "Test the signup flow in our iOS app, then verify the web dashboard shows the new user"
  }]
});

// Handle tool calls
for (const block of response.content) {
  if (block.type === 'tool_use') {
    if (block.name === 'mobile_task') {
      const result = await executeMobile(block.input);
      console.log('Mobile result:', result.result);
    } else if (block.name === 'browser_task') {
      const result = await executeBrowser(block.input);
      console.log('Browser result:', result.result);
    }
  }
}

Tool Schema

The mobile tool accepts the following parameters:

{
  // Required
  task: string,              // Natural language task description

  // Optional - override defaults
  platform?: 'ios' | 'android',
  device_name?: string,
  platform_version?: string,
  app_url?: string,          // Override default app
  max_steps?: number,
  record_trace?: boolean
}

Formatting Results

The tool adapters return concise results suitable for agent consumption:

import { createMobileTool, formatResult } from '@morphllm/morphsdk/tools/mobile/anthropic';

const { tool, execute } = createMobileTool();

// Custom execution with full data
const fullResult = await execute(input, { returnFullResponse: true });

// Format for agent consumption
const formattedResult = formatResult(fullResult);
console.log(formattedResult); // Concise summary

// Access full data if needed
console.log('Trace:', fullResult.trace_url);
console.log('Steps:', fullResult.steps_taken);
console.log('Session:', fullResult.browserstack_session_url);

Migration from Direct Execution

If you’re currently using direct execution and want to try tools: Before (direct execution):

import { MobileClient } from '@morphllm/morphsdk/tools/mobile';

const mobile = new MobileClient({ apiKey: "YOUR_API_KEY" });

const result = await mobile.execute({
  task: "Test login flow",
  platform: "ios",
  app_url: "bs://your-app-hash",
  device_name: "iPhone 16 Pro",
  platform_version: "18"
});

After (as tool):

import { createMobileTool } from '@morphllm/morphsdk/tools/mobile/anthropic';

const { tool, execute } = createMobileTool({
  apiKey: "YOUR_API_KEY",
  defaultAppUrl: "bs://your-app-hash",
  defaultDevice: { name: "iPhone 16 Pro", version: "18" }
});

// Add to your agent's tools array
tools: [tool, /* other tools */]

// Agent will call when needed

Get Started

Models

API Reference

Integrations

Quick Start

Tradeoffs

Tool Configuration

Example: Multi-tool Agent

Tool Schema

Formatting Results

Migration from Direct Execution

See Also

​Quick Start

​Tradeoffs

​Tool Configuration

​Example: Multi-tool Agent

​Tool Schema

​Formatting Results

​Migration from Direct Execution

​See Also

Quick Start

Tradeoffs

Tool Configuration

Example: Multi-tool Agent

Tool Schema

Formatting Results

Migration from Direct Execution

See Also