# VIETAL — Môi trường làm việc cho AI Agent từ xa

> **Résumé (FR)** — Ce document décrit l'environnement de travail permettant à des agents IA
> distants de se connecter au projet VIETAL via HTTPS, de prendre des tâches (bail de 2 h),
> de récupérer le contexte (indicateurs, justificatifs), d'utiliser les ressources internes
> (LLM/OCR/ASR/TTS) et de déposer leurs livrables. Les gestionnaires, eux, créent les demandes,
> fournissent les sources et suivent l'avancement. Toutes les actions sont journalisées.

Tài liệu d' tích hợp cho agent AI (DeepSeek, Claude, GPT, agent tự viết, worker Python…)
làm việc **từ xa** trên hệ thống quản trị dự án VIETAL.

| Hạng mục | Giá trị |
|---|---|
| Base URL | `https://dv.badt.vn/project/api/v1` |
| Xác thực | `Authorization: Bearer vtk_…` (token do quản trị viên cấp) |
| Định dạng | JSON (UTF-8), multipart cho tệp |
| Giới hạn | 120 request/phút/token · tệp ≤ 25 MB |
| Đặc tả máy đọc | [`docs/openapi.yaml`](openapi.yaml) |
| Tổng số endpoint | 39 (có 4 endpoint cây công việc) |
| Tài liệu công khai (Claude web đọc được) | `https://dv.badt.vn/project/docs` |
| Hướng dẫn riêng cho Claude | [`docs/AGENT_CLAUDE.md`](AGENT_CLAUDE.md) |
| Worker mẫu | [`tools/vietal_agent.py`](../tools/vietal_agent.py) |
| Giao diện quản trị | https://dv.badt.vn/project (2 tài khoản: anh Liêm, TS. Saber Aloui) |

---

## 1. Phân vai

Hệ thống được thiết kế cho mô hình **người chỉ huy – agent thực thi**:

| Vai trò | Làm gì | Công cụ |
|---|---|---|
| **Quản trị viên** (2 người) | Cung cấp nguồn thông tin (tài liệu, biên bản, số liệu), đưa yêu cầu, duyệt/trả lại kết quả, theo dõi tiến độ & ngân sách | Giao diện web `/project` |
| **AI Agent** | Nhận việc, đọc ngữ cảnh, xử lý bằng nguồn lực (LLM/OCR/ASR/TTS), nộp kết quả, báo tiến độ, đặt câu hỏi khi thiếu dữ liệu | API `/project/api/v1` |
| **Trợ lý VIETAL** (agent nội bộ) | Trả lời câu hỏi nhanh trong khung chat, tóm tắt tiến độ, rà soát ngân sách | Giao diện `/project/chat` + LLM 250:8091 |

Nguyên tắc: agent **không** sửa/xoá dữ liệu của người khác; mọi thao tác ghi đều vào `vietal_logs`
kèm danh tính agent. Quản trị viên là người duyệt cuối cùng (`review → done`).

---

## 2. Kiến trúc truy cập

```
Agent từ xa (Internet)                        Agent trong LAN 192.168.1.0/24
        │ HTTPS + Bearer vtk_…                          │ HTTPS (hoặc gọi thẳng LAN)
        ▼                                                ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  Apache 2.4 (máy 245) · vhost dv.badt.vn · ModSecurity ON · TLS              │
│  /project/api/v1/*  → PHP 8.3 (vietal_project)                              │
└───────────┬───────────────────────────────────┬────────────────────────────┘
            │ PDO                               │ cURL
            ▼                                   ▼
   MySQL vietal_project @ 244        Nguồn lực AI (pnt.badt.vn hoặc LAN 250)
   tasks · claims · requests          LLM: gemma4 / medgemma / qwen2.5-7b
   evidence · logs · resources        OCR · ASR · TTS
```

Điểm quan trọng:

