Series 1 - Bài 2: Architecture 4 layer của CLI Agent

Trước khi viết một dòng code, cần phải rõ ràng về architecture. Architecture không phải diagram để đẹp — nó là tập hợp các quyết định về ai chịu trách nhiệm cái gì và ai được phép nói chuyện với ai.

Một CLI Agent có 4 layer với trách nhiệm rõ ràng và boundary không nên bị phá vỡ.

4 Layer Overview

┌─────────────────────────────────────────────────────────┐
│                    CLI LAYER                            │
│   Nhận input từ user, render output ra terminal         │
│   Biết về: terminal, stdin/stdout, ANSI codes           │
│   Không biết về: LLM, tools, context                   │
├─────────────────────────────────────────────────────────┤
│                   AGENT CORE                            │
│   Orchestrate toàn bộ flow: context → LLM → dispatch   │
│   Biết về: messages[], tool definitions, agentic loop  │
│   Không biết về: terminal specifics, file system       │
├─────────────────────────────────────────────────────────┤
│                   TOOL LAYER                            │
│   Thực thi actions: đọc file, chạy lệnh, tìm kiếm     │
│   Biết về: file system, shell, search APIs             │
│   Không biết về: LLM, context, conversation history   │
├─────────────────────────────────────────────────────────┤
│                  CONTEXT LAYER                          │
│   Cung cấp thông tin về môi trường hiện tại            │
│   Biết về: project structure, config files, token count│
│   Không biết về: terminal, LLM calls, tool execution  │
└─────────────────────────────────────────────────────────┘

Layer 1: CLI Layer

CLI Layer là giao diện duy nhất giữa agent và người dùng. Trách nhiệm của nó rất cụ thể và giới hạn.

                    CLI Layer

stdin ──▶ InputHandler ──▶ CommandParser
                                │
                      ┌─────────┴─────────┐
                      │                   │
               /command           regular message
                      │                   │
              handle locally      send to AgentCore

AgentCore ──▶ OutputRenderer ──▶ stdout
                │
         ┌──────┴──────┐
         │             │
    stream text    tool status
    (word by word)  indicator

InputHandler: Wrap readline, xử lý multiline input (khi user paste đoạn code dài), lưu command history để dùng phím mũi tên.

CommandParser: Phân biệt /commands (meta-commands như /clear, /context, /help) với regular messages sẽ được gửi đến agent. CLI Layer xử lý commands hoàn toàn, không pass xuống Agent Core.

OutputRenderer: Nhận chunks từ Agent Core và render ra terminal. Xử lý ANSI color codes, streaming từng word, progress indicator khi agent đang xử lý.

Boundary quan trọng: CLI Layer không biết gì về LLM hay tools. Nó chỉ biết cách hiển thị gì đó ra terminal và nhận input từ người dùng.

Layer 2: Agent Core

Agent Core là trung tâm điều phối — nơi agentic loop sống.

                  Agent Core

  User message
       │
       ▼
 ┌─────────────┐
 │ContextBuilder│ ← System prompt + file tree + history
 └──────┬──────┘
        │ messages[]
        ▼
 ┌─────────────┐
 │  LLMClient  │ ← Gọi API, parse SSE stream
 └──────┬──────┘
        │ response
        ▼
 ┌─────────────────────────┐
 │   Response type?        │
 └────┬──────────────┬─────┘
      │              │
  tool_use       text done
      │              │
      ▼              ▼
 ┌─────────┐   ┌──────────┐
 │Dispatcher│   │Return to │
 │execute   │   │CLI Layer │
 └────┬─────┘   └──────────┘
      │
  tool_result
      │
      ▼
  Add to messages[]
  Loop lại từ đầu

ContextBuilder: Mỗi vòng loop, ContextBuilder assembly messages[] từ:

• System prompt (role, constraints, behavior)
• Long-term context (từ Context Layer)
• Conversation history (các turn trước)
• Tool results (từ vòng loop trước)
• Current user message

LLMClient: Thuần túy là HTTP client với SSE parsing. Không có business logic. Nhận messages[], trả về response chunks.

ToolDispatcher: Nhận tool_use block từ LLM response, route đến đúng tool trong Tool Layer, collect result, format thành tool_result để thêm vào messages[].

Boundary quan trọng: Agent Core không thực thi bất kỳ action cụ thể nào. Nó dispatch đến Tool Layer. Không có fs.readFile() trong Agent Core.

