artemis

Consenti agli assistenti AI e alle suite di test di usare telefoni reali come farebbe un umano.

English • 中文文档 • Workflow Showcase • Quick Start • MCP for IDEs • Benchmarks • Discord Community

Demo dal vivo: configura percorsi di guida e calcola le durate totali in Google Maps, poi apri YouTube per riprodurre una canzone dei Coldplay.

Punti Chiave

• Automazione Cross-App: Esegue flussi di test e attività quotidiane su Android a partire da istruzioni in linguaggio naturale.
• Targeting Multimodale: Usa gli indici degli elementi quando disponibili, con fallback di localizzazione tramite coordinate e visiva per interfacce personalizzate.
• Diagnostica nell'IDE: L'integrazione con il Model Context Protocol (MCP) consente a Antigravity, Claude Code e Windsurf di pilotare dispositivi di test e raccogliere output Logcat e screenshot.
• Esecuzione Flash: Un ciclo reattivo di osservazione e azione con riepiloghi asincroni della cronologia, tipicamente 3–5s per step.
• Esplorazione Pro: Verifica i target prima delle singole azioni e restituisce le azioni bloccate all'Operator per il recupero. Supporta test esplorativi e di stabilità di lunga durata.
• Risultati AndroidWorld: 99%+ di completamento delle attività sul benchmark AndroidWorld di Google Research (100+ attività multi-step).

Antigravity × ARTEMIS: Workflow di Testing Autonomo

Antigravity usa ARTEMIS tramite MCP per trasformare una richiesta di test in un piano, esecuzione sul dispositivo e un report diagnostico:

Quick Start

Assicurati che un dispositivo Android (con USB Debugging abilitato) o un emulatore sia connesso. Lo script di avvio one-click eseguirà automaticamente:

• Installazione dei Toolchain di Sistema: Rileva e installa automaticamente le dipendenze ADB, scrcpy, FFmpeg e Python (uv).
• Mount del Global MCP Server e delle Regole per gli Agenti AI: Propone di installare automaticamente le configurazioni globali MCP e la Artemis Mobile Testing Mindset (rules.md) nei tuoi IDE AI (Antigravity, Cursor, Claude Code, Codex, Windsurf, VS Code, Cline/Roo, OpenClaw).

macOS e Linux

# 1. Clone repo & navigate to directory
git clone https://github.com/google/artemis.git && cd artemis

# 2. One-click launch
./start.sh

Windows PowerShell

# 1. Clone repo & navigate to directory
git clone https://github.com/google/artemis.git
cd artemis

# 2. One-click launch
.\start.bat

PowerShell non cerca gli script eseguibili nella directory corrente per impostazione predefinita, quindi usa .\start.bat senza il backslash finale. Nel Prompt dei comandi (CMD), usa invece start.bat.

Suggerimento: Apre http://localhost:8000 nel browser predefinito con una procedura guidata di connessione al dispositivo, mirroring dello schermo in tempo reale, sandbox per i prompt e replay delle esecuzioni. Puoi anche eseguire direttamente da CLI: uv run artemis run "Open Settings, find Battery and tell me current level" --profile flash.

# Auto-install MCP server & global rules for Antigravity / Jetski:
uv run artemis mcp --install antigravity

# Or install for all supported AI IDEs (including Codex):
uv run artemis mcp --install all

uv add "artemis-client @ git+https://github.com/google/artemis.git#subdirectory=packages/artemis-client"

import asyncio
from artemis_client import ArtemisClient


async def main():
    client = ArtemisClient(
        "http://artemis-host:8000",
        device_serial="emulator-5554",  # optional: target specific device serial
        default_profile="flash",  # "flash" (fast reactive) or "pro" (deep reasoning)
    )

    result = await client.run(
        "Open System Settings, go to 'Battery', verify battery percentage is displayed, and check for any crash dialogs.",
    )

    assert result.succeeded, f"Test failed: {result.error or result.status}"
    print(f"✅ Test Passed! Device: {result.device_serial} | Trace ID: {result.trace_id}")


if __name__ == "__main__":
    asyncio.run(main())

Modalità d'Uso

_{Panoramica della Console: ① View Switcher (Home / Workspace) · ② Model & Replay (stato Flash/Pro e replay video) · ③ Live Agent Stream (percezione delle azioni, coordinate target e risultati strutturati) · ④ Prompt Dock (invio in linguaggio naturale) · ⑤ Task Queue & Dashboard (ciclo di vita e cronologia)}

• Console Web di Test Visuale (uv run artemis ui): Proiezione dello schermo in tempo reale e pannello interattivo, con supporto all'invio di test in linguaggio naturale, telemetria del ragionamento live, traiettorie delle azioni e replay delle esecuzioni; gestisci il ciclo di vita del server in qualsiasi momento da qualsiasi terminale usando uv run artemis restart, uv run artemis stop e uv run artemis status;
• MCP Server: Collega Antigravity, Claude Code, Windsurf e altri client MCP a dispositivi reali per la riproduzione di bug e l'esecuzione di test;
• CLI per Sviluppatori (uv run artemis run): Esecuzione diretta da terminale per casi di test automatizzati, ispezione esplorativa della stabilità o benchmark AndroidWorld con output strutturato ad alta fedeltà;
• Python SDK: Si integra come libreria Python standard nei framework di testing automatizzato esistenti (es. pytest) o nelle pipeline CI/CD con output strutturati Pydantic fortemente tipizzati e supporto alle asserzioni.

