Tổng quan pipeline

• main.py khởi động Docker (runtime/docker_env.py), tạo client LLM và chạy vòng lặp agent core/loop.AgentLoop.run(goal).
• AgentLoop xây prompt gồm instruction hệ thống, lịch sử từ core/memory.AgentMemory, và goal người dùng; gọi LLM để tạo output.
• core/decision_engine.DecisionEngine trích xuất code block (bash hoặc python) từ output của LLM.
  • Kiểm tra các pattern nguy hiểm (chặn lệnh interactive, server blocking, hoặc loop vô hạn).
  • Nếu hợp lệ, thực thi trong container Docker (runtime/docker_env.DockerEnv.exec) hoặc bọc/encode python và chạy.
  • Ghi lại action và observation vào AgentMemory.
• Sau khi thực thi, core/reflection/self_check.ReflectionEngine gửi observation và ngữ cảnh cho LLM để quyết định continue hay fix_error.
• Vòng lặp lặp lại tới khi agent báo xong bằng cách khiến output chứa ALL_TASKS_COMPLETED.

File chính và nội dung ngắn gọn

• main.py:

  • Entrypoint; đọc .env, khởi docker, tạo LLMClient, chạy AgentLoop.run(goal) và dọn docker khi kết thúc.

• core/loop.py (class AgentLoop):

  • Xây prompt hệ thống (quy tắc, khả năng, workflow verification), gửi đến LLM, lấy output, gọi DecisionEngine.execute, ghi observation và gọi ReflectionEngine.reflect.
  • Quản lý số vòng lặp tối đa (max_iters).

• core/decision_engine.py (class DecisionEngine):

  • Trích xuất code block từ markdown do LLM trả về.
  • Áp luật bảo mật: chặn các lệnh interactive, chặn chạy server blocking trực tiếp (yêu cầu chạy background với nohup ... &), chặn các pattern nguy hiểm trong Python.
  • Thực thi code trong container và trả về observation; lưu step vào AgentMemory.

• core/memory.py (class AgentMemory):

  • Lưu lịch sử hành động và kết quả (steps) với giới hạn max_steps.
  • to_prompt_context() xây lại context để chèn vào prompt (giữ 2 bước đầu + 10 bước cuối, rút gọn phần giữa nếu quá dài).

• core/reflection/self_check.py (class ReflectionEngine):

  • Gửi prompt review cho LLM dựa trên goal, last_observation, và memory_context; mong trả về JSON với status = continue hoặc fix_error.

• runtime/docker_env.py (class DockerEnv và instance docker):

  • Quản lý container Docker: start, stop, exec, inject folder, read/write file trong container.
  • Inject thư mục runtime/resources/agent_utils vào container để agent có thể dùng helper.

• runtime/resources/agent_utils/file_ops.py:

  • Hàm helper read_file và write_file đơn giản (dùng bên trong container hoặc local helper gọi theo spec prompt).

Luồng thực thi (sequence) ngắn gọn

1. python main.py → load env → docker.start()
2. Tạo LLMClient và AgentLoop → gọi run(goal)
3. Trong mỗi iteration:
   • Build prompt (system + memory + goal)
   • LLMClient.generate(prompt) → trả về markdown có 1 block code
   • DecisionEngine trích code, kiểm tra an toàn, thực thi trong Docker
   • Lưu action/observation vào AgentMemory
   • ReflectionEngine đánh giá kết quả, quyết định tiếp tục hoặc fix
4. Khi agent xác nhận hoàn tất, script dừng và docker.stop() được gọi.

Cách chạy nhanh (local)

1. Cài dependencies Docker + Python 3.11+ và cài docker Python SDK.
2. Tạo file .env với GEMINI_API_KEY.
3. Chạy:

python main.py

4. Mở http://localhost:3000 nếu frontend dev server được start bên trong container (Agent sẽ in URL khi hoàn tất).

---