GoClaw v3 — Intelligence: Trí Tuệ & Phối Hợp

Ba Trụ Cột

Intelligence Layer

Ba hệ thống phối hợp nhau — agent tự cải thiện, biết giao việc cho đúng người, và tra cứu tri thức chính xác.

Vấn đề thực tế

"Agent phục vụ hàng trăm phiên mỗi ngày, nhưng admin phải điều chỉnh thủ công dựa trên cảm tính. Nếu agent tự biết nó yếu ở đâu và tự cải thiện thì sao?"

Quy trình 3 giai đoạn

Thu Thập

Chỉ đọc · An toàn

Thu thập metrics hiệu suất sau mỗi lần chạy — không thay đổi gì, chỉ quan sát và ghi lại. Dữ liệu được lưu vào bảng agent_evolution_metrics.

Chất lượng truy xuất Hiệu quả tool calls Phản hồi user Token efficiency Thời gian phản hồi

Đề Xuất

Admin duyệt

Phân tích xu hướng metrics qua pluggable rules — tạo đề xuất cụ thể, có ưu tiên, có lý do. Admin xem xét và phê duyệt trước khi áp dụng. Không có gì thay đổi mà không có người duyệt.

💡

Ví dụ: "Tool web_search thất bại 40% → thêm retry" | "Memory retrieval thấp → tăng top_k từ 5 lên 10"

Lưu vào agent_evolution_suggestions Priority cao / trung / thấp

Tự Thích Ứng

Guardrails + Rollback

Agent tự áp dụng thay đổi đã được duyệt, nhưng trong giới hạn cứng. Hệ thống snapshot trước mỗi thay đổi và tự động rollback nếu metrics giảm quá ngưỡng.

🛡️

Guardrails

Giới hạn số thay đổi/ngày · Whitelist loại thay đổi · Ngưỡng metrics tối thiểu · Cấm đổi core config

↩️

Auto-Rollback

Nếu metrics giảm quá ngưỡng → tự động hoàn tác. Snapshot trước mỗi thay đổi đảm bảo khôi phục an toàn.

Luồng Kiểm Soát Guardrails

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#262220', 'primaryTextColor': '#f5f0eb', 'primaryBorderColor': '#3d3835', 'lineColor': '#c89030', 'secondaryColor': '#1f1c18', 'tertiaryColor': '#1a1714', 'background': '#1a1714', 'mainBkg': '#262220', 'nodeBorder': '#4a4543', 'clusterBkg': '#1a1714', 'titleColor': '#f5f0eb', 'edgeLabelBackground': '#262220', 'fontFamily': 'system-ui'} }}%% flowchart LR A["Thay Đổi\nĐược Duyệt"] --> B{{"Kiểm tra\nGuardrails"}} B -->|"Vượt giới hạn"| C["🚨 Alert Admin\n(Blocked)"] B -->|"Trong giới hạn"| D["Snapshot\nHiện tại"] D --> E["Áp Dụng\nThay Đổi"] E --> F["Monitor\nMetrics 24h"] F --> G{{"Metrics\nOK?"}} G -->|"Tốt"| H["✅ Giữ\nThay Đổi"] G -->|"Giảm quá ngưỡng"| I["↩️ Auto\nRollback"]

Các Loại Metrics Thu Thập

Metric Type	Mô tả	Đơn vị	Kích hoạt đề xuất khi
retrieval_quality	Chất lượng kết quả memory retrieval — độ liên quan của L2 chunks được inject	0.0 – 1.0	< 0.6 trong 10 runs liên tiếp
tool_success_rate	Tỷ lệ tool calls thành công / tổng tool calls trong phiên	0.0 – 1.0	< 0.7 trong 5 runs
user_feedback	Điểm phản hồi người dùng — thumbs up/down, rating nếu có	-1, 0, +1	Trung bình < 0 trong 20 phiên
token_efficiency	Tỷ lệ output tokens hữu ích / tổng tokens tiêu thụ	0.0 – 1.0	< 0.5 (quá nhiều token bị prune)
response_latency	Thời gian từ request đến first token và total completion	milliseconds	P95 > 8000ms trong 1 giờ

DB Schema

agent_evolution_metrics migration 000037

