--- title: Agent emoji: 🤖 colorFrom: blue colorTo: indigo sdk: docker app_port: 8080 pinned: false --- # Agent — maker harness (atria-style) Người dùng trò chuyện với một agent; agent tự **suy luận và gọi công cụ** (máy/khả năng) để thực hiện. Kiến trúc theo kiểu atria: vòng **ReAct** tool-calling, hệ thống **module**, và hạ tầng tùy chọn (Postgres + Redis + Keycloak). ``` harness/ # lõi hệ thống config.py # API key + model registry (đổi/so sánh model dễ) agents/ # ReAct core: react.py + prompts/ (system prompt module hoá) registry.py # shim -> harness/modules (auto-load modules/*/tool.py) modules/ # discovery module (manifest.json + SKILL.md + tool.py) memory.py # trí nhớ hội thoại (in-memory; DB thay khi có DATABASE_URL) db/ # persistence tùy chọn (SQLAlchemy + Postgres) bus.py # bus step events (Redis, tùy chọn) auth.py # AUTH_MODE none|local|keycloak (tùy chọn) webapp.py # FastAPI: chat API (SSE) + UI + conversations + auth static/index.html # frontend chat modules/ # mỗi công cụ một thư mục (manifest.json + SKILL.md + tool.py) cnc_websim/ # mô phỏng CNC / in 3D (cncwebsim, Playwright) paper_printer/ # máy in Brother (WiFi) + tìm-văn-bản jscut_cam/ # dây chuyền CAM: SVG -> jscut -> cncwebsim docker-compose.yml # db + adminer + redis + keycloak + app schema.sql # snapshot schema + tạo DB keycloak keycloak/realm-export.json ``` ## 3 chế độ chạy **(a) Không Docker — nhanh nhất, giống HF Space** (in-memory, không auth): ```powershell .\web.ps1 # -> http://localhost:8080 .\chat.ps1 # hoặc chat trong terminal ``` **(b) Hybrid — hạ tầng trong Docker, app trên host** (khuyến nghị cho dev Windows, giữ vòng lặp Playwright nhanh): ```powershell docker compose up -d db redis keycloak $env:DATABASE_URL="postgresql://maker:maker@localhost:5432/maker" $env:REDIS_URL="redis://localhost:6379/0" # tùy chọn auth: $env:AUTH_MODE="keycloak" (hoặc "local") .\web.ps1 ``` **(c) Full stack — tất cả trong Docker:** ```powershell docker compose up --build # db + adminer:8081 + redis + keycloak:8082 + app:8080 ``` Cần `GROQ_API_KEY` trong `.env`. Đăng nhập Keycloak: user `demo` / mật khẩu `demo`. Mọi biến hạ tầng (`DATABASE_URL`, `REDIS_URL`, `AUTH_MODE`) **tùy chọn** — thiếu thì app tự degrade về in-memory / không auth (đúng như HF Space). ## Model Sửa `harness/config.py` `MODELS`; key trong `.env`. Chọn model ở dropdown header. `HARNESS_MODEL` đặt mặc định. **Chỉ gpt-oss** tool-call native (lái ReAct); llama tự rơi về legacy routing. ## Thêm một công cụ (module) Tạo `modules//` gồm: - `manifest.json` — `{display_name, tooltip, entry:"tool.py"}` - `SKILL.md` — mô tả cho system prompt (làm gì / KHI NÀO dùng / vào-ra) - `tool.py` — expose `get_tool()` trả về `Tool` (`name`, `description`, `run(task)->ToolResult`) Tự động phát hiện. Sửa module rồi gọi `POST /api/modules/reload` (không cần restart). ## Deploy online (HF Space / bất kỳ host Docker nào) `git push space main`. HF không set biến hạ tầng nên chạy in-memory + không auth. Lưu ý: `paper_printer` cần máy in cùng LAN; `cnc_websim`/`jscut_cam` là mô phỏng, chạy mọi nơi (headless, `CNC_HEADLESS=1`).