|
| 1 | +# 🔨 AgentStudio |
| 2 | + |
| 3 | +<div align="center"> |
| 4 | + <a href="README.md"><b>English</b></a> | <a href="README_KR.md"><b>한국어</b></a> |
| 5 | +</div> |
| 6 | + |
| 7 | +<div align="center"> |
| 8 | +<a href="https://pseudo-lab.com"><img src="https://img.shields.io/badge/PseudoLab-S11-3776AB" alt="PseudoLab"/></a> |
| 9 | +<a href="https://discord.gg/EPurkHVtp2"><img src="https://img.shields.io/badge/Discord-BF40BF" alt="Discord Community"/></a> |
| 10 | +<a href="https://github.com/Pseudo-Lab/Agent_Studio/stargazers"><img src="https://img.shields.io/github/stars/Pseudo-Lab/Agent_Studio" alt="Stars Badge"/></a> |
| 11 | +<a href="https://github.com/Pseudo-Lab/Agent_Studio/network/members"><img src="https://img.shields.io/github/forks/Pseudo-Lab/Agent_Studio" alt="Forks Badge"/></a> |
| 12 | +<a href="https://github.com/Pseudo-Lab/Agent_Studio/pulls"><img src="https://img.shields.io/github/issues-pr/Pseudo-Lab/Agent_Studio" alt="Pull Requests Badge"/></a> |
| 13 | +<a href="https://github.com/Pseudo-Lab/Agent_Studio/issues"><img src="https://img.shields.io/github/issues/Pseudo-Lab/Agent_Studio" alt="Issues Badge"/></a> |
| 14 | +<a href="https://github.com/Pseudo-Lab/Agent_Studio/graphs/contributors"><img alt="GitHub contributors" src="https://img.shields.io/github/contributors/Pseudo-Lab/Agent_Studio?color=2b9348"></a> |
| 15 | +<a href="https://hits.seeyoufarm.com"><img src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2Fpseudo-lab%2FAgent_Studio&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false"/></a> |
| 16 | +</div> |
| 17 | +<br> |
| 18 | + |
| 19 | +> 🔨 **AgentStudio** - 가짜연구소 11기 AI Agent 프로젝트 |
| 20 | +> "AI로 세대간의 지식격차를 줄이고, 선한 영향력을 나누자" |
| 21 | +
|
| 22 | +--- |
| 23 | + |
| 24 | +## 🤖 키오스크 에이전트 (Kiosk Agent) |
| 25 | + |
| 26 | +> **Vision-Language-Action (VLA) 패러다임 기반 키오스크 자동 제어 에이전트** |
| 27 | +
|
| 28 | +키오스크 에이전트는 VLM(Vision-Language Model)을 활용하여 Android 키오스크 애플리케이션을 자동으로 제어하는 AI 시스템입니다. 디지털 기기 사용에 어려움을 겪는 사용자를 돕기 위해 화면을 시각적으로 이해하고 직접 조작합니다. |
| 29 | + |
| 30 | +<img width="2816" height="1536" alt="AgentStudio_Banner" src="https://github.com/user-attachments/assets/0036ca31-18a5-4d49-87c4-56998dccdcbb" /> |
| 31 | + |
| 32 | +### ✨ 주요 특징 (Features) |
| 33 | + |
| 34 | +- **강력한 Gemini 추론**: 최신 `gemini-3-flash` 및 `gemini-3-pro` 모델을 지원하여 정교한 화면 분석이 가능합니다. |
| 35 | +- **VLA 패러다임**: Vision(시각) → Language(언어/추론) → Action(행동)으로 이어지는 순환 워크플로우를 구현합니다. |
| 36 | +- **[AG-UI Protocol](https://github.com/ag-ui-protocol/ag-ui)**: 에이전트와 프론트엔드 간의 표준화된 SSE 실시간 통신을 지원합니다. |
| 37 | +- **Human-in-the-Loop (HITL)**: 주관적인 선택(예: 메뉴 옵션 선택)이 필요할 때 사용자에게 질문하고 응답을 기다립니다. |
| 38 | +- **Planning Mode**: 복잡한 요청을 여러 단계로 분해하고, To-do 리스트 형태로 실시간 진행 상황을 표시합니다. |
| 39 | +- **음성 인터페이스**: TTS (CosyVoice3) 및 STT (Google Cloud)를 통한 자연스러운 음성 상호작용을 지원합니다. |
| 40 | +- **실시간 대시보드**: 에이전트의 사고 과정(Reasoning)과 화면 조작 상태를 실시간으로 모니터링합니다. |
| 41 | + |
| 42 | +--- |
| 43 | + |
| 44 | +## 🧠 모델 설정 (Model Configuration) |
| 45 | + |
| 46 | +AgentStudio는 작업의 복잡도와 요구 성능에 따라 모델을 자유롭게 선택할 수 있습니다. |
| 47 | + |
| 48 | +| 제공자 | 모델명 | 상태 | 권장 용도 | |
| 49 | +| :--- | :--- | :--- | :--- | |
| 50 | +| **Google** | `gemini-3-flash` | ✅ 지원됨 | 기본 모델. 빠른 응답 속도와 효율성 | |
| 51 | +| **Google** | `gemini-3-pro` | ✅ 지원됨 | 복잡한 UI 레이아웃 분석 및 고차원 추론 | |
| 52 | +| **OpenAI** | `gpt-4o-mini` | ✅ 지원됨 | 일관된 성능의 대체 모델 | |
| 53 | +| **Google** | `gemma-2` | 🔜 예정 | 온디바이스 처리 및 개인정보 보호 로컬 실행 | |
| 54 | + |
| 55 | +모델을 변경하려면 `.env` 파일의 변수를 수정하세요: |
| 56 | +```bash |
| 57 | +MODEL_PROVIDER=gemini |
| 58 | +GEMINI_MODEL=gemini-3-flash # gemini-3-flash 또는 gemini-3-pro 선택 |
| 59 | + |
| 60 | +``` |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +## 📐 아키텍처 (Architecture) |
| 65 | + |
| 66 | +### 🔄 VLA 워크플로우 |
| 67 | + |
| 68 | +VLA 패러다임은 에이전트가 화면을 보고(See), 이해하고(Understand), 행동하는(Act) 순환 구조입니다. |
| 69 | + |
| 70 | +```mermaid |
| 71 | +flowchart LR |
| 72 | + A[Screen Capture] --> B[VLM Reasoning] |
| 73 | + B --> C[Action Decode] |
| 74 | + C --> D[Execute ADB] |
| 75 | + D --> E{Done?} |
| 76 | + E -->|No| A |
| 77 | + E -->|FINISH| F[Complete] |
| 78 | + E -->|INTERRUPT| G[Human Input] |
| 79 | + G --> A |
| 80 | +
|
| 81 | +``` |
| 82 | + |
| 83 | +### 🔀 LangGraph 상태 기계 |
| 84 | + |
| 85 | +LangGraph를 사용하여 에이전트의 논리적 흐름과 상태 전이를 관리합니다. |
| 86 | + |
| 87 | +```mermaid |
| 88 | +flowchart TD |
| 89 | + START([Start]) --> VLM[VLM Node] |
| 90 | + VLM --> EXEC[Execute Node] |
| 91 | + EXEC --> ROUTER{Router} |
| 92 | + ROUTER -->|LOOP| VLM |
| 93 | + ROUTER -->|INTERRUPT| HUMAN[Human Node] |
| 94 | + ROUTER -->|FINISH| END([End]) |
| 95 | + HUMAN -->|Resume| VLM |
| 96 | + HUMAN -->|Abort| END |
| 97 | +
|
| 98 | +``` |
| 99 | + |
| 100 | +--- |
| 101 | + |
| 102 | +## 🚀 설치 방법 (Installation) |
| 103 | + |
| 104 | +### 사전 요구사항 |
| 105 | + |
| 106 | +* **Python**: 3.10+ (3.11 권장) |
| 107 | +* **Node.js**: 18+ (대시보드 실행용) |
| 108 | +* **uv**: 최신 버전 (빠른 패키지 관리자) |
| 109 | +* **ADB**: Android Debug Bridge 설치 및 환경변수 설정 완료 |
| 110 | + |
| 111 | +### 1단계: 저장소 복제 |
| 112 | + |
| 113 | +```bash |
| 114 | +git clone [https://github.com/Pseudo-Lab/Agent_Studio.git](https://github.com/Pseudo-Lab/Agent_Studio.git) |
| 115 | +cd Agent_Studio |
| 116 | + |
| 117 | +``` |
| 118 | + |
| 119 | +### 2단계: 파이썬 환경 설정 (uv 사용) |
| 120 | + |
| 121 | +```bash |
| 122 | +# 가상환경 생성 및 활성화 |
| 123 | +uv venv .venv |
| 124 | +source .venv/bin/activate |
| 125 | + |
| 126 | +# 의존성 설치 (Editable 모드) |
| 127 | +uv pip install -e backend/ |
| 128 | + |
| 129 | +``` |
| 130 | + |
| 131 | +### 3단계: 환경 변수 설정 |
| 132 | + |
| 133 | +```bash |
| 134 | +cp .env.example .env |
| 135 | +# .env 파일을 열어 GOOGLE_API_KEY 등을 입력하세요. |
| 136 | + |
| 137 | +``` |
| 138 | + |
| 139 | +--- |
| 140 | + |
| 141 | +## 🎯 지원 액션 (Supported Actions) |
| 142 | + |
| 143 | +| 액션 | 파라미터 | 설명 | |
| 144 | +| --- | --- | --- | |
| 145 | +| `CLICK` | `x, y` | 특정 좌표를 클릭 | |
| 146 | +| `INPUT` | `text` | 텍스트 입력 필드에 내용 입력 | |
| 147 | +| `SWIPE` | `x1, y1, x2, y2` | 화면 스크롤 또는 스와이프 | |
| 148 | +| `INTERRUPT` | `question` | 사용자에게 추가 정보를 요청 (HITL) | |
| 149 | +| `FINISH` | - | 모든 작업이 성공적으로 완료됨 | |
| 150 | + |
| 151 | +--- |
| 152 | + |
| 153 | +## 🗓️ 로드맵 (Roadmap) |
| 154 | + |
| 155 | +### ✅ v1.0.0 (현재) |
| 156 | + |
| 157 | +* LangGraph 기반 VLA 에이전트 루프 구현 |
| 158 | +* **Gemini 3 (Flash/Pro)** 모델 연동 완료 |
| 159 | +* Planning Mode 및 HITL(Human-in-the-Loop) 시스템 |
| 160 | +* AG-UI 프로토콜 기반 실시간 SSE 대시보드 |
| 161 | + |
| 162 | +### 🔜 v1.1.0 (2026년 1월 예정) |
| 163 | + |
| 164 | +* **Gemma 통합**: 경량 로컬 모델 지원으로 온디바이스 실행 가능 |
| 165 | +* **Microsoft Agent Framework**: Semantic Kernel 및 Azure AI Agent Service 연동 |
| 166 | +* **Google ADK**: Gemini 네이티브 에이전트 프레임워크 지원 |
| 167 | +* **CrewAI**: 멀티 에이전트 협업 워크플로우 확장 |
| 168 | + |
| 169 | +--- |
| 170 | + |
| 171 | +## 👥 팀 소개: Agent Studio (가짜연구소 11기) |
| 172 | + |
| 173 | +| 성함 | 역할 | 주요 담당 분야 | |
| 174 | +| --- | --- | --- | |
| 175 | +| [김재현](https://github.com/jh941213) | 빌더 | 프론트엔드(Next.js), 백엔드(FastAPI) | |
| 176 | +| [김승혁](https://github.com/SeungHyeokKim) | 러너 | LangGraph, 추론 엔진, 프롬프트 엔지니어링 | |
| 177 | +| [이규민](https://github.com/qmin2) | 러너 | VLA 메커니즘 설계, LangGraph 아키텍처 | |
| 178 | +| [전민정](https://github.com/ummjevel) | 러너 | 음성 인터페이스(TTS/STT), Google ADK 연동 | |
| 179 | + |
| 180 | +--- |
| 181 | + |
| 182 | +## 🗞 라이선스 (License) |
| 183 | + |
| 184 | +본 프로젝트는 **Apache License 2.0**을 따릅니다. |
| 185 | + |
| 186 | +--- |
| 187 | + |
| 188 | +<div align="center"> |
| 189 | +<b>Pseudo-Lab</b>과 함께 ❤️로 개발되었습니다. |
| 190 | +</div> |
| 191 | + |
0 commit comments