phongent 튜토리얼: iPhone 또는 Android로 여러 휴대폰 Agent 협업 제어

phongent란

phongent는 여러 기기의 Agent를 협업 제어하는 프로젝트입니다. 자연어로 모든 기기, 특정 기기 그룹 또는 지정한 기기에 작업을 할당하고, 하나의 인터페이스에서 실행 진행 상황, 결과, 알림 메시지와 Android 기기의 실시간 화면을 확인할 수 있습니다.

iOS와 Android 모두 마스터 컨트롤러로 사용할 수 있으며, Android 실행 기기를 연결하고 관리합니다. 두 플랫폼 모두 작업 할당, 결과 확인, 메시지 관리, 실시간 미니 창과 제어권 인계를 지원합니다. 단, Android만 기기 자체의 App 조작 작업을 직접 실행할 수 있습니다.

주의: 현재 iOS는 마스터 컨트롤러로서 Android 실행 기기에 연결하는 용도로만 사용할 수 있으며, iPhone 자체의 App 조작 작업은 실행할 수 없습니다.

핵심 기능

• 다중 기기 작업 할당: 기기를 길게 누르고 작업을 설명하거나, 마스터 컨트롤러의 작업 Agent가 기기에 작업을 어떻게 배포할지 직접 결정하도록 할 수 있습니다.
• 기기 그룹 협업: 전체 기기 그룹을 선택해 작업을 일괄 실행하고, 서로 다른 그룹이나 그룹 내 특정 기기에 각각 다른 작업을 지정할 수 있습니다.
• 콘텐츠 제작 및 배포: 마스터 모델이 여러 문안과 텍스트 이미지 카드를 생성한 뒤 서로 다른 콘텐츠를 해당 기기에 전달해 처리하도록 할 수 있으며, 이미지를 첨부할 수도 있습니다.
• Android 실시간 미니 창: Android 가상 화면을 확인하고 클릭, 스와이프, 입력을 통해 기기 조작을 직접 제어할 수 있습니다. 이 기능은 기본적으로 활성화되어 있으며 설정에서 끌 수 있습니다.
• 메시지 중앙 처리: 기기, 앱, 메시지 출처에 따라 알림을 정리하고 대상 Android 기기의 Agent가 메시지에 답장하도록 할 수 있습니다.
• 중앙 구성: 메모리, 스킬, 예약 작업과 작업 경로를 관리하고 단일 기기 또는 여러 기기에 일괄 적용할 수 있습니다.
• 연결 관리: 로컬 네트워크 검색, 최초 승인, 원클릭 연결, 연결 끊김 후 재연결, 기기 이름 변경과 기기 그리드를 지원합니다.

설치 전 준비

기기 및 시스템 요구 사항

• 실행 기기로 사용할 Android 기기를 최소 한 대 준비합니다.
• 마스터 컨트롤러는 iPhone 또는 Android 기기를 사용할 수 있습니다.
• 마스터 컨트롤러와 실행 기기는 동일한 로컬 네트워크에 연결되어야 합니다.
• Android 최소 설치 버전은 Android 11입니다. 구체적인 조작 가능 여부는 시스템 버전과 권한 설정의 영향도 받습니다.
• iOS 최소 배포 버전은 iOS 17이며, 현재 Xcode를 사용해 빌드하고 서명한 뒤 설치해야 합니다.

올바른 설치 패키지 선택

Android 사용자는 프로젝트 릴리스 페이지에서 phongent.apk를 다운로드할 수 있습니다. 반드시 phongent 프로젝트에서 제공하는 빌드를 사용하세요. 상위 프로젝트의 APK로 대체하면 안 됩니다. 상위 버전에는 다중 기기 그룹 제어에 필요한 인터페이스가 없을 수 있습니다.

빠른 구성 및 연결

1. 앱 설치. Android 기기에 phongent APK를 설치합니다. iOS 마스터 컨트롤러는 macOS에서 Xcode를 사용해 빌드하고 서명한 뒤 설치해야 합니다.
2. Android 실행 기기 설정. 앱에서 필요한 모델과 휴대폰 조작 기능을 구성하고, 실제 기능에 따라 접근성, 알림 읽기 등의 권한을 부여합니다. 기기 조작의 기본 설정은 프로젝트의 설정 가이드를 참고하세요.
3. 실행 기기 서비스 유지. Android 측 서비스가 시작되었는지 확인하고, 마스터 컨트롤러와 Android 실행 기기를 동일한 로컬 네트워크에 연결합니다.
4. 기기 연결. 마스터 컨트롤러의 “기기” 페이지에서 검색된 Android 기기를 선택하거나 “원클릭 연결”을 사용합니다. 최초 연결 시 Android 측에서 승인을 확인해야 합니다.
5. 마스터 모델 구성. 마스터 컨트롤러 설정으로 이동해 작업을 이해하고 배포할 모델을 구성합니다. 관련 앱 계정은 해당 실행 기기에서 로그인해야 합니다.
6. 협업 시작. “agent” 페이지로 이동해 모든 기기, 하나의 기기 그룹 또는 단일 기기를 선택한 다음 자연어로 작업을 입력합니다.