Cosa Installa ARTEMIS sul Tuo Telefono

La prima attività su un dispositivo installa l'Artemis Accessibility Helper, un piccolo servizio di accessibilità che legge il layout dello schermo senza occupare la connessione UiAutomation. Gli strumenti che usano UiAutomation possono sopprimere l'helper a meno che non abilitino FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES. Vedrai una notifica compressa "Artemis test helper is running" e una nuova voce sotto Impostazioni > Accessibilità; entrambe sono quell'helper. Ascolta solo sul telefono stesso e non invia nulla altrove.

• Pre-installalo (evita il ritardo di ~3 s alla prima attività): uv run artemis helper install
• Ispezionalo: uv run artemis helper status / uv run artemis doctor
• Rimuovilo in qualsiasi momento: uv run artemis helper uninstall
• Usa UIAutomator2 invece: ARTEMIS_HIERARCHY_BACKEND=uiautomator in .env
• Impedisci l'installazione automatica: ARTEMIS_HELPER_AUTO_INSTALL=false in .env

Se l'helper dovesse fallire a metà attività, ARTEMIS ripiega su UIAutomator2 e lo segnala nella timeline dell'attività, nello stato di mobile_manage_task e nel report finale.

Benchmark: AndroidWorld (SOTA 99%+)

Artemis ha raggiunto un tasso di completamento del 99%+ su AndroidWorld, il benchmark di Google Research che copre 20+ app e 100+ attività multi-step.

Come è Architettato ARTEMIS

• Controlli Pre-Esecuzione e Action Bursts: Pro verifica il target rispetto all'albero UI live e ai pixel prima di inviare una singola azione. Gli action bursts gestiscono controlli transitori senza attendere un altro turno del modello.
• Localizzazione degli Elementi: Combina gerarchie di accessibilità e OCR con modelli visivi per interfacce personalizzate Canvas, Compose e Flutter.
• Compressione della Cronologia Condivisa: Flash e Pro sostituiscono gli screenshot più vecchi con riepiloghi visivi e comprimono gli step completati in chunk di cronologia ricercabili. Le soglie di contesto controllano quando i turni grezzi vengono sostituiti.

Profili di Esecuzione: Flash vs. Pro

ARTEMIS supporta due profili di esecuzione pensati per diverse esigenze di automazione:

• Profilo Flash (--profile flash): Ciclo reattivo veloce ed efficiente in token (~3–5s per step): un modello osserva lo schermo live, ragiona e agisce, senza orchestrazione a grafo. Ideale per attività UI routinarie e deterministiche. Il ciclo è illimitato per impostazione predefinita (agent.flash.max_turns, 0 = illimitato) perché la cronologia viene compressa anziché limitata: Flash condivide il registro della trascrizione di sessione di Pro (orologio relativo alla sessione T+mm:ss, screenshot ripiegati in riepiloghi visivi, step più vecchi raggruppati in ere e richiamabili su richiesta tramite search_history / replay_steps) e può interrogare la registrazione della sessione tramite video_analyzer. La UI transitoria (barre di controllo a dissolvenza automatica, toast) viene gestita concatenando i tap in un unico click_sequence. Limitazioni: Nessun piano di attività o note, nessuna rete di sicurezza pre-esecuzione, nessuna verifica dei checkpoint o report finale, e nessuna shell ADB.
• Profilo Pro (--profile pro): Un workflow di pianificazione e verifica (~15–40s per step), costruito come grafo multi-agente. Un Planner mantiene un piano di attività Markdown vivo con milestone e voci di controllo verify / assert; l' lo esegue con il set completo di strumenti (grounding dell'Explorer il cui tier / / è un'impostazione utente per profilo — / in o — mai scelto dall'agente; note, richiamo della cronologia, analisi video, diagnostica ADB). Ogni singola azione passa attraverso una pre-esecuzione (XML-first, fallback sui pixel), mentre i multi-azione vengono lanciati consecutivamente per battere la latenza dei turni sulla UI transitoria. Un'azione bloccata o fallita apre un che rimane nel contesto dell'Operator finché un'azione successiva non riesce, così il recupero è gestito dall'Operator stesso senza un agente di riparazione separato. Un in sola lettura verifica i checkpoint del piano ed esegue una revisione finale in uscita rispetto all'obiettivo originale (: / (predefinito) / / ), e le modifiche alle milestone del piano ricevono una revisione consultiva. Gestisce workflow a lungo orizzonte di 100+ step, monitoraggio e un report scritto opzionale.

Roadmap

• Integrazione con Android Studio: Plugin IDE nativo e integrazione del workflow per abilitare il debug in-editor, la registrazione dei test e il controllo automatizzato del dispositivo direttamente in Android Studio.
• Espansione alla Piattaforma iOS: Estendere la percezione multimodale e l'automazione mobile a dispositivi e simulatori iOS.
• VLM Leggeri On-Device: Esecuzione locale con modelli di visione edge leggeri per un'automazione a bassa latenza e privacy-first.
• Interazione Vocale Duplex in Tempo Reale: Invio di attività guidato dalla voce con controllo conversazionale in tempo reale e gestione delle interruzioni.

Community e Contributi

I contributi sono calorosamente benvenuti!

• Metti una stella al repo per seguire aggiornamenti e release
• Unisciti alla Discord Community per discussioni tecniche
• Apri una Issue o invia una Pull Request

Licenza

Questo progetto è distribuito sotto la Apache License 2.0.

Questo progetto include codice sorgente sviluppato da Minitap, Inc..