1. **Không cần VPN**: agent ngoài Internet chỉ cần HTTPS tới `dv.badt.vn` + token.
2. **Nguồn lực AI** chia 2 nhóm `scope`:
   - `public` — gọi được từ Internet qua `pnt.badt.vn/...` (gemma4, medgemma, OCR, ASR, TTS);
   - `lan` — chỉ gọi được trong mạng nội bộ (qwen2.5-7b `192.168.1.250:8091`, gemma4 LAN 8092).
   Agent ngoài Internet dùng nhóm `public`; nếu cần model nội bộ, yêu cầu quản trị viên mở proxy.
3. Mọi dữ liệu qua lại đều **JSON**; tệp đi bằng multipart hoặc base64.

---

## 3. Bắt đầu trong 5 phút

### 3.1 Nhận token

Quản trị viên cấp tại `/project/agents` → nút **Cấp token** (hiện một lần), hoặc CLI:

```bash
php bin/token.php --agent=deepseek-planner --label="VPS-HN" --days=90
```

Token dạng `vtk_<48 hex>`. Lưu vào biến môi trường, **không** commit vào git, không gửi qua chat.

### 3.2 Kiểm tra kết nối

```bash
export VIETAL_TOKEN='vtk_...'
export BASE='https://dv.badt.vn/project/api/v1'

curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$BASE/ping"
# {"ok":true,"agent":{"code":"deepseek-planner",...},"server_time":"...","version":"1.0.0"}
```

### 3.3 Lấy "workspace" — một lời gọi là biết phải làm gì

```bash
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$BASE/workspace?project=VIETAL-2026" | jq .
```

Trả về:

```json
{
  "ok": true,
  "workspace": {
    "agent_id": 2,
    "project": { "code": "VIETAL-2026", "name": "...", "progress": 32, "budget_planned": 250000, "currency": "EUR" },
    "stats":   { "tasks_total": 33, "tasks_done": 3, "milestones": 13, ... },
    "tasks":   [ { "id": 7, "code": "A1.3", "title": "...", "status": "doing", "due_date": "2028-02-29",
                   "claimed_by_agent": null, "claim_expires_at": null } ],
    "requests":[ { "id": 3, "title": "Rà soát 20 ca bệnh đầu tiên", "kind": "request", "status": "open" } ],
    "jobs":    [ { "id": 1, "title": "...", "status": "queued" } ],
    "resources":[ { "code": "llm-medgemma", "scope": "public", "endpoint": "https://pnt.badt.vn/medgemma/v1/chat/completions" } ],
    "protocol": { "1": "...", "2": "...", "3": "...", "4": "...", "5": "...", "6": "..." }
  }
}
```

`tasks` gồm: việc được giao trực tiếp cho agent, việc agent đang giữ, và việc **chưa ai giữ**.

---

## 3b. Cây công việc — agent tự chẻ nhánh

Mỗi công việc có thể có việc con nhiều thế hệ (không giới hạn). Agent dùng:

- `GET /api/v1/tasks?project=VIETAL-2026&tree=1` — cả cây lồng nhau (`children`).
- `GET /api/v1/tasks/{id}` — thuộc tính, tổ tiên, việc con, tài chính (`finance`), minh chứng.
- `POST /api/v1/tasks` `{ "title": "...", "parent": "A1.1", "work_type": "document|training|procurement|...",
  "deliverables": "...", "location": "...", "est_cost": 0, "start_date": "YYYY-MM-DD", "due_date": "YYYY-MM-DD",
  "status": "todo|doing|done", "progress": 0 }` — mã tự sinh (`A1.1.3`), không cần gửi `project` khi có `parent`.
- `POST /api/v1/tasks/{id}` — cập nhật thuộc tính (`title`, `status`, `progress`, `due_date`, `location`, ...).

Lưu ý: tiến độ việc cha do hệ thống cộng dồn từ việc con — **đừng ghi đè** `progress` của việc có con.
Minh chứng: `POST /api/v1/evidence` (multipart) với `task_id`; tài chính: ghi qua giao diện hoặc nhờ quản trị.

## 3c. Tiếp nhận văn bản: xem trước rồi mới ghi

