AI Agent
Thực Sự Là Gì?

Vòng Lặp Plan → Execute → Observe → Adjust

╔════════════════════════════════════════════════════════════╗
║              AGENT FEEDBACK LOOP                           ║
╚════════════════════════════════════════════════════════════╝

              ┌─────────────┐
 User Intent ──► │  PERCEIVE   │
              │  (Context)  │
              └──────┬──────┘
                     │ Environment state
                     ▼
              ┌─────────────┐
              │   REASON    │◄── Inference-time Compute
              │   (Plan)    │    ("Extended thinking")
              └──────┬──────┘
                     │ Action plan
                     ▼
              ┌─────────────┐
              │    ACT      │
              │  (Execute)  │──► File edit / Terminal
              └──────┬──────┘    / API call / MCP
                     │
                     ▼
              ┌─────────────┐
              │   OBSERVE   │◄── Environmental Feedback
              │  (Results)  │    (test results, errors,
              └──────┬──────┘     API responses)
                     │
              ┌──────▼──────┐
              │   ADJUST    │
              │  (Re-plan?) │──► Goal achieved? → STOP
              └──────┬──────┘    Error? → Back to REASON
                     │           Budget exceeded? → STOP
              ◄────── Loop continues ──────►

Key: Agent không dừng sau 1 action. Nó loop cho đến khi:
     (1) Goal achieved, (2) Explicit stop, (3) Resource limit

Inference-time Compute — Agent Nghĩ Như Thế Nào?

Thay vì trực tiếp generate output, model hiện đại dành compute để reasoning trước khi commit. Đây là lý do Claude Sonnet hay o1 "chậm hơn" GPT-3.5 — nhưng output có chất lượng cao hơn cho reasoning-intensive tasks.

So Sánh: Autocomplete → Chat → Agent

Không phải mọi AI coding tool đều như nhau. Ba thế hệ công cụ có kiến trúc và năng lực khác nhau căn bản:

Environmental Feedback — Sự Khác Biệt Kiến Trúc Then Chốt

Đây là điểm phân biệt agent thực sự với mọi công cụ AI trước đó. Khi Cline chạy pytest và nhận được output:

$ pytest tests/cart/test_service.py -v
FAILED tests/cart/test_service.py::test_cart_merge_max_qty
   AssertionError: assert 5 == 3
   Full cart after merge has 5 items, expected max(3, 2) = 3

FAILED tests/cart/test_service.py::test_concurrent_add
   IntegrityError: duplicate key value violates unique constraint
   "cart_items_cart_id_product_id_key"

1 passed, 2 failed in 0.23s

Sơ Đồ Kiến Trúc Tổng Quan

╔══════════════════════════════════════════════════════════════╗
║              AGENTIC CODING SYSTEM                           ║
╠══════════════════════════════════════════════════════════════╣
║  ┌──────────────────────────────────────────────────────┐    ║
║  │                    AGENT CORE                        │    ║
║  │  ┌─────────────┐  ┌──────────────────────────────┐  │    ║
║  │  │ LLM Engine  │  │  Context Window (200K)       │  │    ║
║  │  │ (Claude /   │◄─►│  • System prompt             │  │    ║
║  │  │  GPT-4o)    │  │  • AGENTS.md / CLAUDE.md     │  │    ║
║  │  │             │  │  • Conversation history      │  │    ║
║  │  │ Inference-  │  │  • Tool outputs              │  │    ║
║  │  │ time        │  │  • File contents             │  │    ║
║  │  │ Compute     │  └──────────────────────────────┘  │    ║
║  │  └──────┬──────┘                                    │    ║
║  │         │ Tool calls                                │    ║
║  └─────────┼────────────────────────────────────────── ┘    ║
║            ▼                                                  ║
║  ┌─────────────────────────────────────────────────────┐     ║
║  │                   TOOL LAYER                        │     ║
║  │  ┌──────────┐  ┌──────────┐  ┌───────────────────┐ │     ║
║  │  │File Ops  │  │ Terminal │  │   MCP Servers     │ │     ║
║  │  │read_file │  │execute_  │  │  GitHub MCP       │ │     ║
║  │  │write_file│  │command   │  │  Jira MCP         │ │     ║
║  │  │list_dir  │  │run_test  │  │  Database MCP     │ │     ║
║  │  └──────────┘  └──────────┘  │  Slack MCP        │ │     ║
║  │  ┌──────────┐  ┌──────────┐  └───────────────────┘ │     ║
║  │  │  Web     │  │Checkpoint│                         │     ║
║  │  │  Search  │  │  System  │                         │     ║
║  │  └──────────┘  └──────────┘                         │     ║
║  └─────────────────────────────────────────────────────┘     ║
║            ▼                                                  ║
║  ┌─────────────────────────────────────────────────────┐     ║
║  │              FEEDBACK PROCESSING                    │     ║
║  │  • Parse stdout/stderr  • Extract error types       │     ║
║  │  • Test result analysis • State diff computation    │     ║
║  │  • Inject back to context window for next iteration │     ║
║  └─────────────────────────────────────────────────────┘     ║
╚══════════════════════════════════════════════════════════════╝