Layer 3: Tool Layer

Tool Layer là nơi side effects xảy ra. Đây là layer duy nhất tương tác với thế giới bên ngoài.

          Tool Layer

┌─────────────────────────────────────┐
│           Tool Registry             │
│  { name → Tool implementation }     │
└─────────────────────────────────────┘
          │
 ┌────────┼────────┬──────────┐
 │        │        │          │
 ▼        ▼        ▼          ▼

 FileTools  ShellTool  SearchTool  (custom tools)

 read_file  run_cmd    grep_files
 write_file run_test   find_symbol
 list_dir   git_status

Mỗi tool implement một interface chung:

Tool Interface:
  name: string              ← LLM dùng tên này để call
  description: string       ← LLM đọc để biết khi nào dùng
  input_schema: JSONSchema  ← LLM biết cần pass gì
  execute(input) → result   ← Application code chạy cái này

Boundary quan trọng: Tool Layer không biết về conversation history, context, hay LLM. Nó nhận structured input, thực thi action, trả structured output. Stateless hoàn toàn.

Layer 4: Context Layer

Context Layer cung cấp thông tin môi trường mà Agent Core cần để build context cho LLM.

          Context Layer

 ┌──────────────────────────────────────────┐
 │
 │  AGENT.md Loader
 │  └─ Đọc file cấu hình agent ở root project
 │     Inject vào system prompt 1 lần khi start
 │
 │  FileTree Builder
 │  └─ Scan cấu trúc thư mục hiện tại
 │     Rebuild mỗi vòng loop (project có thể thay đổi)
 │     Format gọn để không chiếm quá nhiều token
 │
 │  Token Counter
 │  └─ Estimate token count của messages[]
 │     Signal cho ContextBuilder khi gần limit
 │     Quyết định phần nào cần trim
 │
 └──────────────────────────────────────────┘

Boundary quan trọng: Context Layer không gọi LLM và không execute tools. Nó chỉ đọc và cung cấp thông tin.

Tại sao boundaries này quan trọng

Boundaries không phải bureaucracy — chúng tạo ra properties quan trọng:

Testability: Bạn có thể test Tool Layer hoàn toàn độc lập với LLM. Không cần mock API, không cần real LLM response. Tool nhận input, trả output — đơn giản.

Replaceability: Muốn đổi từ Anthropic sang OpenAI? Chỉ thay LLMClient trong Agent Core. CLI Layer và Tool Layer không đổi.

Security isolation: Tool Layer là nơi duy nhất có side effects. Muốn audit hoặc restrict gì, bạn chỉ cần focus vào đây. Không có side effects leak ra ngoài Tool Layer.

Debuggability: Khi behavior bất ngờ, bạn biết chính xác cần inspect layer nào dựa trên symptom.

Symptom → Layer cần inspect

User input bị parse sai    → CLI Layer
Context thiếu thông tin    → Context Layer
LLM gọi sai tool          → Agent Core (prompt) hoặc Tool Layer (schema)
Tool trả kết quả sai      → Tool Layer
Loop không dừng           → Agent Core (guardrails)

Violation patterns cần tránh

Anti-pattern 1: CLI Layer biết về LLM

// Sai: CLI Layer gọi LLM trực tiếp
readline.on('line', async (input) => {
  const response = await callLLM(input); // ← violation
  console.log(response);
});

Anti-pattern 2: Tool Layer đọc conversation history

// Sai: Tool cần biết context của conversation
class ReadFileTool {
  execute(input, conversationHistory) { // ← violation
    // Tool không nên cần history
  }
}

Anti-pattern 3: Agent Core thực thi file operations

// Sai: Business logic lẫn với orchestration
class AgentCore {
  async handleToolUse(toolUse) {
    if (toolUse.name === 'read_file') {
      return fs.readFile(toolUse.input.path); // ← violation
    }
  }
}

Kết luận

• CLI Agent có 4 layer: CLI, Agent Core, Tool, Context — mỗi layer có một trách nhiệm rõ ràng.
• CLI Layer: user interface. Agent Core: orchestration. Tool Layer: execution. Context Layer: environment info.
• Boundaries tạo ra testability, replaceability, security isolation, và debuggability.
• Khi một layer biết quá nhiều về layer khác, đó là signal của architecture violation.
• Layer boundaries không phải over-engineering — chúng là investment vào maintainability dài hạn.