# tencentqqgylab/appagent architecture

> Architecture diagram of the GitHub repository tencentqqgylab/appagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tencentqqgylab/appagent
- Repository: https://github.com/tencentqqgylab/appagent

## Overview

##### Project Type and Purpose
- AppAgent is a Python-based CLI tool/framework that turns large multimodal language models (e.g., GPT-4V or Qwen-VL) into agents capable of operating smartphone apps via ADB (Android Debug Bridge).
- It supports two phases: exploration (autonomous or human-guided) to build an app UI documentation knowledge base, and deployment to execute tasks using that knowledge.

a. CLI Entry Points
- learn.py (exploration mode)
- run.py (deployment mode)
b. Orchestration Layer (scripts/)
- self_explorer.py: autonomous UI exploration
- step_recorder.py: logs actions & screenshots
- document_generation.py: converts recorded steps into documentation artifacts
- task_executor.py: loads docs & drives the agent in deployment
- and_controller.py: issues ADB commands (screenshot, tap, swipe)
- model.py: wraps calls to GPT-4V or Qwen-VL API
- prompts.py: holds prompt templates for LLM queries
- utils.py & config.py: shared utilities, YAML config loader
c. Configuration & Assets
- config.yaml: API keys, model selection, request intervals
- assets/: stored documentation, test sets, license, teaser image
d. External Services
- OpenAI GPT-4 Vision or Alibaba Dashscope (Qwen-VL)
- Android device or emulator via ADB

##### Relationships & Data Flow
- User invokes learn.py or run.py → CLI parses config.yaml → loads orchestration modules
- Exploration Phase (learn.py):
- and_controller ↔ Device (ADB commands, screenshots)
- Screenshots + UI metadata → step_recorder → prompts + model
- LLM response → document_generation → assets/docs JSON files
- Deployment Phase (run.py):
- Load assets/docs → task_executor → prompts + model
- Model’s action plan → and_controller → Device
- step_recorder updates logs (optional)
- Throughout both phases, model.py abstracts API calls to external LLM service.

##### Architectural Patterns & Principles
- Modular layering:
- Presentation/CLI (learn.py, run.py)
- Orchestration/Business Logic (scripts/*.py)
- Service Abstraction (model wrapper, ADB controller)
- Persistence (local JSON docs in assets/)
- Separation of concerns: each script handles a single responsibility
- Extensibility point: adding new LLMs by extending scripts/model.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        learn["learn.py"]:::cli
        run["run.py"]:::cli
    end

    %% Configuration File
    yaml["config.yaml"]:::persistence

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        se["self_explorer"]:::orch
        sr["step_recorder"]:::orch
        dg["document_generation"]:::orch
        te["task_executor"]:::orch
        pr["prompts"]:::orch
        ut["utils"]:::orch
        cf["config"]:::orch
    end

    %% Service Layer
    subgraph "Service Layer"
        ac["and_controller"]:::service
        mo["model"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        assetsDir["assets/"]:::persistence
        testset["testset.md"]:::persistence
        license["license.txt"]:::persistence
    end

    %% External Services
    subgraph "External Services"
        llm["LLM Service<br/>(GPT-4V/Qwen-VL)"]:::external
        device["Android Device<br/>(via ADB)"]:::external
    end

    %% Relationships - Exploration Phase
    learn -->|parses| yaml
    run -->|parses| yaml
    yaml -->|loads| cf
    cf -->|configures| se
    cf -->|configures| te

    se -->|sends ADB commands| ac
    ac -->|executes| device
    device -->|screenshots| ac

    se -->|logs| sr
    sr -->|extracts UI metadata| pr
    pr -->|formats prompt| mo
    mo -->|API call| llm
    llm -->|response| mo
    mo -->|LLM output| dg
    dg -->|writes docs| assetsDir

    %% Relationships - Deployment Phase
    run -->|invokes| te
    assetsDir -->|loads docs| te
    te -->|uses prompts| pr
    pr -->|formats prompt| mo
    mo -->|API call| llm
    llm -->|response| mo
    te -->|issues action| ac
    ac -->|executes| device
    te -->|optional logs| sr

    %% Utility Usage
    se -.->|uses| ut
    sr -.->|uses| ut
    dg -.->|uses| ut
    te -.->|uses| ut
    pr -.->|uses| ut
    cf -.->|uses| ut

    %% Click Events
    click learn "https://github.com/tencentqqgylab/appagent/blob/main/learn.py"
    click run "https://github.com/tencentqqgylab/appagent/blob/main/run.py"
    click se "https://github.com/tencentqqgylab/appagent/blob/main/scripts/self_explorer.py"
    click sr "https://github.com/tencentqqgylab/appagent/blob/main/scripts/step_recorder.py"
    click dg "https://github.com/tencentqqgylab/appagent/blob/main/scripts/document_generation.py"
    click te "https://github.com/tencentqqgylab/appagent/blob/main/scripts/task_executor.py"
    click ac "https://github.com/tencentqqgylab/appagent/blob/main/scripts/and_controller.py"
    click mo "https://github.com/tencentqqgylab/appagent/blob/main/scripts/model.py"
    click pr "https://github.com/tencentqqgylab/appagent/blob/main/scripts/prompts.py"
    click ut "https://github.com/tencentqqgylab/appagent/blob/main/scripts/utils.py"
    click cf "https://github.com/tencentqqgylab/appagent/blob/main/scripts/config.py"
    click yaml "https://github.com/tencentqqgylab/appagent/blob/main/config.yaml"
    click assetsDir "https://github.com/tencentqqgylab/appagent/tree/main/assets/"
    click testset "https://github.com/tencentqqgylab/appagent/blob/main/assets/testset.md"
    click license "https://github.com/tencentqqgylab/appagent/blob/main/assets/license.txt"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef orch fill:#DFF2D8,stroke:#228B22,color:#228B22;
    classDef service fill:#FFF4CC,stroke:#DAA520,color:#DAA520;
    classDef persistence fill:#E0E0E0,stroke:#6A6A6A,color:#333333;
    classDef external fill:#F0D0D0,stroke:#d9534f,color:#d9534f;
```