Tool Layer — MCP Như Tiêu Chuẩn Ngành

MCP (Model Context Protocol) chuẩn hóa giao tiếp: bất kỳ tool nào implement MCP protocol đều hoạt động với bất kỳ MCP-compatible host nào. MCP = "USB standard for AI tools".

Extended Thinking — Agent "Dừng Lại và Suy Nghĩ"

Extended Thinking là cơ chế cho phép model thực hiện inference-time compute — dành token để "nghĩ" trước khi output. Khi agent nhận một task phức tạp, nó chạy một internal monologue dưới dạng <thinking> blocks.

# Ví dụ: Agent nhận task "Fix the failing cart merge test"

# === THINKING (internal, thường ẩn) ===
<thinking>
Nhìn vào test failure:
  AssertionError: assert 5 == 3
  Full cart after merge has 5 items, expected max(3, 2) = 3

Test expectation: merge của cart có 3 items và cart có 2 items
với cùng product → result phải là max(3,2) = 3 items (không phải 5)

Điều này suggest rằng current implementation đang ADD quantity
thay vì taking MAX. Cần kiểm tra CartMergeService.merge() method.

Approach 1: Fix merge logic → change add to max
Approach 2: Check nếu spec thực sự muốn max (có thể test sai?)
Đọc SPEC.md §3: "merge rule: keep max(guest_qty, user_qty)"
→ Test đúng, code sai. Fix CartMergeService.

Plan: Edit CartMergeService.merge(), run test, verify other merge tests.
</thinking>

# === OUTPUT (visible) ===
# "Tôi thấy vấn đề trong CartMergeService.merge().
#  Đang cộng quantity thay vì lấy max. Sửa ngay."

Checkpoint System — Cơ Chế Rollback Khi Agent Sai

# Checkpoint workflow trong thực tế (Cline built-in)

# Trước mỗi "dangerous action" (xóa, overwrite nhiều files):
AGENT: "Tôi sắp xóa 3 files và rewrite CartService.py.
        Tôi đã tạo checkpoint tại commit abc123.
        Để rollback: git checkout abc123"
        [Awaiting approval: Yes/No]

# Khi agent detect nó đi sai hướng:
AGENT: "Test vẫn fail sau 2 lần sửa. Rollback về checkpoint
        và thử approach khác."
→ git reset --hard abc123
→ Agent restart với fresh approach

# IMPORTANT: Agent tạo checkpoint trước, không sau.
# Rule: "checkpoint → action" not "action → checkpoint"

State Management — Agent Quản Lý Trạng Thái

Agent không có "memory" giữa các session (trừ khi dùng MCP Memory Server). Trong một session, state được quản lý qua context window — một "cuộn giấy" dài chứa toàn bộ lịch sử.

Ba Mức Độ Autonomy

Bảng So Sánh Chi Tiết

Approval Gate Design — Khi Nào Cần Human?

Human-in-the-loop không phải bottleneck — đó là thiết kế cố ý. Agent làm 90% công việc nặng; con người chỉ can thiệp tại những điểm có rủi ro cao nhất.

Cline Config + Autonomy Spectrum

// .vscode/settings.json — Cline approval gates
{
  "cline.alwaysAllowReadOnly": true,   // Read = auto-approve
  "cline.alwaysAllowWrite": false,     // Write = show diff
  "cline.alwaysAllowExecute": false,   // Commands = explicit
  "cline.autoApproveEnabled": false,   // No full auto

  // Allowlist cho specific safe commands
  "cline.allowedCommands": [
    "pytest",      // Run tests = safe
    "ruff",        // Linter = safe
    "mypy",        // Type check = safe
    "git status",  // Read-only git = safe
    "git diff"
  ]
  // Anything NOT in allowlist = needs human approval
}

// Philosophy:
// Agent làm việc nhanh trên read/analyze/test.
// Human review tại "point of no return" moments.
// 10% approval time → 90% development quality assurance.

