LumiBaseDocs

Agent Harness Layer

LumiBase định vị thế hệ tiếp theo không chỉ là headless CMS cho con người, mà là control plane để AI Agent làm việc cùng con người trên dữ liệu, schema, workflow và artifact của business.

1. Định nghĩa sản phẩm

Harness là lớp bao quanh agent để agent không chạy tự do: nó nhận mục tiêu, được cấp context/quyền hạn, gọi tool theo hợp đồng chuẩn, bị quan sát, được đánh giá, cần approval khi rủi ro cao, và ghi lại kết quả để có thể audit/retry.

LumiBase for AI is not just a CMS where humans manage content. It is a structured operating layer where humans, agents, data, workflows, and applications co-evolve.

Nói ngắn gọn: LumiBase là AI-native backend operating system — nơi agent hiểu thế giới business qua schema/content, nhận nhiệm vụ, bị giới hạn bởi governance, rồi trả kết quả thành artifact có thể dùng lại.

2. Những điểm học từ Directus

Directus có nhiều mảnh nền tảng phù hợp để làm CMS cho AI: database-first data model, Data Studio, Roles/Policies/Permissions, Flows/Operations, REST/GraphQL generated API, file library và extension system. Các nguồn chính thức cần được dùng làm baseline khi thiết kế parity/improvement:

LumiBase không sao chép Directus. LumiBase giữ phần tốt của CMS/database-first nhưng thêm Agent Harness Layer làm lớp vận hành chính cho agent.

3. Kiến trúc 3 tầng

text
1. CMS Layer
   └─ schema, content, files, users, roles, policies, permissions, revisions

2. Agent Harness Layer
   └─ goals, runs, plans, tools, memory, approvals, evaluations, audit trail

3. App Generation Layer
   └─ generated apps, pages, components, datasets, API specs, migrations, docs

Luồng chuẩn:

text
Goal
→ Context package
→ Plan
→ Tool calls
→ Validation & evaluation
→ Human approval if needed
→ Commit artifact/result back to LumiBase
→ Audit trail & memory update

4. Các collection hệ thống đề xuất

Các bảng hiện có (ai_approvals, ai_conversations, ai_messages, ai_embeddings) là bước đầu của harness. Lộ trình nên mở rộng thành các system collections sau:

CollectionMục đíchGhi chú governance
agent_goalsMục tiêu business do người dùng hoặc workflow tạoCó owner, priority, deadline, status
agent_runsMột lần thực thi goal/taskGắn model/provider, budget, status, started/finished
agent_plansPlan dạng steps trước khi gọi toolCó thể require approval trước khi execute
agent_toolsRegistry tool/API/extension mà agent được phép gọiKhai báo capability, input schema, rate limit
agent_tool_callsLog từng tool call/input/output/errorMask secrets, lưu latency/cost
agent_memoryMemory dài hạn ngoài conversationCó scope, expiry, source, confidence
agent_artifactsKết quả agent tạo ra: page, component, dataset, config, prompt, migration, API specVersioned, reviewable, link tới collection/item
agent_evaluationsKết quả validate/eval outputDùng policy, test, lint, schema diff, hallucination checks
agent_approvalsApproval tổng quát cho plan/tool/artifactCó approver, decision, reason, expiry
agent_permissionsMapping agent/role/policy/capabilityKhông cấp quyền trực tiếp qua prompt

5. Contract execution

Mỗi lần agent chạy phải có envelope tối thiểu:

json
{
  "goalId": "goal_...",
  "runId": "run_...",
  "agent": "lumibase-copilot",
  "context": {
    "siteId": "site_...",
    "collections": ["products", "orders"],
    "policySnapshot": "sha256:..."
  },
  "budget": {
    "maxToolCalls": 20,
    "maxCostUsd": 2,
    "timeoutMs": 30000
  },
  "risk": "safe | review_required | dangerous",
  "approvalPolicy": "none | before_execute | before_commit",
  "artifacts": []
}

Nguyên tắc:

  • Tool chỉ chạy nếu được khai báo trong registry và capability của agent/session thoả mãn.
  • Prompt không thể tự nâng quyền; quyền đến từ policy snapshot.
  • Kết quả sinh ra không ghi thẳng vào content/schema nếu vượt risk threshold.
  • Mọi tool call và artifact đều có site_id, audit metadata, correlation id.
  • Harness phải hỗ trợ replay/retry idempotent cho run thất bại.

5.1. Quyết định một approval: claim, execute, quarantine