기기가 최초 승인을 완료하면 연결이 끊긴 뒤에도 다시 연결할 수 있습니다. 기기가 검색되지 않으면 먼저 로컬 네트워크 연결과 Android 측 서비스 상태를 확인하세요. 바로 앱을 반복 설치할 필요는 없습니다.

네 가지 주요 진입점

• 기기: Android 기기를 검색하고 연결하며 이름을 변경하고 그룹으로 관리합니다.
• agent: 작업을 할당하고 실행 진행 상황, 결과와 실시간 미니 창을 확인합니다.
• 메시지: 기기, 앱과 출처별로 알림을 확인하고 답장 작업을 시작합니다.
• 설정: 마스터 모델, 실행 기기 기능과 관련 동기화 옵션을 구성합니다.

기본 사용법: 기기에 작업 배포

서로 다른 기기에 서로 다른 작업 할당

기기 이름이 각각 A와 B라고 가정하면 작업에 각 기기가 해야 할 일을 직접 설명할 수 있습니다.

A는 샤오홍슈 홈페이지를 열고 스크린샷을 찍고, B는 브라우저를 열어 오늘 날씨를 확인해.

제출 후 기기별로 실행 진행 상황과 결과를 확인할 수 있습니다. Android 측 조작을 관찰하거나 수정해야 한다면 해당 기기의 실시간 미니 창을 열고 클릭, 스와이프 또는 입력을 통해 직접 제어할 수 있습니다.

기기 그룹별 일괄 협업

콘텐츠 제작, 점검 또는 운영처럼 반복되는 작업은 먼저 기기 그룹을 만든 다음 그룹 이름으로 작업을 할당할 수 있습니다.

콘텐츠 그룹은 각각 제품 소개 초안을 하나씩 작성하고, 점검 그룹은 각 기기의 작업 상태를 확인해.
콘텐츠 그룹의 A는 기존 자료 정리로 변경하고, 나머지 기기는 계속 초안을 작성해.

이러한 설명으로 전체 그룹에 동일한 목표를 지정할 수도 있고, 그룹 내 특정 기기의 작업만 덮어쓸 수도 있습니다.

서로 다른 콘텐츠 생성 및 배포

각 기기가 서로 다른 자료를 처리해야 한다면 마스터 모델에 콘텐츠를 각각 생성한 뒤 기기별로 배포하도록 요청할 수 있습니다.

콘텐츠 그룹의 각 기기에 서로 다른 제목, 본문과 텍스트 이미지 카드를 생성하고,
각 기기에 배포해 초안으로 저장하되 아직 게시하지 마.

작업에 “초안으로 저장하고 아직 게시하지 마”와 같은 제한을 명확히 포함하면 원하는 작업 범위를 전달하는 데 도움이 됩니다. 실제 실행 결과는 모델 구성, 대상 App 상태, 계정 로그인 여부와 부여된 시스템 권한에 따라 달라집니다.

기기 그룹 생성 및 관리

1. “기기” 페이지를 엽니다. 아래쪽 그리드에 현재 연결된 기기와 각 기기의 이름 및 소속 그룹이 표시됩니다.
2. “그룹”을 클릭하고 관리할 기기를 선택합니다.
3. 기존 그룹을 선택하거나 새 그룹을 만듭니다.
4. “N대 이동”을 클릭해 일괄 이동을 완료합니다.

각 기기는 하나의 그룹에만 속할 수 있으며, 이동하면 기존 그룹에서 나옵니다. 수동으로 그룹을 지정하지 않은 기기는 “기본 그룹”에 포함됩니다.

기기 아바타나 카드를 길게 누르면 기기 이름을 변경하거나 그룹을 이동할 수 있습니다. 기기 이름 변경은 해당 Android App과 동기화되도록 시도하지만, 실행 기기가 관련 인터페이스를 지원해야 합니다.

그룹 정보는 현재 마스터 컨트롤러에 저장되며 다른 마스터 컨트롤러로 자동 동기화되지 않습니다. 여러 마스터 컨트롤러를 사용하는 환경에서는 각 마스터 컨트롤러의 그룹을 별도로 관리해야 합니다.

알림 중앙 확인 및 답장

phongent는 권한이 부여된 Android 알림을 읽고 기기, 앱과 메시지 출처별로 정리할 수 있습니다. “메시지” 페이지로 이동하면 알림 세부 정보를 확인하고 해당 Android 기기의 Agent에 답장 작업을 맡길 수 있습니다.

