Agent thông minh hơn, tự cải thiện, phối hợp nhóm —
thiết kế lại từ nền tảng với kiến trúc pipeline 8 stage.
Ba vấn đề cốt lõi khiến v2 không thể scale — và cách v3 giải quyết từng vấn đề.
Hàm runLoop() 804 dòng — nấu ăn, rửa bát, nhận order trong cùng 1 nhà bếp.
Pipeline 8 stage — mỗi đầu bếp 1 nhiệm vụ, test riêng, thay thế độc lập.
Kết quả: Giảm 70% thời gian debug — test riêng từng stage, xác định lỗi chính xác trong vài giây.
Chỉ có context window — hết phiên là quên sạch. User phải nhắc lại từ đầu.
Memory 3 tầng: Working → Episodic → Semantic. Auto-inject kiến thức phiên trước.
Kết quả: Agent "nhớ" ngữ cảnh xuyên phiên — không cần user nhắc lại, trải nghiệm liên tục.
Admin điều chỉnh thủ công dựa trên cảm tính — không có dữ liệu, không nhất quán.
Self-Evolution 3 giai đoạn: thu thập metrics → đề xuất → tự thích ứng (có guardrails).
Kết quả: Giảm chi phí vận hành — chất lượng tăng tự động theo thời gian sử dụng.
Từ client request đến kết quả — toàn bộ luồng dữ liệu trong GoClaw v3.
Load agent config, system prompt, inject L2 memory, build initial message list.
Gọi LLM provider, xử lý streaming response, parse tool calls từ output.
Đếm token chính xác, soft trim ở 70%, hard compact khi cần thiết.
Execute tools — song song cho I/O-heavy, tuần tự cho state mutation.
Tổng hợp tool results, emit events, quyết định loop tiếp hay kết thúc.
Lưu trạng thái mỗi 5 vòng — chống mất dữ liệu khi crash giữa chừng.
Flush memory L1, trigger evolution async, emit run.completed event.
Consolidate L0 → L1, schedule L1 → L2 extraction (async, không block).
Trạng thái khởi tạo: agent config, memory injection, system prompt rendering.
LLM đang xử lý — streaming tokens, buffering tool calls, tracking usage.
Kiểm tra token limit, quyết định soft trim hay trigger compact.
Đang thực thi tools — tracking parallel vs sequential execution groups.
Phân tích tool outputs, update loop context, emit intermediate events.
Hard compact — summarize conversation history khi đạt 100% context limit.
Background evolution metrics collection và suggestion generation sau run.
Kích hoạt pipeline 8 stage thay cho runLoop() cũ. Entry point: loop_run.go:160.
Bật Memory L1 (Episodic) — lưu session summaries, consolidation sau mỗi run.
Bật Memory L2 auto-inject — vector search và inject vào context khi có message mới.
Thu thập performance metrics sau mỗi run — token usage, tool calls, latency.
LLM phân tích metrics và đề xuất cải thiện prompt/behavior cho agent.
Tạo bảng agent_memory, evolution_metrics, evolution_suggestions. Schema v37.
Tạo bảng vault_documents, vault_links — Knowledge Vault với wikilinks. Schema v38.
Thêm episodic_summaries table cho L1 Memory consolidation. Schema v39 (hiện tại).
Tình trạng hiện tại của từng module — backend, UI, và tests.
Mỗi quyết định có lý do cụ thể — không phải thích thì làm, mà là phải làm.
Hàm runLoop() trong v2 dài 804 dòng — không có ranh giới rõ ràng giữa các trách nhiệm. Khi bug xảy ra, không thể xác định chính xác stage nào gây lỗi. Không thể test riêng từng bước, không thể thay thế 1 phần mà không ảnh hưởng toàn bộ. Pipeline 8 stage tách biệt hoàn toàn từng concern, mỗi stage có interface riêng, test độc lập.
Phức tạp hơn để setup ban đầu — cần adapter pattern để tương thích ngược với v2. Overhead nhỏ cho context truyền giữa các stage.
Context window có giới hạn cứng — không thể lưu toàn bộ lịch sử hội thoại. Cần cơ chế phân cấp: L0 giữ context hiện tại, L1 lưu summary của các phiên gần đây, L2 lưu vector embeddings của kiến thức đã trích xuất. Ba tầng đảm bảo agent luôn có đủ ngữ cảnh mà không bị overflow.
Cần 3 migration tables, async consolidation pipeline. Latency tăng nhẹ do auto-inject vector search.
Ước tính token (characters/4) sai lệch đáng kể với nội dung tiếng Việt và code. Sai số 15-20% dẫn đến hoặc prune quá sớm (mất context cần thiết) hoặc quá muộn (API lỗi 413). Token counting chính xác từ provider response đảm bảo PruneStage quyết định đúng thời điểm.
Chỉ có số chính xác sau khi LLM xử lý — không biết trước khi gửi request. Cần lưu usage từ response.
Dual-key workspace (agent_id + user_id) gây nhầm lẫn khi resolver phải xử lý 6 kịch bản khác nhau: solo agent, team agent, predefined agent, per-user context, shared context, admin context. Workspace có cấu trúc với enum type đơn giản hóa routing logic và loại bỏ ambiguity.
Cần migration để cập nhật workspace schema. Một số edge cases cần handle riêng trong resolver.
Memory module cần trigger Evolution, Evolution cần đọc Memory metrics, Consolidation cần notify cả hai — tạo vòng import circular không thể compile. Event bus typed (strongly-typed event structs) cho phép các module publish/subscribe mà không import lẫn nhau.
Async by default — event có thể đến sau một chút. Debug khó hơn vì không có call stack trực tiếp.
String concatenation để build system prompt không thể toggle section — luôn phải thêm tất cả hoặc không có. Template system cho phép bật/tắt từng section (memory injection, evolution context, workspace info) dựa trên feature flags, và dễ maintain hơn nhiều.
Cần parse template một lần khi khởi động. Template errors chỉ phát hiện khi render, không phải compile time.
Global feature flag bật v3 cho toàn bộ tenant gây rủi ro cao — không thể test trên subset user. Per-agent flags cho phép team migrate từng agent một, so sánh A/B, và rollback ngay lập tức chỉ 1 agent nếu phát hiện vấn đề.
5 flags × nhiều agents = nhiều config rows hơn. Admin UI phức tạp hơn một chút.
Không thể cắt service để migrate toàn bộ production sang v3 cùng một lúc. Dual-mode giữ cả hai code path hoạt động song song — if l.v3PipelineEnabled ở loop_run.go:160. Flag tắt = rollback ngay lập tức không cần deploy.
Phải maintain cả hai code path trong thời gian migration. Sau khi migration hoàn tất, cần cleanup v2 code path.
Không cần rewrite 804 dòng code v2. Adapter wraps các callbacks của v2 loop (sendMessage, handleTool, etc.) thành interface mà pipeline stages có thể consume. Closures capture context tự nhiên mà không cần struct phức tạp.
Adapter layer thêm một lớp indirection. Cần đảm bảo closure không capture stale state khi reuse.
1 pha pruning gây tình huống hoặc quá thận trọng (trim sớm, mất context quan trọng) hoặc quá hung hăng (summarize khi chưa cần). Soft trim loại bỏ messages cũ nhất khi đạt 70% — giữ context gần đây. Hard compact chỉ chạy khi đạt 100% — summarize toàn bộ conversation.
Hard compact cần thêm 1 LLM call để tóm tắt — tăng latency và cost khi triggered.
Tools như web search, file read, API call là I/O-heavy — có thể chạy đồng thời mà không conflict. Nhưng tools như write file, update database phải tuần tự để tránh race condition. ToolStage phân loại và group tools theo loại trước khi execute.
Cần metadata cho từng tool để biết loại. Parallel execution khó debug hơn sequential.
Agent chạy dài (20-50+ vòng lặp) có thể crash giữa chừng do OOM, network timeout, hoặc lỗi provider. Không checkpoint = mất toàn bộ progress. Checkpoint mỗi 5 vòng đảm bảo worst case chỉ mất tối đa 5 vòng cuối.
Thêm DB write mỗi 5 vòng. Checkpoint size có thể lớn với long conversations.
Nếu agent phải gọi tool để lấy memory, sẽ tốn thêm 1 LLM round-trip và phụ thuộc vào việc LLM có nhớ gọi tool hay không. Auto-inject tại context_stage.go:97 khi V3RetrievalEnabled && AutoInject != nil && Message != "" — agent luôn có context mà không cần làm gì.
Luôn chạy vector search khi có message mới — thêm latency ~50-100ms. Cần cache cho frequent queries.
Trích xuất kiến thức từ L1 sang L2 yêu cầu LLM call để tóm tắt và generate embeddings — có thể mất 2-5 giây. Sync consolidation sẽ block user phải chờ sau mỗi phiên. Async consolidation chạy background sau khi đã trả response cho user.
Kiến thức mới chưa available ngay trong phiên tiếp theo đầu tiên. Cần error handling cho async failures.
Full autonomy ngay từ đầu rủi ro cao — agent tự thay đổi behavior mà không có guardrails. 3 giai đoạn: (1) Collect metrics chỉ đọc, (2) Generate suggestions để admin review, (3) Auto-apply chỉ khi confidence cao và change nhỏ. Guardrails ngăn thay đổi destructive.
Cần human review ở giai đoạn 2. Evolution chậm hơn fully autonomous nhưng an toàn hơn nhiều.
Một agent tổng hợp làm tất cả mọi việc dễ bị "context pollution" — không thể focus vào 1 domain. Agent chuyên biệt (code agent, search agent, analysis agent) có system prompt tối ưu cho domain và model riêng. Delegate tool cho phép orchestrator giao task cho đúng specialist.
Cần quản lý nhiều agent hơn. Communication overhead giữa agents qua delegate calls.
Flat list tài liệu không thể hiện mối quan hệ giữa các khái niệm. Wikilinks syntax [[document-name]] tạo bidirectional links — khi đọc tài liệu A, agent biết tài liệu nào khác liên quan và có thể follow. Graph traversal cho kết quả tốt hơn simple keyword search.
Cần parse wikilinks khi lưu, maintain link table. Orphaned links cần cleanup job.
Destructive schema changes (rename column, change type, drop table) không thể rollback trong production. Cả 3 migration của v3 (v37, v38, v39) đều additive — chỉ thêm bảng/cột mới, không sửa schema cũ. Rollback bằng cách tắt feature flags mà không cần rollback schema.
Cần cleanup migration sau khi confirm stable. Schema có thêm tables không dùng nếu feature off.