CREATE TABLE agent_evolution_metrics (
  id          UUID PRIMARY KEY,
  agent_id     UUID NOT NULL,
  metric_type  TEXT NOT NULL, -- retrieval_quality, etc
  value        FLOAT8 NOT NULL,
  metadata     JSONB,
  recorded_at  TIMESTAMPTZ DEFAULT NOW()
);

agent_evolution_suggestions migration 000037

CREATE TABLE agent_evolution_suggestions (
  id           UUID PRIMARY KEY,
  agent_id      UUID NOT NULL,
  type          TEXT, -- config, behavior, tool
  priority      TEXT, -- high / medium / low
  description   TEXT,
  status        TEXT, -- pending/approved/rejected
  reviewed_by   UUID -- admin user_id
);

Vấn đề thực tế

"Một người không thể giỏi mọi thứ. Agent cũng vậy — agent dịch thuật không nên viết code, agent code không nên trả lời về marketing. Mỗi chuyên gia làm đúng việc của mình."

Ba Chế Độ Orchestration

Spawn Always

Luôn Tạo Agent Con Mới

Mỗi lần delegate → tạo agent con hoàn toàn mới, cách ly hoàn toàn. Đơn giản nhất, không cần quản lý agent links, không có shared state.

Dùng khi nào

Tác vụ đơn giản, một lần. Không cần chia sẻ context hay trạng thái giữa các lần gọi.

Delegate Base

Uỷ Quyền Agent Đã Có

Uỷ quyền cho agent đã tồn tại thông qua agent_links. Tái sử dụng context và khả năng chuyên biệt đã được cấu hình sẵn.

Dùng khi nào

Đã có agent chuyên biệt cho domain đó. Muốn dùng lại system prompt và config được tinh chỉnh.

Team Optional

Kết Hợp Thông Minh

Agent tự quyết: nếu có agent phù hợp trong links thì delegate, không thì spawn mới. Linh hoạt nhất cho tác vụ phức tạp.

Dùng khi nào

Tác vụ phức tạp cần nhiều agent phối hợp, không biết trước cần agent nào.

Delegate Tool — Luồng Thực Thi

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#262220', 'primaryTextColor': '#f5f0eb', 'primaryBorderColor': '#3d3835', 'lineColor': '#e07030', 'secondaryColor': '#1f1c18', 'tertiaryColor': '#1a1714', 'background': '#1a1714', 'mainBkg': '#262220', 'nodeBorder': '#4a4543', 'clusterBkg': '#1a1714', 'titleColor': '#f5f0eb', 'edgeLabelBackground': '#262220', 'fontFamily': 'system-ui'} }}%% sequenceDiagram actor U as User participant A as Agent A participant DT as Delegate Tool participant AL as agent_links participant B as Agent B U->>A: "Phân tích code này" A->>DT: delegate(task, mode) DT->>AL: Tra cứu agent phù hợp AL-->>DT: Agent B (code specialist) rect rgb(17, 24, 39) Note over DT,B: Sync — đợi kết quả DT->>B: Tạo phiên + inject task B-->>DT: Kết quả phân tích DT-->>A: Trả kết quả end rect rgb(13, 20, 36) Note over DT,B: Async — thông báo sau DT->>B: Tạo phiên + inject task DT-->>A: job_id (trả ngay) B-->>A: Notify khi xong (event) end A-->>U: Tổng hợp kết quả

Agent Links — Mạng Lưới Chuyên Gia

🔗

Cấu trúc Link

source_agent_id → target_agent_id với relationship type và metadata. Mỗi link có thể có điều kiện kích hoạt.

💬

Inject vào System Prompt

Danh sách agent liên kết được inject tự động vào system prompt — agent A "biết" agent B tồn tại và có thể giúp gì.

🌐

Ngôn ngữ Enforcement

Không phải suggestion — agent được yêu cầu trả lời bằng ngôn ngữ cụ thể khi delegate cross-language.

⚡ Thứ tự ưu tiên Mode Resolution

Cao nhất

per-agent config

Cấu hình riêng từng agent — overrides tất cả

Trung bình

per-tenant config

Cấu hình chung cho toàn tenant

Mặc định

spawn_always

Fallback an toàn — luôn tạo mới, không cần cấu hình

Vấn đề thực tế

"Tài liệu nằm rải rác: filesystem, database, đầu người... Khi cần tìm, không ai biết ở đâu. Vault gom tất cả vào một nơi có cấu trúc, liên kết với nhau."