- `POST /api/v1/intake {"text": "...", "apply": false}` → chỉ phân tích, trả `preview.changes` (thêm/cập nhật/bỏ qua + lý do) và `warnings`. Không ghi gì vào dự án.
- `POST /api/v1/intake/{id}/apply` → ghi đúng kế hoạch đã xem trước (không gọi lại mô hình).
- `POST /api/v1/intake/{id}/revert` → hoàn tác lần ghi đó (khôi phục giá trị cũ, xoá bản ghi vừa tạo).
- Dán lại đúng văn bản cũ → API trả `duplicate: true` kèm id bản ghi trước; muốn xử lý lại thì gửi `{"force": true}`.
- Văn bản dài (>~8.400 ký tự) được chia khối tự động; trường `model` cho biết `deepseek-chat · 3 khối`.

## 4. Vòng đời một công việc (lease + review)

```
           ┌────────────┐  claim (POST /tasks/{id}/claim, 120')  ┌────────────┐
  todo ───►│   doing    │──────────────────────────────────────►│  doing     │
           └────────────┘        trả về claim_token             │ (giữ bởi A)│
                                                                └─────┬──────┘
                        POST /tasks/{id}/progress (0–100)             │
                        POST /tasks/{id}/deliverable (nộp bài)        │
                                                                      ▼
                                        ┌────────────┐   duyệt (web)  ┌────────┐
                                        │   review   │───────────────►│  done  │
                                        └─────┬──────┘                └────────┘
                                              │ trả lại + yêu cầu chỉnh sửa
                                              ▼
                                          doing (claim lại)
```

Quy tắc lease:

- Mỗi lần `claim`, server trả `claim_token` + `claim_expires_at` (mặc định **120 phút**, tối đa 24 h).
- Agent khác gọi `claim` khi lease còn hiệu lực → **409 `already_claimed`** kèm `expires_at`.
- Hết hạn lease mà không cập nhật → việc trở lại trạng thái "chưa ai giữ" (tự động, không cần cron).
- Gọi `claim` lần nữa bởi **cùng agent** = gia hạn lease (dùng trong vòng lặp dài).
- `POST /tasks/{id}/release` khi bỏ việc giữa chừng (bắt buộc ghi lý do trong `message` của `/logs`).

---

## 5. Tham chiếu API

Tất cả endpoint dưới `/project/api/v1` (tổng **32**). Quyền: `read` (mọi token) / `write` (token có scope write).

### 5.1 Đọc dữ liệu

| Method | Endpoint | Quyền | Mô tả |
|---|---|---|---|
| GET | `/ping` | read | kiểm tra token, danh sách endpoint |
| GET | `/workspace?project=CODE` | read | gói khởi động (mục 3.3) |
| GET | `/projects` | read | danh sách dự án |
| GET | `/projects/{code}/summary` | read | KPI + mốc của dự án |
| GET | `/tasks?project=CODE&status=doing&type=task&limit=100` | read | danh sách công việc |
| GET | `/tasks/{id}/context` | read | **ngữ cảnh đầy đủ** của một việc |
| GET | `/indicators?project=CODE` | read | 32 chỉ số + giá trị hiện tại + % đạt đích |
| GET | `/requests?status=open` | read | yêu cầu dành cho agent này (hoặc chung) |
| GET | `/jobs?status=queued` | read | việc trong hàng đợi job |
| GET | `/resources` | read | danh mục nguồn lực (kèm token dịch vụ nếu scope write) |
| GET | `/evidence/{id}/file` | read | tải tệp nguồn (ảnh, PDF, biên bản) |
| GET | `/documents?project=CODE&q=…` | read | tìm tài liệu dự án (tiêu đề, mô tả, nội dung đã bóc) |
| GET | `/documents/{id}` | read | **nội dung text** của tài liệu (PDF/DOCX/ảnh bóc tự động, có cache) |
| GET | `/docs` · `/docs/{slug}` | read | tài liệu kỹ thuật của hệ thống (agent-workspace, agent-claude, openapi…) |

### 5.2 Ghi dữ liệu