Phase 1 & 2: Perception + Reasoning

Task: Implement CartMergeService cho EcoShop (Case Study Ch.7). Spec đã approved. Agent yêu cầu implement + tests, không có additional guidance.

# === USER INPUT ===
Implement CartMergeService theo SPEC.md §3 merge rule.
Đọc code hiện có, viết implementation + tests. Chạy tests sau khi xong.

# === PHASE 1: PERCEPTION — Agent reads codebase ===
→ list_directory("src/cart/")
# OUTPUT:
  src/cart/service.py   ← CartService (exists)
  src/cart/repository.py ← CartRepository (exists)
  src/cart/models.py    ← Cart, CartItem models (exists)
  # merge_service.py NOT YET EXISTS ← needs to create

→ read_file("src/cart/service.py")
→ read_file("src/cart/models.py")
→ read_file(".sdd/features/feat-cart-core/SPEC.md")

# === PHASE 2: REASONING — Agent lên plan ===
<thinking>
Merge logic cần handle:
1. Guest cart items + User cart items
2. Same product+variant: keep max(guest_qty, user_qty)
3. Guest-only items: add to user cart
4. User-only items: keep as is
5. After merge: delete guest cart

Edge cases từ SPEC clarification:
- product_id + variant_id = unique key (Q3 answer)
- Refresh snapshot_price after merge (Q1 answer)
- Concurrent merge: need transaction (Q2 from original spec)
Race condition: add FOR UPDATE lock in transaction.
Plan: T1: Write CartMergeService + T2: Write unit tests + T3: Run tests
</thinking>

Phase 3: Action — Agent Viết Code

# === AGENT ACTION: Create file ===
→ write_file("src/cart/merge_service.py")

class CartMergeService:
    def __init__(self, repo: CartRepository, price_svc: PriceService):
        self.repo = repo
        self.price_svc = price_svc

    async def merge(self, guest_cart_id: str, user_cart_id: str) -> Cart:
        # EARS[Event]: WHEN Customer logs in with Guest cart
        # EARS[Ubiquitous]: Run in transaction (race condition protection)
        async with self.repo.transaction() as txn:
            guest_cart = await txn.get_cart_for_update(guest_cart_id)
            user_cart  = await txn.get_cart_for_update(user_cart_id)

            for g_item in guest_cart.items:
                key = (g_item.product_id, g_item.variant_id)
                u_item = user_cart.find_item(*key)

                if u_item:
                    # EARS[Ubiquitous]: Same product → keep max qty
                    u_item.quantity = max(u_item.quantity, g_item.quantity)
                    # EARS[Ubiquitous]: Refresh snapshot_price
                    u_item.snapshot_price = await self.price_svc.current(*key)
                else:
                    # Guest-only item → add to user cart
                    user_cart.add_item(g_item, refresh_price=True)

            await txn.delete_cart(guest_cart_id)
            return await txn.save_cart(user_cart)

→ write_file("tests/cart/test_merge_service.py")
# [writes 5 test cases for the 5 scenarios]

→ execute_command("pytest tests/cart/test_merge_service.py -v")

Phase 4: Observe — Tests Fail! Không Phải Happy Path

# === TEST OUTPUT (environmental feedback) ===

FAILED test_merge_guest_only_items
   AttributeError: Cart object has no attribute "add_item"
   self.repo returned Cart object, not expected CartProxy

FAILED test_merge_max_qty_with_price_refresh
   RuntimeError: Cannot use transaction outside async context
   NullSession: transaction requires active session

PASSED test_merge_user_only_items_unchanged
PASSED test_merge_deletes_guest_cart

2 passed, 2 failed in 0.31s

# ← Agent NHẬN PHẢN HỒI TỪ MÔI TRƯỜNG
# Không hỏi human. Tự phân tích.

Phase 5: Reasoning — Agent Tự Debug

# === AGENT THINKING sau khi đọc failures ===
<thinking>
Failure 1: "Cart object has no attribute add_item"
→ add_item không phải method của Cart model.
→ Tôi assumed Cart có add_item() nhưng models.py không có.
→ Fix: dùng cart.items.append() + create CartItem object directly.
→ Check models.py lại để verify correct field names.

Failure 2: "Cannot use transaction outside async context"
→ self.repo.transaction() không hoạt động trong unit test environment.
→ Tests dùng mock repository không có real transaction support.
→ Approach: Abstract transaction detail, mock trong tests.
→ Hoặc: Đưa transaction lên caller (CartService), không trong MergeService.

