# 04. Điều phối Đa Đặc vụ Trí tuệ Nhân tạo (Antigravity Multi-Agent Orchestration)

> **Framework**: Google Antigravity Python SDK (`google-genai` & `google-antigravity`)  
> **Kiến trúc**: Hierarchical Multi-Agent Swarm (Master Agent + Sub-Agents)  
> **Mô hình**: Siêu tốc độ thế hệ mới **Gemini 3.8 Flash** (Độ trễ < 300ms, Cửa sổ ngữ cảnh 1M Tokens) kết hợp Gemma 3 Cục bộ (LiteRT)

---

## 1. Thiết kế Hệ sinh thái Đặc vụ (Agent Ecosystem Overview)

Trong các hệ thống bot thông thường, việc ra quyết định dựa hoàn toàn vào các cây điều kiện cứng (Hardcoded If-Else Trees). Cách tiếp cận này bộc lộ điểm yếu chết người trong Path of Exile 2: không thể thích ứng với các biến đổi địa hình ngẫu nhiên, không thể định giá hàng triệu tổ hợp thuộc tính trang bị (Affixes), và dễ bị hệ thống phân tích hành vi của nhà phát hành phát hiện do các mẫu hành động lặp đi lặp lại.

**AutoPOE2** ứng dụng **Google Antigravity SDK** kết hợp mô hình **Gemini 3.8 Flash** để xây dựng một tổ hợp Đặc vụ AI tự hành phân cấp:

```mermaid
graph TD
    subgraph MasterLayer ["Tầng Điều phối Tối cao (Master Layer)"]
        MasterAgent["Master Orchestrator Agent (Gemini 3.8 Flash)"]
    end

    subgraph SubAgentLayer ["Tầng Đặc vụ Chuyên trách (Sub-Agent Swarm)"]
        NavAgent["Procedural Navigator Agent<br/>(Dẫn đường & Giải mê cung)"]
        LootAgent["Loot & Economy Appraiser Agent<br/>(Định giá & Phân tích Đồ - Gemini 3.8 Flash Vision)"]
        BossAgent["Boss Tactics & Poise Strategist<br/>(Chiến thuật Đấu Boss)"]
        SafeAgent["Safety & Anti-Ban Supervisor<br/>(Giám sát An toàn & Chống Ban - Gemini 3.8 Flash Chat)"]
    end

    subgraph ToolLayer ["Tầng Công cụ Kết nối (MCP & Game Bridge Tools)"]
        ToolMem["tool: read_game_state()"]
        ToolMap["tool: get_minimap_grid()"]
        ToolOCR["tool: parse_item_tooltip()"]
        ToolInput["tool: send_macro_command()"]
        ToolMarket["tool: query_poe2_economy()"]
    end

    MasterAgent ==>|Ủy quyền Nhiệm vụ| NavAgent
    MasterAgent ==>|Ủy quyền Nhiệm vụ| LootAgent
    MasterAgent ==>|Ủy quyền Nhiệm vụ| BossAgent
    MasterAgent ==>|Ủy quyền Nhiệm vụ| SafeAgent

    NavAgent --> ToolMap
    NavAgent --> ToolInput
    LootAgent --> ToolOCR
    LootAgent --> ToolMarket
    BossAgent --> ToolMem
    BossAgent --> ToolInput
    SafeAgent --> ToolMem
    SafeAgent --> ToolInput
```

---

## 2. Chi tiết Các Đặc vụ Chuyên trách (Sub-Agents Specification)

### 2.1. Master Orchestrator Agent (Đặc vụ Điều phối Trưởng)
- **Vai trò**: Nắm giữ trạng thái vĩ mô của phiên chơi (Game State Machine).
- **Mô hình**: **Gemini 3.8 Flash**.
- **Trách nhiệm**:
  - Quyết định khi nào bắt đầu một lượt chạy map mới, khi nào về thị trấn cất đồ, khi nào nâng cấp trang bị.
  - Phân bổ tài nguyên và điều phối các Sub-Agents theo bối cảnh (ví dụ: khi đang đánh Boss, tạm dừng `LootAgent` và dồn toàn bộ chu kỳ xử lý cho `BossAgent`).

### 2.2. Procedural Navigator Agent (Đặc vụ Dẫn đường Mê cung)
- **Mô hình ưu tiên**: Gemma 3 Cục bộ (LiteRT) kết hợp Gemini 3.8 Flash.
- **Trách nhiệm**:
  - Nhận bản đồ thu gọn từ Tier 1 qua `get_minimap_grid()`.
  - Phân tích các nút giao lộ (Intersections) của mê cung ngẫu nhiên.
  - Dự đoán vị trí phòng Boss dựa trên quy luật địa chất của từng Act/Map trong POE2.
  - Lập lộ trình tối ưu dọn sạch quái (Full Clear) hoặc chạy tắt (Speed Run).