| Method | Endpoint | Body chính | Tác dụng |
|---|---|---|---|
| POST | `/tasks/{id}/claim` | `{ttl_minutes, note}` | giữ việc, trả `claim_token` |
| POST | `/tasks/{id}/release` | — | trả việc |
| POST | `/tasks/{id}/progress` | `{status, progress, message}` | cập nhật tiến độ |
| POST | `/tasks/{id}/deliverable` | `{title, content, kind, summary}` hoặc multipart `file` | nộp bài → việc sang `review` |
| POST | `/logs` | `{project, action, message, task_id?, payload?}` | ghi nhật ký xử lý |
| POST | `/reports` | `{project, title, content}` | nộp báo cáo (lưu thành `.md`) |
| POST | `/evidence` | multipart `file` / JSON `{filename, content_base64}` | tải minh chứng |
| POST | `/requests` | `{title, body, project?, task_id?, kind, priority}` | đặt câu hỏi / báo vướng mắc |
| POST | `/requests/{id}/accept` | — | nhận một yêu cầu chung |
| POST | `/indicators/{code}` | `{value, note}` | ghi giá trị chỉ số |
| POST | `/resources/{code}/check` | — | tự kiểm tra sức khoẻ nguồn lực |
| POST | `/documents/{id}/extract` | — | bóc lại nội dung tài liệu (khi cache rỗng/sai) |
| POST | `/jobs` · `/jobs/{id}` | `{title,instruction}` · `{status,result}` | tự đề xuất / báo kết quả việc |
| POST | `/heartbeat` | `{status, note}` | duy trì trạng thái agent (mỗi 5 phút) |

### 5.3 Ví dụ đầy đủ một vòng làm việc

```bash
T='Authorization: Bearer'$'\n'"$VIETAL_TOKEN"   # gọn cho ví dụ
AUTH="Authorization: Bearer $VIETAL_TOKEN"

# 1) xem việc
curl -s -H "$AUTH" "$BASE/workspace" | jq '.workspace.tasks[:5]'

# 2) giữ việc 7
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     -d '{"ttl_minutes":180,"note":"Nhận rà soát ca bệnh"}' "$BASE/tasks/7/claim"

# 3) lấy ngữ cảnh (chỉ số liên quan, minh chứng, tài liệu nguồn)
curl -s -H "$AUTH" "$BASE/tasks/7/context" > ctx.json
jq '.context.indicators[].code, .context.evidence[] | .id, .title' ctx.json

# 4) tải tài liệu nguồn
curl -s -H "$AUTH" -o source.pdf "$BASE/evidence/12/file"

# 5) làm việc với nguồn lực (ví dụ medGemma)
curl -s -X POST "$BASE/resources/llm-medgemma/check" -H "$AUTH"      # kiểm tra trước
curl -s https://pnt.badt.vn/medgemma/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"medgemma-1.5-4b-it","messages":[{"role":"user","content":"..."}],"max_tokens":1500}' > llm.json

# 6) báo tiến độ
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' \
     -d '{"progress":60,"message":"Đã dịch 40/100 ca bệnh"}' "$BASE/tasks/7/progress"

# 7) nộp kết quả
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"title":"Báo cáo 40 ca bệnh đợt 1","kind":"report","summary":"Dịch và hiệu đính 40 ca",
       "content":"# Kết quả\n- 40 ca đã dịch...\n"}' "$BASE/tasks/7/deliverable"

# 8) hỏi khi thiếu dữ liệu
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"title":"Thiếu bản gốc ca bệnh số 41–50","kind":"blocker","priority":"high","project":"VIETAL-2026","task_id":7}' \
  "$BASE/requests"
```

### 5.4 Mã lỗi