Which approach? SPEC nói CartService orchestrates everything.
PLAN.md: CartMergeService là helper, CartService owns transaction.
→ Move transaction to CartService.handle_login_merge().
→ CartMergeService chỉ contain pure logic, easier to test.

Đây là architectural improvement, không chỉ bug fix.
Update both merge_service.py và service.py.
</thinking>

# AGENT: "Tôi thấy 2 vấn đề:
#  1. Cart.add_item() không tồn tại — cần dùng models trực tiếp
#  2. Transaction nên ở CartService, không MergeService (clean architecture)
#  Refactoring cả hai files."

Phase 6: Adjust — Fix và Re-test → Green!

# === AGENT ACTION: Fix based on reasoning ===
→ read_file("src/cart/models.py")          ← Verify Cart model fields
→ write_file("src/cart/merge_service.py")  ← Remove transaction, pure logic
→ write_file("src/cart/service.py")        ← Add transaction at CartService level
→ write_file("tests/cart/test_merge_service.py")  ← Update mocks

# === SECOND TEST RUN ===
→ execute_command("pytest tests/cart/test_merge_service.py -v")

PASSED test_merge_guest_only_items
PASSED test_merge_max_qty_with_price_refresh
PASSED test_merge_user_only_items_unchanged
PASSED test_merge_deletes_guest_cart
PASSED test_merge_handles_empty_guest_cart

5 passed, 0 failed in 0.18s ✅

→ execute_command("pytest tests/cart/ -v")
# All 23 tests pass ✅

# === AGENT FINAL OUTPUT ===
"CartMergeService implemented. Kết quả:
- 5/5 merge tests pass
- 23/23 total cart tests pass
- Architectural note: moved transaction to CartService
  (cleaner, easier to test, follows PLAN.md pattern)
Files changed:
  + src/cart/merge_service.py (created)
  ~ src/cart/service.py (added handle_login_merge)
  + tests/cart/test_merge_service.py (created)"

Agent Log Analysis — Đọc Log Để Debug

# Cline Agent Log — Location: View → Output → "Cline" dropdown

[10:23:01] TASK_START  model: claude-sonnet-4-6  context_tokens: 15230
[10:23:02] TOOL_CALL: list_directory  path: "src/cart/"  tokens_added: 180
[10:23:03] TOOL_CALL: read_file  path: "src/cart/service.py"  tokens_added: 2250
[10:23:05] TOOL_CALL: read_file  path: ".sdd/.../SPEC.md"  tokens_added: 1800
           ← Agent đọc spec!
[10:23:08] THINKING  duration: 3.2s  thinking_tokens: 850
           ← Extended thinking enabled
[10:23:09] TOOL_CALL: write_file  path: "merge_service.py"  bytes: 1840
           [AWAITING APPROVAL] ← Human gate
[10:23:15] HUMAN_APPROVED  action: write_file
[10:23:18] TOOL_CALL: execute_command  command: "pytest ... -v"
           exit_code: 1  ← Test fail!  tokens_added: 420
[10:23:19] THINKING  duration: 4.1s  thinking_tokens: 1200
           ← Longer think for error analysis