### 2.3. Multimodal Loot & Economy Appraiser Agent (Đặc vụ Định giá Chiến lợi phẩm)
- **Mô hình ưu tiên**: **Gemini 3.8 Flash** (Multimodal Vision Siêu tốc < 300ms & Structured Outputs).
- **Trách nhiệm**:
  - Chụp ảnh tooltip hoặc bóc tách chuỗi Affixes của trang bị Rare/Unique.
  - Đánh giá sự tương tác giữa các dòng mod (ví dụ: Tier 1 Elemental Damage + Cast Speed + Sockets).
  - So sánh với dữ liệu giá trị thị trường cập nhật thời gian thực (POE2 Ninja / Trade API).
  - Phân loại trang bị theo 3 hướng xử lý:
    1. `STASH_FOR_TRADE`: Cất vào tab bán hàng định giá cao.
    2. `EQUIP_UPGRADE`: Tự động trang bị ngay nếu mạnh hơn trang bị hiện tại.
    3. `VENDOR_OR_SALVAGE`: Bán cho NPC lấy vàng hoặc rã lấy nguyên liệu.

### 2.4. Boss Tactics & Poise Strategist (Đặc vụ Chiến thuật Đấu Boss)
- **Trách nhiệm**:
  - Theo dõi thanh máu và thanh Stagger của Boss.
  - Dự đoán giai đoạn chuyển phase (Invulnerability Phases / Bullet Hell phases) để ra lệnh cho Tier 1 giữ khoảng cách an toàn.
  - Ra lệnh chuyển đổi trạng thái chiến đấu: từ *Kiting & Thăm dò* sang *Burst DPS Tối đa* ngay khi Boss ngã quỵ vì Stagger.

### 2.5. Safety & Anti-Ban Supervisor (Đặc vụ Giám sát An toàn)
- **Trách nhiệm**:
  - Giám sát tần suất hành động của bot (Actions Per Minute - APM). Nếu APM duy trì quá đều đặn, đặc vụ sẽ chèn các khoảng nghỉ ngẫu nhiên (micro-pauses từ 0.5s đến 2s).
  - Đọc tin nhắn chat trong game: Nếu có người chơi thì thầm (Whisper) hoặc thông điệp đáng ngờ từ hệ thống, đặc vụ có thể trả lời tự động bằng ngôn ngữ tự nhiên hợp ngữ cảnh (Human-like Chat Response) hoặc bấm thoát ra màn hình chọn nhân vật (Logout Macro).
  - Quản lý lịch trình hoạt động sinh học: Tự động cho bot "nghỉ ăn cơm/đi ngủ" sau 2-3 tiếng cày cuốc liên tục.

---

## 3. Mã nguồn Triển khai Mẫu với Google Antigravity SDK

Dưới đây là đoạn mã Python chuẩn hóa sử dụng thư viện `google-antigravity` để khởi tạo hệ thống đa đặc vụ cho POE2:

```python
"""
POE2 Autonomous Agent Swarm using Google Antigravity SDK
Target: Path of Exile 2 (v0.5.5) - September 2026
"""

import asyncio
from google_antigravity import Agent, LocalAgentConfig
from pydantic import BaseModel, Field
from typing import Literal

# ==========================================
# 1. ĐỊNH NGHĨA SCHEMAS DỮ LIỆU ĐẦU RA (Pydantic)
# ==========================================

class LootEvaluationResult(BaseModel):
    item_name: str = Field(description="Tên trang bị hoặc loại tiền tệ")
    rarity: Literal["Normal", "Magic", "Rare", "Unique", "Currency"]
    estimated_value_chaos: float = Field(description="Giá trị ước tính quy đổi ra Chaos/Divine Orbs")
    decision: Literal["KEEP_TRADE", "EQUIP_NOW", "SALVAGE_FOR_MATERIALS", "IGNORE"]
    reasoning: str = Field(description="Lý do phân loại dựa trên meta POE2 v0.5.5")

class MapNavigationPlan(BaseModel):
    primary_objective: Literal["RUSH_BOSS", "CLEAR_PACKS", "COMPUTE_LEAGUE_EVENT", "HEAD_TO_EXIT"]
    target_coordinates: tuple[float, float] = Field(description="Tọa độ XY đích tiếp theo")
    danger_level: Literal["LOW", "MEDIUM", "EXTREME"]
    recommended_kiting_stance: Literal["AGGRESSIVE", "BALANCED", "RETREAT"]

# ==========================================
# 2. CÔNG CỤ TÍCH HỢP GAME (CUSTOM TOOLS)
# ==========================================

def read_item_tooltip_from_clipboard() -> str:
    """Đọc dữ liệu thuộc tính trang bị từ bộ nhớ đệm (Ctrl+C trong POE2)."""
    # Mô phỏng tích hợp đọc dữ liệu
    return """
    Item Class: Bows
    Rarity: Rare
    Death Chaser, Composite Bow
    Quality: +20%
    Physical Damage: 85-180
    Elemental Damage: 120-250 (Fire)
    Critical Strike Chance: 8.5%
    Attacks per Second: 1.45
    Requirements: Level 58, 140 Dex
    Sockets: S-S-S
    ---
    +115% increased Physical Damage
    Adds 45 to 80 Fire Damage
    +28% to Global Critical Strike Multiplier
    +35% to Fire Resistance
    """

def send_macro_command_to_core(command_type: str, target_x: float, target_y: float) -> str:
    """Gửi mệnh lệnh vĩ mô tới Tier 1 C++ Core qua Shared Memory."""
    # Kết nối IPC ghi vào Ring Buffer
    return f"Sent command {command_type} to coordinates ({target_x}, {target_y}) successfully."

# ==========================================
# 3. THIẾT LẬP SUB-AGENTS & MASTER ORCHESTRATOR
# ==========================================

def create_poe2_agent_system():
    # 3.1. Sub-Agent Định giá Đồ (Loot Appraiser)
    loot_agent = Agent(
        name="LootAppraiser",
        role="POE2 Economics & Item Specialist",
        instructions="""
        Bạn là chuyên gia thẩm định trang bị Path of Exile 2 phiên bản 0.5.5.
        Nhiệm vụ của bạn là phân tích các dòng mod, bậc (tiers) và sự phối hợp chỉ số (synergy)
        với các build phổ biến nhất hiện hành. Luôn xuất dữ liệu dưới dạng LootEvaluationResult JSON.
        """,
        tools=[read_item_tooltip_from_clipboard],
        model="gemini-2.5-flash",
    )

    # 3.2. Sub-Agent Dẫn đường (Procedural Navigator)
    nav_agent = Agent(
        name="MapNavigator",
        role="POE2 Procedural Layout Strategist",
        instructions="""
        Bạn là chuyên gia định vị và tìm đường trong các bản đồ ngẫu nhiên của POE2.
        Phân tích địa hình, phát hiện vị trí cổng Boss và các cơ chế phụ (League Mechanics).
        Đưa ra kế hoạch di chuyển tối ưu và an toàn nhất.
        """,
        tools=[send_macro_command_to_core],
        model="gemini-2.5-flash",
    )

    # 3.3. Master Orchestrator Agent
    master_agent = Agent(
        name="MasterDirector",
        role="Autonomous Farming Commander",
        instructions="""
        Bạn là chỉ huy tối cao của hệ thống AutoPOE2.
        Quản lý toàn bộ vòng lặp cày cuốc:
        1. Khi vào map, triệu hồi MapNavigator để dẫn đường.
        2. Khi có đồ rơi, triệu hồi LootAppraiser để đánh giá.
        3. Duy trì sự an toàn và phong cách chơi giống người thật nhất có thể.
        """,
        subagents=[loot_agent, nav_agent],
        model="gemini-2.5-flash",
    )

    return master_agent

# ==========================================
# 4. CHU TRÌNH VẬN HÀNH BẤT ĐỒNG BỘ
# ==========================================

async def main():
    agent_system = create_poe2_agent_system()
    print("AutoPOE2 Antigravity Agent Swarm đã sẵn sàng vận hành...")
    
    # Giả lập một lượt thẩm định đồ rơi
    response = await agent_system.run("Phát hiện một cây cung Rare vừa rơi dưới đất. Hãy phân tích và đưa ra quyết định.")
    print("Kết quả từ Agent Swarm:\n", response)

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 4. Tối ưu Hóa Tốc độ & Chi phí Xử lý (Latency & Cost Optimization)

1. **Bộ đệm Quyết định Cục bộ (Decision Caching)**:
   - Các vật phẩm tiền tệ phổ biến (Scroll of Wisdom, Transmutation, Alchemy, Chaos) được bộ nhớ Tier 1 nhận diện tức thì qua ID nhị phân mà không cần gọi đến LLM.
   - Chỉ những trang bị Rare cấp cao và Unique có biến thiên chỉ số rộng mới được đẩy qua hàng đợi thẩm định của `LootAppraiserAgent`.
2. **Xử lý Hàng loạt trong Thị trấn (Batch Processing in Town)**:
   - Khi dọn map, bot chỉ gom toàn bộ đồ đạt chuẩn sơ bộ vào hòm tạm.
   - Khi quay về thị trấn an toàn, Sub-Agent sẽ kích hoạt một lượt thẩm định hàng loạt (Batch Appraisal) toàn bộ túi đồ, giúp giảm số lượng cuộc gọi API đến 80% và tiết kiệm tối đa chi phí.