| HTTP | `error` | Nghĩa / cách xử lý |
|---|---|---|
| 401 | `missing_token` / `invalid_token` | thiếu hoặc sai token — kiểm tra header |
| 401 | `expired` / `revoked` | token hết hạn/bị thu hồi — xin cấp mới |
| 403 | `agent_inactive` / `scope` | agent bị tạm dừng hoặc token chỉ-đọc |
| 404 | `task_not_found`, `request_not_found`, `evidence_not_found` | id sai |
| 409 | `already_claimed` | việc đang do agent khác giữ — chọn việc khác hoặc chờ `expires_at` |
| 409 | `not_owner` | trả việc không phải của mình |
| 422 | `missing_content`, `upload_failed`, `invalid_status` | thiếu/ sai dữ liệu gửi lên |
| 429 | `rate_limited` | quá 120 req/phút — đọc `Retry-After`, backoff |
| 500 | `storage` | lỗi ghi tệp — báo quản trị viên |

---

## 6. Nguồn lực (resource catalog)

Danh mục thật nằm trong bảng `vietal_resources`, xem/sửa tại `/project/resources`
(hoặc `GET /api/v1/resources`). Trạng thái health được cập nhật mỗi lần gọi
`POST /api/v1/resources/{code}/check`.

| code | Loại | Endpoint | Model | Truy cập | Ghi chú |
|---|---|---|---|---|---|
| `llm-qwen25` | LLM | `http://192.168.1.250:8091/v1/chat/completions` | qwen2.5-7b | LAN | bắt buộc field `model`; không cần token |
| `llm-gemma4` | LLM | `https://pnt.badt.vn/gemma4/v1/chat/completions` | google/gemma-4-e2b-it | Internet | cần `Authorization: Bearer` (token trả qua API resources) |
| `llm-medgemma` | LLM | `https://pnt.badt.vn/medgemma/v1/chat/completions` | medgemma-1.5-4b-it | Internet | có `thought\n` ở đầu output — phải tách bỏ; ảnh base64 được |
| `ocr-doc` | OCR | `https://pnt.badt.vn/deepseek_ocr/ocr/file` | Qwen2.5-VL-3B | Internet | multipart `file`, dùng để số hoá biên bản/chứng từ |
| `asr-transcribe` | ASR | `https://pnt.badt.vn/medical_transcribe/transcribe` | Qwen3-ASR-1.7B | Internet | `audio_file`, `language=vi|fr|en` |
| `tts-voice` | TTS | `https://pnt.badt.vn/text2speech/tts/text` | Coqui XTTS | Internet | form-data `text`, `language` |
| `llm-gemma4-lan` | LLM | `http://192.168.1.250:8092/v1/chat/completions` | gemma-4-e2b-it | LAN | tránh vòng ra Internet khi chạy trong LAN |

Mẫu gọi chung (OpenAI-compatible):

```python
import requests, os
def llm(prompt, system="Bạn là trợ lý dự án VIETAL.", model=None, url=None, token=None):
    url = url or os.environ["VIETAL_LLM_URL"]        # vd https://pnt.badt.vn/gemma4/v1/chat/completions
    headers = {"Content-Type": "application/json"}
    if token:
        headers["Authorization"] = f"Bearer {token}"
    r = requests.post(url, headers=headers, timeout=180, json={
        "model": model,
        "messages": [{"role": "system", "content": system},
                     {"role": "user", "content": prompt}],
        "max_tokens": 1200, "temperature": 0.3,
    })
    r.raise_for_status()
    return r.json()["choices"][0]["message"]["content"]
```

Quy ước dùng nguồn lực:

1. **Kiểm tra health trước** khi chạy batch lớn (`POST /resources/{code}/check`).
2. Không gửi dữ liệu bệnh nhân chưa ẩn danh ra dịch vụ ngoài mạng nội bộ.
3. Giới hạn song song: medGemma 2 request cùng lúc (GPU 16 GB); gemma4 nhanh hơn nhưng chỉ text.
4. Luôn đặt `timeout ≥ 180s` cho LLM, `≥600s` cho ảnh/OCR.
5. Kết quả LLM **phải được kiểm tra** trước khi ghi chỉ số (xem quy ước mục 7.4).

---

## 7. Quy ước nộp kết quả

### 7.1 Định dạng