[10:23:25] TOOL_CALL: write_file (fix #1)
[10:23:28] TOOL_CALL: execute_command  exit_code: 0 ← Green!
[10:23:30] TASK_COMPLETE
           total_duration: 89s  total_tokens: 22450 (~$0.067)
           files_changed: 3  tool_calls: 12

# Total: 89s, $0.067 — for a task that would take dev 30+ min

Red Flags Trong Log — Dấu Hiệu Agent Đang Có Vấn Đề

Internal Monologue — Tại Sao Agent Chọn A Thay Vì B

Enable Extended Thinking để thấy lý do agent ra quyết định:

# Enable qua Claude API
response = client.messages.create(
    model="claude-sonnet-4-6",
    thinking={"type": "enabled", "budget_tokens": 5000},
    messages=[{"role": "user", "content": task}]
)

# Đọc thinking output
for block in response.content:
    if block.type == "thinking":
        print("AGENT THINKING:", block.thinking)

# === TYPICAL THINKING EXCERPT ===
# "Two approaches to implement this:
#  A: Use Redis cache with 5min TTL
#  B: Use PostgreSQL materialized view
#
#  SPEC says: < 200ms p95 response time
#  Current DB has 50K products → full scan too slow
#
#  Redis: latency ~1ms, cost ~$20/month, cache invalidation needed
#  Mat view: latency ~5ms, cost $0, auto-refresh by DB
#
#  Both satisfy 200ms requirement.
#  PLAN.md says: existing Redis cluster already deployed.
#  → Use Redis (no new infrastructure, team already knows it)"

# Đây là chính xác lý do agent chọn Redis.
# Không phải "tôi thích Redis" — có reasoning chain rõ ràng.

Token Burn — Chi Phí Ẩn Của Agentic Workflows

# Token budget breakdown — implement một feature

# Bước 1: Initial context load (constant per session)
AGENTS.md + CLAUDE.md:      4,000 tokens
SPEC.md (current feature):  2,500 tokens
PLAN.md + TASKS.md:         1,500 tokens
Total setup:                8,000 tokens

# Bước 2: Per-iteration costs (× nhiều lần)
Read source file (200 lines): 2,500 tokens × 5 files = 12,500
Thinking (Extended):          1,500 tokens × 3 rounds = 4,500
Generate code (150 lines):    2,000 tokens × 2 files = 4,000
Test output (50 lines):         600 tokens × 4 runs  = 2,400
Error analysis thinking:      1,000 tokens × 2 errors = 2,000
Total dynamic: ~25,400 tokens

# Total session cost:
# Input tokens:  ~28,000 × $3/M  = $0.084
# Output tokens:  ~6,000 × $15/M = $0.090
# Total: ~$0.17 per feature task   ← affordable!

# Scale: 20 features/sprint × 2 devs × $0.17 = $6.80/sprint

# Khi agent bị stuck và loop:
# Normal task:           28,000 tokens
# Loop task (10 iters): 280,000 tokens = $1.70/task
# 5 tasks/day stuck: $8.50/day = $170/month extra!

Chiến Lược Tối Ưu Chi Phí Token

"cline.maxTokensPerTask": 50000
// hard stop at 50K

"cline.warnAt": 30000
// alert at 30K

Loop Trapping — Khi Agent "Ngáo"

Loop Trapping xảy ra khi agent bị stuck trong một vòng lặp sửa lỗi: fix lỗi A tạo ra lỗi B, fix lỗi B tạo ra lỗi A (hoặc C). Agent không nhận ra nó đang loop vì mỗi iteration nhìn có vẻ "khác nhau".

Cách Xử Lý Khi Agent Bị Loop

# Khi phát hiện agent đang loop — INTERRUPT ngay

# 1. Dừng agent (Ctrl+C trong Cline)

# 2. Đọc current state:
#    - Test đang fail là gì?
#    - Code hiện tại trông như thế nào?
#    - Agent đã thử approach gì?

# 3. Human analyze root cause
#    Thường loop xảy ra vì:
#    a) Spec mơ hồ → AI không biết "đúng" là gì
#    b) Architectural constraint chưa được spec
#    c) Dependency issue → cần fix ở chỗ khác trước

# 4. Provide clarification prompt, không phải "fix this"

# SAI (tạo thêm loop):
# "Fix the test failure"

# ĐÚNG (break loop với specific guidance):
# "Test fail vì cart.items.quantity không thể là 0.
#  SPEC §5 Data: quantity là positive integer.
#  Database constraint: quantity > 0 NOT NULL.
#  Approach: kiểm tra quantity >= 1 trong CartService.add_item(),
#  reject nếu < 1 với ValidationError.
#  Đừng fix test — fix validation trong service."

# 5. Nếu vẫn loop sau clarification → rollback + rewrite từ đầu
# Rule of thumb: > 5 failed attempts = root cause issue,
# không phải fixable incrementally.

Model Dependency — Intelligence Ceiling

Mọi agentic framework — Cline, Claude Code, Cursor Composer — đều là orchestration layer. Chất lượng output cuối cùng bị bounded bởi model LLM bên trong. Architecture agent tốt với model kém → kết quả tệ hơn architecture đơn giản với model tốt.

Context Window Cliff + API Hallucination

# Ví dụ hallucination:
# Agent viết: redis_client.set_with_ttl("key", value, ttl=300)
# Thực tế:    redis_client.setex("key", 300, value)

# Prevention:
# 1. Thêm vào CLAUDE.md: library version + usage examples
# 2. Cung cấp actual code examples trong spec
# 3. Sau khi agent write code: "Verify tất cả API calls là hợp lệ"
# 4. Luôn chạy code sau khi generate — import errors catch ngay

Long-range Dependency Blindness + Tóm Tắt Giới Hạn

Agent thường rất tốt với local code nhưng yếu hơn với long-range dependencies: thay đổi một file ảnh hưởng đến file khác 20 modules downstream. Đây là lý do integration tests quan trọng hơn unit tests khi dùng agent.

Tổng Kết Chương 9