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 |
| 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 |
| Worker mẫu | 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) |
---
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).
---
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.
---
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:
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.
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"}
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$BASE/workspace?project=VIETAL-2026" | jq .
Trả về:
{
"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ữ.
---
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ị.
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).duplicate: true kèm id bản ghi trước; muốn xử lý lại thì gửi {"force": true}.model cho biết deepseek-chat · 3 khối. ┌────────────┐ 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:
claim, server trả claim_token + claim_expires_at (mặc định 120 phút, tối đa 24 h).claim khi lease còn hiệu lực → 409 already_claimed kèm expires_at.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).---
Tất cả endpoint dưới /project/api/v1 (tổng 32). Quyền: read (mọi token) / write (token có scope write).
| 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…) |
| 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) |
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"
| 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 |
---
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):
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).
---
| 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.
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.
data/plan_fr.php (đã có bản dịch chuẩn của đề án).Mỗi lần nộp bài, gọi thêm POST /logs:
{"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}}
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ị.
---
| 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).
---
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>.
429 + Retry-After. Khuyến nghị backoff luỹ thừa (2s, 4s, 8s…).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.
ghi lại request và báo quản trị viên, đừng thử vòng qua.
actor_type=agent, actor_label=<tên agent>, ip trong vietal_logs.---
Khung tối giản (đầy đủ trong tools/vietal_agent.py):
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 |
---
# 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ũ |
---
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.
---
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.*