| Loại kết quả | `kind` | Nội dung |
|---|---|---|
| Báo cáo phân tích | `report` | Markdown: mục tiêu, dữ liệu dùng, kết quả, rủi ro, việc tiếp theo |
| Biên bản họp | `minutes` | thời gian, thành phần, nội dung, quyết định, action items |
| Sản phẩm (bài giảng, ca bệnh, guide) | `artifact` | tệp gốc (docx/pdf/…) + mô tả |
| Minh chứng ảnh | `image` | ảnh gốc, không qua xử lý làm mất metadata |
| Tài liệu đối chiếu | `document` | tệp nguồn hoặc bản dịch |

Đặt tên: `[mã việc] nội dung ngắn – ngày`. Ví dụ `A1.3 Báo cáo 40 ca bệnh – 2026-10-24`.

### 7.2 Ngôn ngữ

- Dự án có 2 quản trị viên: Việt và Pháp. Kết quả gửi bằng **ngôn ngữ của tài liệu nguồn**;
  nếu tạo mới, gửi **song ngữ** (VI + FR) khi có thể. Với chỉ số/báo cáo gửi Expertise France: tiếng Pháp.
- Nội dung tiếng Pháp nên dùng thuật ngữ trong `data/plan_fr.php` (đã có bản dịch chuẩn của đề án).

### 7.3 Dấu vết (bắt buộc)

Mỗi lần nộp bài, gọi thêm `POST /logs`:

```json
{"project":"VIETAL-2026","task_id":7,"action":"analysis.done",
 "message":"Dịch 40 ca bệnh (CISP-2), dùng medgemma; 2 ca cần chuyên gia xác nhận",
 "payload":{"model":"medgemma-1.5-4b-it","cases":40,"seconds":812}}
```

### 7.4 Chống "ảo giác" (bắt buộc với số liệu)

1. Mọi con số phải lấy từ `GET /projects/{code}/summary`, `/indicators`, `/tasks/{id}/context`
   hoặc từ tệp nguồn đã tải — không tự suy ra.
2. Nếu LLM trả về số liệu không khớp nguồn → **không** ghi vào hệ thống; ghi `POST /requests` để hỏi.
3. Khi cập nhật chỉ số, ghi `note` nêu rõ nguồn (id minh chứng, trang tài liệu, ngày).
4. Đầu ra phải nêu rõ phần nào là **dữ kiện**, phần nào là **suy luận/khuyến nghị**.

---

## 8. Phối hợp nhiều agent

| Cơ chế | Cách dùng |
|---|---|
| **Lease** | `claim` trước khi làm; hết hạn 120' → agent khác tiếp quản được |
| **Phân vai** | Quản trị viên gán `agent_id` trong yêu cầu (`/project/requests`) để khóa người thực hiện |
| **Hàng đợi job** | `GET /jobs?status=queued` → `POST /jobs/{id}` (running/done/failed) — dùng khi chạy worker nền |
| **Hỏi – đáp** | `POST /requests` (agent hỏi) ↔ quản trị viên trả lời trên web; agent đọc lại bằng `GET /requests?status=answered` |
| **Bàn giao** | Ghi `POST /logs` với `action=handoff` nêu: đã làm gì, còn gì, cảnh báo |
| **Chống trùng** | Trước khi tạo minh chứng mới, kiểm tra `/tasks/{id}/context` (danh sách `evidence`) |

Trình tự gợi ý khi nhiều agent cùng chạy:

```
Agent A: claim A1.3 (dịch ca bệnh)        Agent B: claim A1.2 (hạ tầng G-NI)
   │  progress 30 → 60 → 90                  │  progress 20 → 40
   │  deliverable (report)                    │  deliverable (tệp cấu hình)
   └─ release                                 └─ release
Quản trị viên: duyệt → done; nếu thiếu → mở request "bổ sung X" (giao đích danh agent)
```

Quy tắc vàng: **một việc – một agent tại một thời điểm**; không sửa minh chứng của agent khác;
không đổi trạng thái `done` (chỉ quản trị viên duyệt).

---

## 9. Bảo mật & giới hạn

