Talos Agent

Python-based Android test executor service using Droidrun SDK.

Prerequisites

• Python 3.9+
• ADB (Android Debug Bridge) installed and in PATH
• Android device connected via USB or emulator running
• Gemini API key (via .env file OR provided by Talos AI at runtime)

Setup

1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\activate  # Windows

2. Install dependencies:

pip install -r requirements.txt

3. Create a .env file (optional if using Talos AI frontend):

GEMINI_API_KEY=your_gemini_api_key_here
SERVER_URL=http://localhost:3000
EXECUTOR_PORT=8000

4. Connect an Android device or start an emulator:

# List connected devices
adb devices

5. Start the executor:

./run_agent.sh

Note: We use run_agent.sh to ensure the correct Python environment (Miniconda) is used where droidrun is installed.

API Key Configuration

The executor supports two methods for configuring the Gemini API key:

Method 1: Static Configuration (.env file)

Create a .env file in the executor directory with your API key:

GEMINI_API_KEY=your_gemini_api_key_here

This key is loaded at startup and used for all executions.

Method 2: Dynamic Configuration (HTTP endpoint)

The Talos AI frontend can send the API key at runtime via the /config endpoint:

curl -X POST http://localhost:8000/config \
  -H "Content-Type: application/json" \
  -d '{"geminiApiKey": "your_api_key_here"}'

The dynamically configured key takes precedence over the .env configuration.

Configuration Priority

1. HTTP /config endpoint - Takes precedence when called
2. .env file - Used as fallback if no dynamic config is provided

API Endpoints

Configuration

Method	Endpoint	Description
POST	/config	Update API key at runtime
GET	/config/status	Check if executor is configured

Health & Device

Method	Endpoint	Description
GET	/health	Health check
GET	/device	Get connected device info
GET	/devices	List all connected devices
POST	/screenshot	Take a screenshot

Test Execution

Method	Endpoint	Description
POST	/execute	Start test execution
POST	/execute/cancel/{id}	Cancel running test
GET	/execute/status/{id}	Get execution status

How It Works

1. Talos AI frontend sends API key to executor via POST /config
2. Talos AI frontend sends test cases to the executor via POST /execute
3. Executor uses Droidrun SDK to execute each step via natural language
4. After each step, a screenshot is captured via ADB
5. Results are sent back to Talos server via POST /api/executor/step-result
6. Server compares screenshots with AI and pushes updates via SSE

Architecture

testconn-executor/
├── main.py              # FastAPI application entry point
├── config.py            # Configuration with runtime update support
├── requirements.txt     # Python dependencies
├── .env                 # Environment variables (optional)
├── .env.example         # Example environment file
├── executor/
│   ├── droidrun_agent.py    # Droidrun SDK wrapper
│   ├── browser_agent.py     # Browser automation wrapper
│   ├── step_runner.py       # Executes steps and reports results
│   ├── screenshot.py        # ADB screenshot capture
│   └── drivers/             # Platform-specific drivers
│       ├── android.py
│       ├── flutter.py
│       └── web.py
└── api/
    └── routes.py            # FastAPI route handlers

Troubleshooting

"No devices found"

• Ensure USB debugging is enabled on your device
• Check adb devices shows your device
• Try adb kill-server && adb start-server

"Droidrun not installed"

• Run pip install droidrun

"Screenshot capture failed"

• Ensure device is unlocked
• Check ADB permissions: adb shell pm grant com.android.shell android.permission.READ_FRAME_BUFFER

"API key not configured"

• Either create a .env file with GEMINI_API_KEY
• Or ensure Talos AI frontend is configured with an API key in Settings

Development

Run with auto-reload:

uvicorn main:app --reload --port 8000

Check configuration status:

curl http://localhost:8000/config/status