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

# Python

> Control Android phones from Python

## Full example

```python theme={null}
import requests
import time

API = "https://agentcell.live/api"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1. Create session
session = requests.post(f"{API}/sessions", headers=H, json={}).json()
sid = session["id"]
print(f"Session {sid} — {session['status']}")

# 2. Wait for boot
while True:
    s = requests.get(f"{API}/sessions/{sid}", headers=H).json()
    if s["status"] == "ready":
        print("Phone is ready!")
        break
    if s["status"] == "failed":
        raise Exception(s.get("error_message", "boot failed"))
    print(f"  status: {s['status']}...")
    time.sleep(2)

# 3. Run a task
result = requests.post(
    f"{API}/sessions/{sid}/agent/task",
    headers=H,
    json={"task": "Search DuckDuckGo for the weather in Tokyo"},
).json()

print(f"Status: {result['status']}")
print(f"Summary: {result['summary']}")
print(f"Steps: {len(result['steps'])}")

# 4. Run another task on the same phone
result2 = requests.post(
    f"{API}/sessions/{sid}/agent/task",
    headers=H,
    json={"task": "Open Settings and check the Wi-Fi status"},
).json()

print(f"Status: {result2['status']}")
print(f"Summary: {result2['summary']}")

# 5. Clean up
requests.delete(f"{API}/sessions/{sid}", headers=H)
print("Session deleted")
```

## Task options

The `/agent/task` endpoint accepts:

```python theme={null}
{
    "task": "what you want the agent to do",
    "max_steps": 20  # optional, 1-200, default 20
}
```

* **task** — plain English instruction for the AI agent
* **max\_steps** — maximum number of actions the agent can take before giving up

## Response format

```python theme={null}
{
    "status": "completed",  # or "failed"
    "summary": "Successfully opened Settings and turned on Wi-Fi",
    "steps": [
        {"tool": "open_app", "args": {"package": "com.android.settings"}, "ok": true},
        {"tool": "click", "args": {"index": 5}, "ok": true},
        ...
    ]
}
```

## Error handling

```python theme={null}
result = requests.post(f"{API}/sessions/{sid}/agent/task", headers=H, json={
    "task": "Do something"
})

if result.status_code == 402:
    print("Trial expired or session limit reached")
elif result.status_code == 409:
    print("Session not ready yet")
elif result.status_code == 404:
    print("Session not found")
else:
    data = result.json()
    if data["status"] == "failed":
        print(f"Agent failed: {data['summary']}")
```

## Tips

* **DuckDuckGo over Google** — Google blocks cloud IPs with reCAPTCHA. Use DuckDuckGo for web searches.
* **One task at a time** — each session runs one agent task at a time. Wait for completion before sending the next.
* **Fresh sessions** — each session starts as a clean Android install. Apps and state don't persist between sessions.