artemis

Permita que assistentes de IA e suítes de teste usem telefones reais como um humano.

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

Demonstração ao vivo: Configure rotas no Google Maps e calcule as durações totais, depois abra o YouTube para reproduzir uma música do Coldplay.

Destaques Principais

• Automação entre Aplicativos: Executa fluxos de teste e tarefas cotidianas no Android a partir de instruções em linguagem natural.
• Segmentação Multimodal: Usa índices de elementos quando disponíveis, com fallbacks de localização por coordenadas e visual para interfaces personalizadas.
• Diagnósticos na IDE: A integração com o Model Context Protocol (MCP) permite que Antigravity, Claude Code e Windsurf controlem dispositivos de teste e coletem saída de Logcat e capturas de tela.
• Execução Flash: Um loop reativo de observar-e-agir com resumos de histórico assíncronos, tipicamente 3–5s por passo.
• Exploração Pro: Verifica os alvos antes de ações individuais e devolve ações bloqueadas ao Operator para recuperação. Suporta testes exploratórios e de estabilidade de longa duração.
• Resultados no AndroidWorld: 99%+ de conclusão de tarefas no benchmark AndroidWorld do Google Research (100+ tarefas de múltiplos passos).

Antigravity × ARTEMIS: Fluxo de Teste Autônomo

O Antigravity usa o ARTEMIS através do MCP para transformar uma solicitação de teste em um plano, execução no dispositivo e um relatório de diagnóstico:

Início Rápido

Certifique-se de que um dispositivo Android (com Depuração USB habilitada) ou emulador esteja conectado. O script de inicialização com um clique irá automaticamente:

• Instalar Toolchains do Sistema: Detectar e instalar automaticamente as dependências do ADB, scrcpy, FFmpeg e Python (uv).
• Montar o Servidor MCP Global e as Regras do Agente de IA: Solicitar a instalação automática das configurações globais do MCP e do Artemis Mobile Testing Mindset (rules.md) em suas IDEs de IA (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

O PowerShell não procura scripts executáveis no diretório atual por padrão, então use .\start.bat sem uma barra invertida no final. No Prompt de Comando (CMD), use start.bat em vez disso.

Dica: Abre http://localhost:8000 no seu navegador padrão com um assistente de conexão de dispositivo, espelhamento de tela ao vivo, sandbox de prompt e replays de execução. Você também pode executar diretamente pela 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())

Modos de Uso

_{Visão Geral do Console: ① Alternador de Visualização (Home / Workspace) · ② Modelo e Replay (status Flash/Pro e replay de vídeo) · ③ Stream do Agente ao Vivo (percepção de ação, coordenadas-alvo e resultados estruturados) · ④ Dock de Prompt (despacho em linguagem natural) · ⑤ Fila de Tarefas e Dashboard (ciclo de vida e histórico)}

• Console Visual de Teste Web (uv run artemis ui): Projeção de tela em tempo real e painel interativo, suportando despacho de testes em linguagem natural, telemetria de raciocínio ao vivo, trajetórias de ação e replay de execução; gerencie o ciclo de vida do servidor a qualquer momento de qualquer terminal usando uv run artemis restart, uv run artemis stop e uv run artemis status;
• Servidor MCP: Conecta Antigravity, Claude Code, Windsurf e outros clientes MCP a dispositivos reais para reprodução de bugs e execução de testes;
• CLI para Desenvolvedores (uv run artemis run): Execução direta pelo terminal para casos de teste automatizados, inspeção exploratória de estabilidade ou benchmarks do AndroidWorld com saída de terminal estruturada de alta fidelidade;
• SDK Python: Integra-se como uma biblioteca Python padrão em frameworks de teste automatizado existentes (por exemplo, pytest) ou pipelines de CI/CD com saídas estruturadas Pydantic fortemente tipadas e suporte a asserções.

O Que o ARTEMIS Instala no Seu Telefone

A primeira tarefa em um dispositivo instala o Artemis Accessibility Helper, um pequeno serviço de acessibilidade que lê o layout da tela sem assumir a conexão UiAutomation. Ferramentas que usam UiAutomation podem suprimir o helper a menos que habilitem FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES. Você verá uma notificação recolhida "Artemis test helper is running" e uma nova entrada em Configurações > Acessibilidade; ambas são esse helper. Ele escuta apenas no próprio telefone e não envia nada para outro lugar.

• Pré-instale-o (evita o atraso de ~3 s na primeira tarefa): uv run artemis helper install
• Inspecione-o: uv run artemis helper status / uv run artemis doctor
• Remova-o a qualquer momento: uv run artemis helper uninstall
• Use UIAutomator2 em vez disso: ARTEMIS_HIERARCHY_BACKEND=uiautomator no .env
• Impeça a instalação automática: ARTEMIS_HELPER_AUTO_INSTALL=false no .env

Se o helper falhar no meio de uma tarefa, o ARTEMIS recorre ao UIAutomator2 e informa isso na linha do tempo da tarefa, no status de mobile_manage_task e no relatório final.

Benchmarks: AndroidWorld (SOTA 99%+)

O Artemis alcançou uma taxa de conclusão de 99%+ no AndroidWorld, o benchmark do Google Research que abrange mais de 20 aplicativos e mais de 100 tarefas de múltiplos passos.

Como o ARTEMIS é Arquitetado

• Verificações Pré-Execução e Rajadas de Ações: O Pro verifica o alvo em relação à árvore de UI ao vivo e aos pixels antes de despachar uma ação individual. Rajadas de ações lidam com controles transitórios sem esperar por outro turno do modelo.
• Localização de Elementos: Combina hierarquias de acessibilidade e OCR com modelos visuais para interfaces personalizadas de Canvas, Compose e Flutter.
• Compressão de Histórico Compartilhado: Flash e Pro substituem capturas de tela mais antigas por resumos visuais e comprimem passos concluídos em blocos de histórico pesquisáveis. Limiares de contexto controlam quando os turnos brutos são substituídos.

Perfis de Execução: Flash vs. Pro

O ARTEMIS suporta dois perfis de execução adaptados para diferentes requisitos de automação:

• Perfil Flash (--profile flash): Loop reativo rápido e eficiente em tokens (~3–5s por passo): um modelo observa a tela ao vivo, pensa e age, sem orquestração de grafo. Ideal para tarefas de UI rotineiras e determinísticas. O loop é ilimitado por padrão (agent.flash.max_turns, 0 = ilimitado) porque o histórico é comprimido em vez de limitado: o Flash compartilha o registro de transcrição da sessão do Pro (relógio relativo à sessão T+mm:ss, capturas de tela dobradas em resumos visuais, passos mais antigos agrupados em eras e recuperáveis sob demanda via search_history / replay_steps) e pode consultar a gravação da sessão através do video_analyzer. UI transitória (barras de controle com desaparecimento automático, toasts) é tratada encadeando toques em um único click_sequence. Limitações: Sem plano de tarefa ou notas, sem rede de segurança pré-execução, sem verificação de checkpoint ou relatório final, e sem shell ADB.
• Perfil Pro (--profile pro): Um fluxo de trabalho de planejamento e verificação (~15–40s por passo), construído como um grafo multiagente. Um Planner mantém um plano de tarefa Markdown vivo com marcos e itens de verificação verify / assert; o o executa com o conjunto completo de ferramentas (fundamentação do Explorer cujo nível / / é uma configuração do usuário por perfil — / em ou — nunca escolhido pelo agente; notas, recuperação de histórico, análise de vídeo, diagnósticos ADB). Cada ação individual passa por uma pré-execução (XML-first, fallback por pixel), enquanto multi-ação disparam em sequência para vencer a latência de turno em UI transitória. Uma ação bloqueada ou falha abre um que permanece no contexto do Operator até que uma ação posterior tenha sucesso, então a recuperação é tratada pelo próprio Operator sem um agente de reparo separado. Um somente leitura verifica os checkpoints do plano e executa uma revisão final de saída em relação ao objetivo original (: / (padrão) / / ), e edições de marcos do plano recebem uma revisão consultiva. Lida com fluxos de trabalho de longo horizonte com 100+ passos, monitoramento e um relatório escrito opcional.

Roadmap

• Integração com o Android Studio: Plugin de IDE nativo e integração de fluxo de trabalho para permitir depuração no editor, gravação de testes e controle automatizado de dispositivos diretamente dentro do Android Studio.
• Expansão para a Plataforma iOS: Estender a percepção multimodal e a automação mobile para dispositivos e simuladores iOS.
• VLMs Leves no Dispositivo: Execução local com modelos de visão de borda leves para automação de baixa latência e com privacidade em primeiro lugar.
• Interação de Voz Duplex em Tempo Real: Despacho de tarefas por voz com controle conversacional em tempo real e tratamento de interrupções.

Comunidade e Contribuição

Contribuições são muito bem-vindas!

• Dê uma estrela no repositório para acompanhar atualizações e lançamentos
• Junte-se à Comunidade no Discord para discussões técnicas
• Abra uma Issue ou envie um Pull Request

Licença

Este projeto está licenciado sob a Apache License 2.0.

Este projeto inclui código-fonte desenvolvido pela Minitap, Inc..