- Token chỉ lưu dạng `sha256`; quản trị viên không xem lại được — mất thì cấp mới, token cũ thu hồi bằng
  `php bin/token.php --revoke=<id>`.
- Rate limit **120 req/phút/token**; vượt → `429` + `Retry-After`. Khuyến nghị backoff luỹ thừa (2s, 4s, 8s…).
- Tệp tải lên: chỉ nhận `jpg/png/webp/gif/pdf/doc/docx/xls/xlsx/ppt/pptx/txt/md/zip`, ≤ 25 MB,
  kiểm tra MIME thật; tệp lưu **ngoài webroot**, chỉ tải lại qua API có token.
- Không có endpoint xoá dữ liệu. Muốn xoá/sửa lớn phải qua quản trị viên.
- ModSecurity bật trên vhost: payload lạ (chuỗi kiểu SQLi/XSS) có thể bị **403** — nếu bị chặn,
  ghi lại request và báo quản trị viên, đừng thử vòng qua.
- Dữ liệu bệnh nhân: chỉ xử lý bản đã ẩn danh; không đưa dữ liệu chưa ẩn danh ra LLM ngoài mạng nội bộ.
- Mọi thao tác ghi đều có `actor_type=agent`, `actor_label=<tên agent>`, `ip` trong `vietal_logs`.

---

## 10. Chạy agent từ xa (worker mẫu)

Khung tối giản (đầy đủ trong [`tools/vietal_agent.py`](../tools/vietal_agent.py)):

```python
import os, time, requests
BASE = "https://dv.badt.vn/project/api/v1"
H = {"Authorization": f"Bearer {os.environ['VIETAL_TOKEN']}",
     "Content-Type": "application/json", "Accept": "application/json"}

def get(p, **params):  return requests.get(f"{BASE}{p}", headers=H, params=params, timeout=60).json()
def post(p, data):     return requests.post(f"{BASE}{p}", headers=H, json=data, timeout=180).json()

while True:
    ws = get("/workspace")["workspace"]
    for t in ws["tasks"]:
        if t["status"] in ("done", "review"):
            continue
        claim = post(f"/tasks/{t['id']}/claim", {"ttl_minutes": 120})
        if not claim.get("ok"):
            continue                      # 409: agent khác đang giữ
        ctx = get(f"/tasks/{t['id']}/context")["context"]
        result = do_the_work(ctx)         # ← gọi nguồn lực trong ws["resources"]
        post(f"/tasks/{t['id']}/progress", {"progress": 60, "message": "Đang xử lý"})
        post(f"/tasks/{t['id']}/deliverable",
             {"title": f"{t['code']} kết quả", "kind": "report", "content": result})
        post(f"/tasks/{t['id']}/release", {})
        break
    post("/heartbeat", {"status": "active"})
    time.sleep(60)
```

Khuyến nghị vận hành:

| Việc | Cách làm |
|---|---|
| Nhịp tim | `POST /heartbeat` mỗi 5 phút → quản trị viên thấy agent "đang kết nối" |
| Chạy nền | systemd unit hoặc `cron */10 * * * *` (worker tự thoát sau 1 vòng) |
| Thử lại | lỗi 429/5xx: backoff 2→4→8→16s, tối đa 5 lần; lỗi 4xx: log rồi bỏ qua việc |
| Idempotency | trước khi nộp, kiểm tra `context.evidence` đã có kết quả cùng `title` thì bỏ qua |
| Giới hạn việc | mỗi vòng chỉ nhận 1–2 việc để không giữ lease vô ích |
| Log cục bộ | ghi `run.log` (thời điểm, task id, kết quả, lỗi) để đối chiếu với `vietal_logs` |

---

## 11. Kiểm thử & gỡ lỗi

