agent-iot / README.md
ASown's picture
Consolidate project history under ASown
f368481
|
Raw History Blame Contribute Delete
3.66 kB
metadata
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):

.\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):

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:

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/<tên>/ 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).