Approve không phải là đổi trạng thái — nó thực thi hành động đã lưu. Vì vậy đường quyết định gồm ba bước, claim → execute → finalize, và mỗi bước tồn tại vì một cách mà bản làm đơn giản sẽ sai:

  • Claim. Quyết định trước tiên chuyển dòng sang deciding, bằng một conditional update guard trên pending. Kiểu read-rồi-act sẽ để hai approval đồng thời cùng qua bước đọc và cùng chạy hành động.
  • Execute. Claim được giữ trong đúng một lần thực thi skill. Mọi đường không hoàn tất đều tự nhả claim — skill lỗi, kill switch, cancel, hay một exception.
  • Finalize. Chỉ một lần thực thi hoàn tất mới ghi approved.

Một lỗi mà process sống sót qua được sẽ không quay về pending. Nếu skill đã chạm tới một service trước khi lỗi thì side effect có thể đã tồn tại, và đưa nó trở lại inbox như việc bình thường là mời gọi một side effect thứ hai. Những ca đó vào failed — bị cách ly, ra khỏi inbox, và chỉ chạy lại được qua một bước có con người tham gia.

Điều mà không handler in-process nào che được là process chết giữa lúc thực thi: crash, bị OOM kill, Worker bị evict, hay một lần deploy cuốn pod đi. Dòng đó sẽ ở deciding mãi mãi, và vì inbox filter theo pending nên nó cũng biến mất khỏi tầm mắt — vừa kẹt vừa vô hình. Một sweep định kỳ (sweepStaleApprovalClaims, cửa sổ 15 phút) là lưới an toàn. Nó cũng đưa các dòng đó vào failed chứ không phải pending: một cú crash nói "không có quyết định nào được ghi", chứ không nói "không có gì xảy ra" — nên một lần thực thi bị crash ít nhất cũng mơ hồ như một lần lỗi in-process, và phải qua cùng một cửa.

Thời gian đã trôi qua không là bằng chứng công việc bị bỏ rơi đã dừng. Một timeout của JavaScript reject một promise mà không cancel handler phía sau, và một process đã crash có thể để lại một request đang bay ở provider bên ngoài. Cửa sổ chỉ giới hạn hệ thống chờ bao lâu, không bao giờ giới hạn điều nó kết luận.

5.2. Phục hồi một approval bị cách ly

POST /api/v1/agent/approvals/:id/reopen với { reason } đưa một approval failed trở lại pending. Nó đòi đúng capability approvals:decide như khi quyết định, vì reopen chính là thứ làm hành động có thể thực thi lại. Bước chuyển trạng thái và audit record approval.reopened của nó commit cùng nhau: ghi nhận ai đã cho phép một lần thực thi thứ hai là một phần của sự cho phép đó, không phải một dòng log có thể có mà cũng có thể không.

Trong Studio, tab Approvals nêu rõ có bao nhiêu approval bị ngắt giữa đường, hiện lý do đã ghi cho từng cái, và chỉ đưa nút Reopen ở đúng những dòng đó — một approval pending là việc bình thường, không có affordance phục hồi nào. Lý do là bắt buộc: đó là điều con người tuyên bố mình đã kiểm chứng, và nó được lưu cùng bước chuyển trạng thái.

Chỉ failed mới reopen được. Một approval đã quyết định thì không được hồi sinh, còn một dòng deciding thuộc về một lần thực thi đang sống hoặc thuộc về sweeper.

5.3. Thử lại một run

POST /api/v1/agent/runs/:id/retry chạy lại một run failed hoặc cancelled dưới dạng một run mới ở trạng thái queued, có retryOfRunId trỏ về run gốc, và đưa nó vào hàng đợi agent-runs — cùng claim của worker, cùng harness, approval và kill switch như mọi run async. Tác vụ được khôi phục từ tool call mà run đã ghi lại, còn envelope quản trị (role, intent, autonomy cap, budget) lấy từ goal của nó; lần thử lại chạy với quyền của người yêu cầu thử lại, được resolve lại khi worker nhận job, không bao giờ mượn quyền của người yêu cầu ban đầu. Chỉ lần thử mới nhất của goal mới được thử lại, và chỉ khi goal không còn run nào đang chạy, nên một request sinh ra nhiều nhất một lần thực thi mới: các request thử lại đồng thời được tuần tự hoá trên hàng goal và bên thua nhận 409.

