> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morphllm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Automation as Agent Tool

> Use mobile app automation as a tool in your AI agents

<Warning>
  **Beta Feature** — Mobile automation is currently in beta. Please report any issues to [founders@morphllm.com](mailto:founders@morphllm.com).
</Warning>

While we recommend [direct execution](/sdk/components/mobile/direct) for better control and trace access, you can also use mobile tasks as agent tools in your AI applications.

## Quick Start

<CodeGroup>
  ```typescript Anthropic theme={null}
  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);
  }
  ```

  ```typescript OpenAI theme={null}
  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);
  }
  ```

  ```typescript Vercel AI SDK theme={null}
  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);
  ```
</CodeGroup>

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

<Tip>
  For most use cases, we recommend [direct execution](/sdk/components/mobile/direct) for better control and debugging capabilities.
</Tip>

## Tool Configuration

All tool adapters support the same configuration options:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
{
  // 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:

```typescript theme={null}
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)**:

```typescript theme={null}
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)**:

```typescript theme={null}
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
```

## See Also

* [Direct Execution](/sdk/components/mobile/direct) - Recommended for most use cases
* [Browser Tool](/sdk/components/browser/tool) - Web automation as agent tool