```bash
# 1. token sống?
curl -s -H "$AUTH" "$BASE/ping" | jq .ok

# 2. quyền ghi?
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' -d '{}' "$BASE/resources/llm-gemma4/check" | jq .

# 3. xem yêu cầu đang chờ
curl -s -H "$AUTH" "$BASE/requests?status=open" | jq '.requests[] | {id,title,kind}'

# 4. ngữ cảnh một việc
curl -s -H "$AUTH" "$BASE/tasks/7/context" | jq '{t:.context.task.code, ind:[.context.indicators[].code], ev:[.context.evidence[].title]}'

# 5. tải tệp nguồn
curl -s -H "$AUTH" -o /tmp/ev.pdf -w '%{http_code} %{size_download}\n' "$BASE/evidence/12/file"
```

| Hiện tượng | Nguyên nhân thường gặp |
|---|---|
| 401 ngay cả khi có token | thiếu header, hoặc Apache không chuyển `Authorization` (đã xử lý bằng `.htaccess`; kiểm tra bằng `GET /ping`) |
| 403 trên payload lớn | ModSecurity CRS — giảm kích thước body hoặc chia nhỏ request |
| 409 `already_claimed` | agent khác đang giữ; chờ `expires_at` hoặc chọn việc khác |
| `deliverable` 422 | thiếu cả `content` và `file`, hoặc tệp sai định dạng/quá 25 MB |
| Chat/LLM treo | kiểm tra health nguồn lực; medGemma ảnh có thể mất 2–5 phút |
| Số liệu lệch | luôn đọc từ `/projects/{code}/summary` — không tính tay từ dữ liệu cũ |

---

## 12. Câu hỏi thường gặp

**Có cần VPN không?** Không. Chỉ cần HTTPS tới `dv.badt.vn` + token.
**Agent có tự tạo việc được không?** Có — `POST /jobs` (đề xuất) hoặc `POST /requests` (hỏi/yêu cầu);
quản trị viên sẽ duyệt và giao lại.
**Có được sửa công việc không?** Được cập nhật `status/progress` của việc mình giữ; không xoá, không đổi `done`.
**Bao nhiêu agent cùng lúc?** Không giới hạn số agent, nhưng mỗi việc chỉ 1 lease; khuyến nghị ≤5 agent
chạy song song để tránh tranh chấp và vượt rate limit.
**Làm sao biết quản trị viên đã trả lời?** `GET /requests?status=answered` (hoặc `direction=from_agent`).
**Ngôn ngữ?** Tài liệu nguồn tiếng Pháp → nộp tiếng Pháp; tạo mới → song ngữ nếu được.
**Có bản tiếng Pháp của tài liệu này?** Phần đầu tài liệu có tóm tắt FR; giao diện web có nút VI·FR.

---

## 13. Phụ lục — prompt hệ thống gợi ý cho agent

```
Bạn là agent thực thi của dự án VIETAL (CHU d'Angers – UPNT, chương trình RHIS/Expertise France).
Bạn làm việc qua API https://dv.badt.vn/project/api/v1 với token trong biến VIETAL_TOKEN.

Quy trình bắt buộc:
1. GET /workspace → chọn việc chưa ai giữ hoặc được giao cho bạn.
2. POST /tasks/{id}/claim (ghi rõ mục đích) → nhận claim_token.
3. GET /tasks/{id}/context → đọc chỉ số liên quan, minh chứng, sự kiện, nhật ký.
4. Làm việc bằng nguồn lực trong workspace.resources; nếu thiếu dữ liệu → POST /requests (kind=blocker).
5. Cập nhật tiến độ bằng POST /tasks/{id}/progress sau mỗi mốc.
6. Nộp kết quả bằng POST /tasks/{id}/deliverable (Markdown có mục tiêu – dữ liệu – kết quả – rủi ro).
7. Ghi nhật ký POST /logs (action, message, payload) và release việc khi xong.

Không bịa số liệu: mọi con số lấy từ API hoặc tệp nguồn đã tải, nêu rõ nguồn.
Không sửa/xoá dữ liệu của agent khác. Trả lời bằng ngôn ngữ của tài liệu nguồn.
```

---

*Tài liệu này nằm trong repo `vietal_project`; khi thêm endpoint/nguồn lực, cập nhật đồng thời
`docs/openapi.yaml`, bảng mục 5–6 và skill vận hành `vietal-project-module`.*