Phản hồi: 201 kèm { goalId, runId, agentName, status: 'queued', retryOfRunId }; 404 cho run không tồn tại hoặc thuộc tenant khác; 409 cho RUN_NOT_RETRYABLE, RUN_ACTIVE, RUN_EFFECT_RECORDED (một tool call của run đã được ghi executed, tức tác động đã xảy ra), RETRY_SUPERSEDED, GOAL_CLOSED, GOAL_BUSY, INTENT_NOT_ACTIVE hoặc RETRY_UNRECOVERABLE (input đã ghi có giá trị secret bị che, hoặc run không ghi tool call nào); 423 FROZEN; 400 ASYNC_UNAVAILABLE; 503 ENQUEUE_FAILED, khi đó run thử lại được chốt ở failed. Một run bị cách ly với stale_unverified có thể đã tạo tác dụng rồi — thử lại nó là quyết định có chủ ý của con người để chạy lại, và được ghi là agent_run.retried trong activity.

5.4. Hỏi người dùng: askUser (#710)

Một agent không thể đi tiếp nếu thiếu một quyết định mà nó không được phép tự đưa ra thì gọi tool askUser thay vì đoán. Run tạm dừng, một người trả lời trong inbox của Mission Control, và run tiếp tục với câu trả lời làm kết quả của tool. Đây là cùng vòng đời với một approval đang chờ, không phải một vòng đời song song.

askUser và getUserAnswer được cung cấp cho các agent có quản trị — agent run, queue worker agent-runs và MCP — và không cho Copilot chat (POST /api/v1/ai/chat). Chat thực thi một tool call mỗi lượt và không có run nào để tạm dừng rồi tiếp tục, nên danh sách tool của nó (chatToolSkills() trong llm-provider.ts, cũng dùng cho ngân sách context) bỏ cả hai ra.

Input (contract chuẩn askUser trong @lumibase/contracts, giới hạn nằm ở ASK_USER_LIMITS): question (1–1000 ký tự), options tùy chọn (2–10 lựa chọn, mỗi lựa chọn 200 ký tự, được trim và phải khác nhau sau khi trim — chúng được so với một câu trả lời đã trim), allowFreeText (mặc định true; false bắt buộc có options và câu trả lời phải là một trong số đó), context (≤ 2000 ký tự) và timeoutMinutes (1–10080, mặc định 1440 = một ngày). Capability bắt buộc: items:read — hỏi không có side effect, nên nó không nằm trên thang autonomy và được phép ở mọi mức, kể cả L0.

Vòng đời. Một câu hỏi là một dòng agent_approvals với kind = 'question' (cạnh approval, veto, promotion); không có bảng mới, không có migration.

BướcRunCâu hỏiTool call askUserAudit (activity)
hỏiqueued/running → waiting_userpending, có expires_atwaiting_useragent_question.asked
trả lờiwaiting_user → succeeded (stopReason: answered)answered; câu trả lời ở decision_reason, decided_by, decided_atexecuted, câu trả lời là outputagent_question.answered
hết hạn→ failed (stopReason: question_timeout)expiredfailedagent_question.expired
huỷ / kill switch→ cancelled (stopReason của lệnh huỷ, frozen khi đóng băng)cancelleddeniedagent_question.cancelled

Hỏi, trả lời và hết hạn mỗi việc là một transaction ngắn với các update có điều kiện. Khi hỏi, việc chuyển run, ghi câu hỏi và đánh dấu tool call askUser là waiting_user nằm trong cùng một transaction, trước mọi thông báo, nên một câu trả lời tới ngay sau khi commit không bao giờ bị ghi đè. Một run đang chờ chỉ rời waiting_user qua câu hỏi của nó (trả lời, hết hạn, huỷ): một lệnh close hoặc fail chung chung — ví dụ một worker ném lỗi sau khi việc đỗ đã commit — và việc đỗ nó vào một approval đều bị từ chối, nên câu hỏi không bao giờ bị bỏ lại pending dưới một run đã kết thúc. Một run đang chờ không giữ queue worker nào (worker agent-runs trả về ngay khi harness đã đỗ run) và không giữ khoá database nào. Với dispatcher, nó vẫn đang chạy (waiting_user nằm trong cùng tập in-flight với awaiting_approval), nên goal không nhận run thứ hai trong lúc chờ, và POST /agent/runs/:id/retry từ chối nó.

Tiếp tục. Một run của harness là một tool call có quản trị, nên tiếp tục nghĩa là lời gọi askUser đang đỗ hoàn tất với câu trả lời làm kết quả và run chốt ở succeeded. Agent làm gì với câu trả lời là tool call kế tiếp của nó, được phân quyền riêng. Agent đọc câu trả lời bằng tool getUserAnswer ({ questionId }), chỉ principal hoặc agent role đã hỏi mới đọc được (hoặc một grant admin; còn lại là NOT_FOUND). Câu trả lời tới model như dữ liệu không tin cậy: được bọc bằng untrustedBlock('ask-user-answer', …) kèm UNTRUSTED_CONTENT_RULE, cả trong output của tool call lẫn kết quả getUserAnswer. Một người đã gõ nó, nhưng ô trả lời cũng là một input như mọi input khác.

Ai được trả lời (POST /api/v1/agent/questions/:id/answer, nằm sau control-plane guard như phần còn lại của /api/v1/agent). Chỉ một user đã đăng nhập mới trả lời được. Mọi API key — scope site hay scope organization, dù mang capability gì — đều bị từ chối với 403 trước mọi kiểm tra khác: key là cách một agent hành động, và agent không được tự trả lời câu hỏi của chính nó (một organization key được resolve như control-plane admin, nên nếu không chặn nó sẽ lọt qua như một approver mà audit trail không có người nào). Trong số các user:

  • người giữ approvals:decide, hoặc một control-plane admin — những operator vốn đã được tin để gỡ một run đang đỗ, và là đường duy nhất cho run của reconciler, vốn không có người yêu cầu là người;
  • người yêu cầu của run, khi người đó là một user vẫn còn resolve được trên site.

Hiện tại chỉ quản trị viên site tới được route này: control-plane guard đứng trước /api/v1/agent không cho ai khác qua, và một quản trị viên vốn đã được tính là approver. Vì vậy quy tắc người yêu cầu chưa thể chạm tới; nó có hiệu lực khi backlog B207 đưa route trả lời ra khỏi control plane.

Câu trả lời dài 1–2000 ký tự, đã trim; với allowFreeText: false nó phải là một trong các options (400 ANSWER_NOT_AN_OPTION). Việc claim dòng pending và việc tiếp tục run nằm trong một transaction, nên câu trả lời thứ hai nhận 409 ALREADY_ANSWERED và không bao giờ tiếp tục run lần thứ hai. Trước khi tiếp tục, quyền của người yêu cầu được resolve lại (#472): người yêu cầu đã mất quyền khiến run bị fail (stopReason: requester_revoked) và nhận 409 REQUESTER_REVOKED. Các từ chối khác: 404 (id không tồn tại hoặc của tenant khác), 409 EXPIRED (route trả lời tự chốt một câu hỏi quá hạn), 409 QUESTION_CLOSED (đã huỷ), 409 RUN_NOT_WAITING, 423 FROZEN.

Hết hạn. agent-question-sweep (cron Docker mỗi 5 phút, và cron trigger 5 phút trên Cloudflare) cho hết hạn mọi câu hỏi pending đã qua expires_at và fail run của nó với question_timeout, giải phóng goal cho dispatcher (goal của reconciler khi đó bị chặn với RUN_FAILED, không bao giờ tự hỏi lại). Run đã fail có thể thử lại như mọi run khác; lần thử lại sẽ hỏi lại câu hỏi.

Kill switch. Một agent đang chạy gặp lệnh đóng băng ở ranh giới tool call kế tiếp; một run đang chờ thì không còn ranh giới nào, nên đóng băng một role hoặc cả site, và tạm dừng một intent, sẽ huỷ các run đang chờ trong phạm vi đó (stopReason: frozen) và đóng câu hỏi của chúng. Phạm vi run (cancel run) đóng câu hỏi qua đúng lệnh huỷ đó. Một câu trả lời chạy đua với lệnh đóng băng bị từ chối với 423 FROZEN và run bị huỷ. Một agent đã bị đóng băng thì không hỏi được ngay từ đầu.

Approval không phải câu hỏi. GET /api/v1/agent/approvals loại các dòng kind = 'question'; POST /approvals/:id/decide và /reopen trả 409 NOT_AN_APPROVAL cho id của câu hỏi; agent reviewer từ chối chúng với 403 HUMAN_ONLY.

MCP. Một tools/call tới askUser trả về một tool result bình thường (không bao giờ là lỗi JSON-RPC, isError: false) với status: "waiting_user", questionId và runId — cùng quy tắc hình dạng như pending_approval với approvalId.

Metric autonomy. lumibase_agent_questions_total{status} (asked | answered | expired | cancelled) và lumibase_agent_question_wait_seconds{status} đếm câu hỏi như những lần con người can thiệp; run được trả lời được đếm trong lumibase_agent_runs_total với stop_reason="answered", hết hạn với question_timeout. Trust ledger hiển thị questions: { asked, answered, expired } trong bằng chứng của một đề xuất thăng cấp; đó là bằng chứng cho người quyết định, không phải một cổng chặn — một câu hỏi không được trả lời vốn đã làm đứt chuỗi run thành công vì run của nó kết thúc failed.

Multi-tenancy. Cô lập theo tenant: dòng câu hỏi (agent_approvals, site_id, vốn đã nằm dưới RLS site_isolation), run và tool call của nó, các dòng audit, các route liệt kê/đọc/trả lời (mọi query lọc site_id; id của site khác là 404) và thông báo (fan-out lọc theo siteId). Dùng chung toàn deployment: chỉ có sweep, quét qua các site trên system connection và chốt từng dòng trong phạm vi site của chính nó. Được kiểm bằng agent-ask-user.db.integration.test.ts (hai site trên PostgreSQL thật).

Thông báo. Khi hỏi, harness phát một agent notification loại question với deep link tới /mission-control/inbox?entry=question:<id>; phần body mang câu hỏi đã được che giống hệt input tool đã lưu. Queue worker agent-runs truyền một sink Web Push chỉ cho approval và question, nên câu hỏi của một run nền tới được người dùng mà không cần mở tab Studio; run trong hàng đợi vẫn không gửi push run succeeded/failed (hay sự kiện vòng đời nào khác). Việc gửi là best effort: trên Workers nó được giữ sống bằng waitUntil của queue consumer, trên Docker worker chờ nó xong, và một lần gửi lỗi không bao giờ làm fail run.

6. App Generation Layer

Khi người dùng yêu cầu “build storefront”, agent không bắt đầu từ trang trắng. Nó đọc schema/content/policies trong LumiBase:

text
collections: products, orders, customers
policies: public read products, customer owns orders
prompt/spec: build storefront
agent goal: generate frontend app from schema
agent tasks:
  - generate page/component artifact
  - create API integration docs
  - seed sample content
  - evaluate missing descriptions/images
  - request approval for schema changes

Artifact được commit ngược về LumiBase để con người review, version, publish hoặc rollback.

MVP hiện tại trả 4 artifact từ /api/v1/agent/generate-app: page_spec, component_spec, seed_data, api_spec. Publish idempotent, artifact đã publish có thể rollback, và schema/migration artifact fail evaluation không được publish nếu không có override reason.

6.1. Runtime limitations & operations

  • Cloudflare Workers: route CMS và service Drizzle-backed chạy trong Worker runtime; evaluation runner MVP giữ ngắn và synchronous để tránh vượt request runtime.
  • Docker / Node.js: cùng API và service chạy qua Docker runtime, dùng BullMQ/Redis khi cần queue.
  • Queues: run fail lặp lại dùng runtime QueueProvider để enqueue agent-dead-letter; nếu không có queue adapter, audit trail vẫn nằm trong agent_runs và agent_tool_calls.
  • Observability: Prometheus metrics bao phủ run status, stop reason, tool latency, approval latency, evaluation status, token/cost estimate và dead-letter enqueue rate. Docker mode auto-load dashboard Grafana LumiBase Agent Harness.

7. Roadmap ứng dụng vào LumiBase

Roadmap chi tiết theo checklist nằm ở Roadmap triển khai Agent Harness Layer. Tóm tắt các chặng chính:

  1. Lifecycle DB + service — thêm agent_goals, agent_runs, agent_plans, agent_tool_calls và AgentRunService để mọi hành động agent có trạng thái, audit và retry.
  2. Tool Registry — nâng CORE_SKILLS thành registry có input/output schema, capabilities, rate limits, risk policy và owner.
  3. Approval tổng quát — mở rộng HITL từ skill nguy hiểm sang plan/tool/artifact approval, có diff/eval summary trước khi duyệt. Item CRUD nay cũng được phân loại theo tác động (#578): createItem với status: 'published', updateItem đổi status của item, và updateItem trên item đang published đi qua cùng approval và autonomy gradient như một skill nguy hiểm; ghi draft không đổi. Xem governed tool contract §3a.
  4. Artifact Store — thêm agent_artifacts để output không chỉ là text chat mà là page/component/dataset/config/migration/API spec versioned.
  5. Evaluation Gate — thêm eval trước khi commit artifact: schema validation, permission diff, migration dry-run, generated app smoke test, policy lint.
  6. Memory có kiểm soát — xây RAG/memory theo scope, provenance, expiry, field mask và redaction.
  7. App Generation MVP — kết nối schema/content/policy → generator → artifact → eval → approval → publish/rollback cho demo e-commerce đầu tiên.

8. Success metrics

  • 100% agent runs có audit trail đầy đủ: goal, plan, tool calls, approvals, artifact hashes.
  • 0 hành động schema/delete chạy ngoài approval policy.
  • ≥80% artifact generated có evaluation result trước khi admin review.
  • Median time từ schema có sẵn đến generated app scaffold < 5 phút.
Last modified: 15/11/2026