Agent Node

LAN 다중 머신 지능형 에이전트 협업 노드. 각 컴퓨터에 하나씩 배포하면 「다중 머신 다중 에이전트 협업 팀」을 구성할 수 있습니다: 자동 LAN 상호 발견, 대칭형 제어/원격 제어 명령 실행, 시스템 트레이에서 상태 확인 가능, 노드 간 파일 송수신, AI 클라이언트가 호출할 수 있는 내장 MCP Server.

agent-bus 저장소에서 분리한 최소화 독립 프로젝트. 소스 코드로 실행되며, 패키징 배포는 없음.

1. 기능 설계

2. 사용 시나리오

• 다중 머신 다중 에이전트 협업: 하나의 AI 클라이언트가 MCP를 통해 여러 컴퓨터의 기능을 도구로 캡슐화하여, 머신 간 스케줄링.

• LAN 원격 운영 / 디버깅: 임의 노드에서 다른 노드에 명령을 내리고 결과 수신.

• 머신 간 파일 전송: 단일 파일 / 디렉토리(자동 zip 패키징) 양방향 송수신.

• AI 클라이언트 연결: 「작업 보내기 / 받은 편지함 확인 / 명령 실행 / 파일 읽기 쓰기 / 업로드 다운로드」를 표준 도구로 캡슐화하여 Claude / Cursor가 호출.

3. 기술 아키텍처

┌──────────── 中心节点 (一台, --role hub) ────────────┐
│  mosquitto (MQTT broker)                           │
│  bus_server (FastAPI + SQLite, Web 面板 + 文件服务) │
│  自身控制节点 (带全部功能)                            │
└────────────────────────────────────────────────────┘
          ▲ MQTT / HTTP               ▲ UDP beacon 发现
          │                           │
┌─────────┴─────────┐       ┌─────────┴─────────┐
│ worker (对称控制节点) │  ...  │ worker (对称控制节点) │
│ 连总线 + 受控/遥控    │       │ 连总线 + 受控/遥控    │
└───────────────────┘       └───────────────────┘

• 통신 계층: MQTT(mosquitto), 메시지는 topic으로 라우팅(agent/<id>/inbox, bus/register, bus/heartbeat/), QoS 1, retain 등록 + 유언 오프라인.

• 발견 계층: UDP 브로드캐스트 비콘(255.255.255.255:41830), 대칭형 무주종; worker 시작 시 is_master 노드 자동 스캔하여 실제 broker 주소 획득(수동 설정 불필요).

• 파일 계층: HTTP(bus_server, FastAPI), Claim-Check 업로드 다운로드, 디렉토리 자동 zip / 안전한 압축 해제(경로 트래버설 + zip-slip 방지).

• 중앙: hub 역할이 mosquitto를 인라인으로 시작(로컬에 설치되어 있으면 재사용, 아니면 첫 시작 시 build/mosquitto.zip에서 압축 해제) + bus_server + 웹 패널.

• MCP: FastMCP가 stdio 전송 사용, GUI 모드와 분리되어 독립 실행 가능.

MCP 도구(10개): list_online_agents · send_task · check_inbox · run_command · read_file · upload_file · download_file · fetch_file · post_file · reply_task

4. 설치

4.1 사전 요구 사항

• Python 3.10+(모든 머신)

• LAN 통신 가능 + 방화벽 허용(hub 측 인바운드):

  • TCP 1883(MQTT, 포트 풀 폴백 가능 1884/1885/8883/18830)

  • TCP 8000(HTTP 패널/파일, 풀 폴백 8001/8002/8010/8088)

  • UDP 41830(발견 브로드캐스트)

4.2 hub 마스터 머신(한 대)

전체 프로젝트 디렉토리 + mosquitto 필요.

# 1. 获取代码（git clone 或拷贝整个 agent-node 文件夹）
git clone <本仓库地址>

# 2. 安装依赖
cd agent-node
pip install -r requirements.txt