🔗

Wikilinks 2 Chiều

Cú pháp [[Tên Tài Liệu]] (giống Obsidian). Forward link A→B và backlink B←A được tạo tự động khi lưu tài liệu. Agent có thể follow graph để khám phá kiến thức liên quan.

Ví dụ Tài liệu "Quy trình Deploy" chứa [[Checklist Bảo Mật]] → tự động tạo liên kết 2 chiều. Khi đọc Checklist Bảo Mật, agent biết nó được tham chiếu bởi Quy trình Deploy.

🔍

Tìm Kiếm Hybrid

Kết hợp Semantic Search (embedding + cosine similarity) với Full-Text Search (tsvector). Hai cách tìm kiếm bổ sung cho nhau — dùng khi nào tuỳ vào loại query.

Semantic tốt cho "Làm sao deploy lên production?" → tìm "Quy trình Release v2.3" dù không trùng từ khoá.

FTS tốt cho Mã lỗi ERR_CONTEXT_OVERFLOW · Config key cụ thể · Tên function chính xác.

🔄

Sync Worker

Worker quét filesystem định kỳ. Dùng SHA-256 hash để phát hiện file thay đổi — chỉ xử lý file mới hoặc đã sửa, không re-index toàn bộ mỗi lần.

Quy trình mỗi file Tính SHA-256 → So sánh với hash đã lưu → Nếu khác: tính embedding mới + parse wikilinks + tạo version mới → Cập nhật vault_documents.

Kiến Trúc Vault

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#262220', 'primaryTextColor': '#f5f0eb', 'primaryBorderColor': '#3d3835', 'lineColor': '#2ea85a', 'secondaryColor': '#1f1c18', 'tertiaryColor': '#1a1714', 'background': '#1a1714', 'mainBkg': '#262220', 'nodeBorder': '#4a4543', 'clusterBkg': '#1a1714', 'titleColor': '#f5f0eb', 'edgeLabelBackground': '#262220', 'fontFamily': 'system-ui'} }}%% graph TB subgraph SRC["Nguồn Dữ Liệu"] U["👤 User\n(thủ công)"] AG["🤖 Agent\n(ghi khi chạy)"] SW["🔄 Sync Worker\n(filesystem scan)"] end subgraph VE["Vault Engine"] H["SHA-256\nHash Check"] EM["Tính\nEmbedding"] LP["Parse\nWikilinks"] VR["Tạo\nVersion"] end subgraph ST["Storage"] FS["📁 Filesystem\n(nội dung gốc)"] PG["🗄️ PostgreSQL\nvault_documents\nvault_links\nvault_versions"] end subgraph AC["Truy Cập"] SS["🔍 Semantic Search\n(cosine similarity)"] FT["📝 Full-Text Search\n(tsvector)"] WN["🗺️ Wikilink Nav\n(graph traversal)"] end U --> VE AG --> VE SW --> VE VE --> H --> EM --> LP --> VR VR --> FS VR --> PG PG --> SS PG --> FT PG --> WN

Phạm Vi Tài Liệu

Personal — Riêng tư

Chỉ user đó mới thấy. Dùng cho ghi chú nháp, draft, tài liệu đang soạn. Không bao giờ leaked sang user khác trong cùng tenant.

Shared — Dùng chung

Cả team trong cùng tenant thấy. Dùng cho tài liệu chung, knowledge base chia sẻ, quy trình làm việc của tổ chức.

🔒

Tenant isolation cứng: Tenant A không bao giờ thấy tài liệu của Tenant B, dù cùng chạy trên cùng database server. Kiểm soát qua tenant_id trong mọi query.

DB Schema

vault_documents migration 000038

id UUID
tenant_id UUID
user_id UUID
title TEXT
content TEXT
content_hash TEXT -- SHA-256
embedding VECTOR(1536)
scope TEXT -- personal/shared
fts_index TSVECTOR
created_at TIMESTAMPTZ

vault_links migration 000038

id UUID
source_doc_id UUID
target_doc_id UUID
link_text TEXT -- tên trong [[...]]
link_type TEXT -- wikilink/ref
created_at TIMESTAMPTZ

vault_versions migration 000038

id UUID
doc_id UUID
version_num INT
content_snapshot TEXT
content_hash TEXT
changed_by UUID
created_at TIMESTAMPTZ