1. 대상 Android 기기에 알림 읽기 권한이 부여되었는지 확인합니다.
2. 마스터 컨트롤러에서 “메시지” 진입점을 엽니다.
3. 기기, 앱 또는 출처별로 대상 알림을 찾습니다.
4. 알림 세부 정보로 이동해 답장 작업을 시작합니다.
5. 대상 Android 기기의 Agent가 실제 답장 작업을 완료합니다.

마스터 컨트롤러에서 알림이 보이지 않으면 먼저 대상 Android 기기의 알림 읽기 권한, 실행 기기 서비스와 연결 상태를 확인하세요.

고급 사용 팁

실행하기 쉬운 작업 설명 작성

• 기기 또는 그룹 이름을 명확히 작성: 예를 들어 “콘텐츠 그룹”, “점검 그룹” 또는 “A 기기”라고 입력합니다.
• 목표를 나누어 작성: 각 기기의 작업을 명확히 설명하고 여러 기기의 요구 사항을 모호한 한 문장에 섞지 않습니다.
• 최종 상태를 명시: 예를 들어 “스크린샷을 찍은 후 결과 반환”, “초안으로 저장”, “아직 게시하지 않기”라고 작성합니다.
• 그룹 내 작업 덮어쓰기: 먼저 전체 그룹에 목표를 할당한 다음 특정 기기가 무엇을 변경해 수행해야 하는지 별도로 설명합니다.
• 계정 먼저 확인: 타사 App과 관련된 작업은 해당 Android 기기에서 미리 계정 로그인을 완료합니다.

실시간 미니 창의 합리적인 사용

실시간 미니 창은 Agent의 작업 과정을 관찰하거나 자동 조작 중 페이지가 변경될 때 직접 제어하는 데 적합합니다. 기본적으로 활성화되어 있으며 실시간 화면이 필요하지 않다면 설정에서 끌 수 있습니다.

실행 기기 일괄 관리

메모리, 스킬, 예약 작업과 작업 경로 등의 설정을 중앙에서 관리하고 기능별로 단일 기기 또는 여러 기기에 적용할 수 있습니다. 일괄 수정 전에는 선택한 기기 범위를 확인해 특정 기기에만 적합한 설정이 전체 그룹에 적용되지 않도록 해야 합니다.

연결 문제 해결

• 마스터 컨트롤러와 실행 기기가 동일한 로컬 네트워크에 있는지 확인합니다.
• Android 실행 기기 서비스가 계속 실행 중인지 확인합니다.
• 최초 연결 시 Android 기기에서 승인을 완료합니다.
• 승인된 기기의 연결이 끊겼다면 다시 연결하거나 “원클릭 연결”을 사용해 보세요.
• 기기 그리드에는 연결된 기기만 표시됩니다. 표시되지 않는 기기는 연결에 성공했다는 의미가 아닙니다.

소스 코드에서 Android 버전 빌드

프로젝트의 Android 앱, 마스터 컨트롤러 인터페이스와 실행 기기 서비스는 app/에 있으며 Agent 핵심 기능은 core/에 있습니다. 빌드에는 JDK 17과 Android SDK가 필요하며, 현재 compileSdk 36을 사용합니다.

./gradlew :app:assembleDebug

디버그 APK는 app/build/outputs/apk/debug/에 생성됩니다. 설치 전 빌드 결과물에 자체 개발 서명이 사용되었는지 확인해야 합니다.

소스 코드에서 iOS 마스터 컨트롤러 빌드

iOS 빌드에는 macOS와 프로젝트에서 사용하는 SDK를 지원하는 Xcode가 필요합니다. 최소 배포 버전은 iOS 17입니다.

1. Xcode로 ios/MikaRemote.xcodeproj를 엽니다.
2. MikaRemote scheme을 선택합니다.
3. 서명 설정에서 자신의 개발 팀을 선택합니다.
4. 대상 iPhone을 연결한 다음 빌드하고 설치합니다.

저장소의 ios/ 디렉터리에는 iOS 마스터 컨트롤러, 구성 요소와 실시간 활동이 포함되어 있습니다. tools/android-emulators/에는 Android 에뮬레이터 연동 도구가 제공되며, 설정 가이드, 프로토콜과 검증 기록은 docs/에 있습니다.

보안 안내: 모델 키, 계정 자격 증명과 로컬 서명 자료를 소스 코드에 작성하거나 버전 저장소에 커밋하지 마세요.

요약

phongent는 여러 Android 기기를 중앙에서 관리할 수 있는 Agent 실행 환경으로 구성하고, iPhone 또는 Android 기기를 마스터 컨트롤러로 사용할 수 있게 합니다. 실행 기기 권한, 로컬 네트워크 연결과 마스터 모델 구성을 완료하면 단일 기기, 기기 그룹 또는 모든 기기에 작업을 할당하고 결과, 실시간 화면과 알림 메시지를 함께 확인할 수 있습니다. 이 프로젝트는 Mika를 기반으로 개발되었으며 Apache License 2.0을 따릅니다.