# 3. 启动中心节点（起 broker + Web 面板 + 自身控制节点 + 托盘）
python executor/control_app.py --role hub

• mosquitto: 로컬에 설치되어 있으면 자동 재사용(shutil.which("mosquitto") 또는 C:\Program Files\mosquitto); 설치되어 있지 않으면 최초 시작 시 build/mosquitto.zip에서 data/runtime/mosquitto로 자동 압축 해제, 그러므로 build/는 반드시 유지해야 함.

• 웹 패널: 시작 후 브라우저에서 http://127.0.0.1:8000/ 열기(포트 풀 폴백 시 시작 로그에서 실제 포트 확인).

• hub 최초 시작 시 data/ 생성(bus.db, files, broker.log, node_config.json), 사전 준비 불필요.

4.3 worker 다른 머신(여러 대)

간소화된 하위 집합만 필요: agent_bus/ 패키지 + executor/control_app.py + requirements.txt(server/, build/, scripts/는 불필요).

# 1. 拷贝精简子集到目标机器（或 git clone 后仅运行，多余的目录会被自动忽略）
#    agent_bus/  executor/control_app.py  requirements.txt

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动 worker（无参数，自动扫描局域网中心）
python executor/control_app.py

• broker 주소 설정 불필요: worker가 --broker-host 없이 LAN의 is_master 노드를 자동 스캔하여 실제 주소(host / MQTT 포트 / HTTP 포트 세 가지 모두) 획득.

• 수동으로 중앙 지정(크로스 네트워크 세그먼트 / 자동 발견 실패 시): python executor/control_app.py --broker-host 192.168.1.10

• 받은 편지함은 자동으로 Downloads/agent-node/inbox에 저장, data/ 설정 디렉토리 자동 생성, 모두 사전 준비 불필요.

4.4 최소 파일 목록

5. 명령 매개변수

포트 풀

• MQTT: 1883 → 1884 → 1885 → 8883 → 18830

• HTTP: 8000 → 8001 → 8002 → 8010 → 8088

• 발견: 41830 → 41831 → 41832 → 41840 → 41850

6. MCP 설정(AI 클라이언트용)

--mcp는 stdin/stdout을 사용하며, Claude Desktop / Cursor 등이 MCP Client로 JSON 설정을 통해 실행.

{
  "mcpServers": {
    "agent-node": {
      "command": "python",
      "args": [
        "C:/path/to/agent-node/executor/control_app.py",
        "--mcp", "--role", "worker", "--agent-id", "my-agent"
      ],
      "env": { "BUS_BROKER_HOST": "192.168.1.10" }
    }
  }
}

BUS_BROKER_HOST는 생략 가능 — worker가 자동으로 중앙 발견; 크로스 네트워크 세그먼트 또는 발견 실패 시 명시적으로 지정.

7. 디렉토리 구조

agent-node/
├── executor/
│   └── control_app.py          # 节点主入口（对称 + 托盘 + MCP + 中心角色）
├── agent_bus/                  # 通信 SDK（client/config/discovery/provision/files/schema...）
├── server/
│   ├── bus_server.py           # 中心 HTTP + 消息服务（可编程 serve_bus_server 内联启动）
│   └── static/index.html       # Web 面板
├── scripts/
│   └── build_mosquitto_zip.py  # 重建 mosquitto 便携包
├── build/
│   └── mosquitto.zip           # 便携 mosquitto（hub 首启自解压）
├── docs/
│   ├── 需求与设计.md
│   └── BUGFIX_LOG_20260819.md
└── requirements.txt

8. 보안 모델

이 프로젝트는 신뢰할 수 있는 LAN을 대상으로 함: broker allow_anonymous, 제어 메시지는 MQTT로 평문 전송, sender_id 접두사 화이트리스트만 적용(제어면은 hub-* 신분만 수락). HMAC 서명 / 암호화 / 노드 화이트리스트는 하지 않음 — 신뢰할 수 없는 네트워크를 통과할 때는 자체적으로 보안 강화 필요.