Progressive Enhancement: 5 levels từ raw API đến agent-native — khi nào dùng level nào

English title: Progressive Enhancement: CLI → MCP → Skills → Agent SDK

Mở đầu

Có một câu hỏi tôi nhận được nhiều nhất từ khi bắt đầu viết series này: "Bắt đầu từ đâu? MCP ngay, hay CLI trước?"

Câu trả lời không phải chọn một — mà là hiểu khi nào bạn cần leo lên level nào.

Progressive Enhancement trong web development có nghĩa: build HTML trước, thêm CSS sau, thêm JavaScript sau nữa. Mỗi layer thêm capability mà không phá layer trước. Khi một layer không load, layer dưới vẫn hoạt động.

Cùng nguyên tắc áp dụng cho agent tools: build CLI trước, expose qua MCP sau nếu cần, thêm Skills doc cho context efficiency, tích hợp Agent SDK khi ready. Mỗi level optional và additive.

Bài này là decision framework để biết khi nào cần leo lên level nào — với data thực tế.

1. Năm levels

Level 0: Raw API (REST/GraphQL)
    │ Vấn đề: Agent phải tự manage auth, pagination, error handling
    │ Phù hợp: Không có CLI wrapper
    ▼

Level 1: CLI Wrapper
    │ Thêm: --json output, meaningful exit codes, no interactive prompts
    │ Cost: ~0 tokens | Discovery: qua --help hoặc Skills doc
    │ Phù hợp: Hầu hết use cases, bắt đầu từ đây
    ▼

Level 2: CLI + Skills Doc
    │ Thêm: SKILL.md mô tả commands, workflows, exit codes
    │ Cost: ~200-500 tokens on-demand | Discovery: agent load khi cần
    │ Phù hợp: Tools < 50 commands, agent workflow bounded
    ▼

Level 3: MCP Server
    │ Thêm: Tool schema, dynamic discovery, stateful server
    │ Cost: ~55,000 tokens upfront | Discovery: tự động khi connect
    │ Phù hợp: > 50 tools, interactive IDE session, stateful operations
    ▼

Level 4: Agent SDK Integration
    │ Thêm: Native tool definition, streaming, computer use, structured workflow
    │ Cost: Variable | Discovery: defined in agent system prompt
    │ Phù hợp: Core agent infrastructure, production deployment

2. Data benchmark: tại sao CLI vượt MCP trong nhiều tasks

Benchmark từ nhiều teams (2025-2026) nhất quán cho thấy một pattern:

CLI via subprocess đạt task completion rate cao hơn 28% so với MCP, với cùng token budget.

Tại sao? Không phải vì MCP tệ — mà vì token economics.

Scenario: Agent có 100,000 token context budget, cần complete 10 tasks.

MCP approach:
- MCP schema load: 55,000 tokens (upfront, không optional)
- Remaining cho tasks: 45,000 tokens
- Tokens per task: 4,500

CLI approach:
- CLI schema load: 0 tokens
- Skills doc (khi cần): 500 tokens × 3 tasks = 1,500 tokens
- Remaining cho tasks: 98,500 tokens
- Tokens per task: 9,850

→ CLI có gần 2.2× token budget per task so với MCP

Với nhiều token hơn, agent có thể:

• Maintain richer task context
• Explore more approaches before settling on one
• Handle edge cases better
• Recover from errors more gracefully

28% task completion improvement là hệ quả tự nhiên của việc agent có nhiều "thinking room" hơn.

3. Framework quyết định: 5 câu hỏi

Trả lời 5 câu hỏi này để biết bạn ở level nào:

Q1: Tool của bạn có bao nhiêu commands?
    < 10  → Level 1 (CLI only) đủ
    10-50 → Level 2 (CLI + Skills doc)
    > 50  → Level 3 (MCP) có thể cần

Q2: Agent workflow stateful không?
    Không (mỗi call độc lập) → Level 1 hoặc 2
    Có (cần session, connection pool) → Level 3+

Q3: Agent sử dụng trong IDE không? (Cursor, Claude Code)
    Không → Level 1-2 đủ
    Có → Level 3 (MCP) required để IDE integration hoạt động

Q4: Multiple agents cùng share tools không?
    Không → Level 1-2 đủ
    Có → Level 3 (central MCP server registry)

Q5: Context efficiency quan trọng đến mức nào?
    Critical (cost per token, tight budget) → Level 2 (Skills doc)
    Moderate → Level 2-3 (hybrid)
    Not critical (IDE với long context) → Level 3

Scoring:

• 0-1 "Có" → Level 1: CLI + --json đủ
• 2 "Có" → Level 2: CLI + Skills doc
• 3+ "Có" → Level 3: MCP server
• Level 4 khi: production agent infrastructure, streaming, computer use

4. Migration path: từ Level 1 lên Level 3

Nếu bắt đầu đúng (CLI layer), leo lên là additive — không phải rewrite.

Level 1 → Level 2 (thêm Skills doc):

# Nếu có pipeline: thêm một lệnh
make codegen  # đã generate adapters + commands + tests
python pipeline/generate_skills.py metadata/api-metadata.json SKILL.md myapp

Time: 5 phút. Cost: 0 (generate từ metadata đã có).

Level 2 → Level 3 (thêm MCP server):

# mcp_server.py — wrap adapter, không duplicate logic
from adapters.user_adapter import UserAdapter  # reuse existing adapter
 
@server.call_tool()
async def call_tool(name: str, arguments: dict):
    with UserAdapter(token=os.environ["API_TOKEN"]) as adapter:
        # delegate to adapter
        ...

Time: 2-4 giờ. Cost: maintain thêm một server process.

Level 3 → Level 4 (Agent SDK integration):

# Anthropic Agent SDK tool definition
from anthropic_agent_sdk import tool
 
@tool(description="Manage users via CLI")
def user_management(action: str, **kwargs) -> dict:
    """Route to adapter based on action."""
    with UserAdapter(token=...) as adapter:
        return getattr(adapter, f"{action}_user")(**kwargs)

Time: 4-8 giờ. Cost: SDK dependency, maintain tool definitions.

5. Real-world examples từ các CLI lớn

GitHub CLI (gh): Level 2 + Level 3 hybrid.

• Level 2: Skills doc tương đương trong man pages và --help
• Level 3: GitHub Copilot tích hợp gh qua MCP

Stripe CLI: Level 2.

• 200+ commands nhưng grouped logic → Skills doc per domain đủ
• MCP server thêm sau cho Cursor integration

kubectl: Level 1 + Level 2.

• --output json, --dry-run: Level 1 properties
• kubectl docs (man pages) = Level 2 equivalent
• Kubernetes MCP server là community add-on, không first-party

AWS CLI v2: Level 2.

• --output json, --query (JMESPath selector)
• AWS Toolkit (IDE plugin) dùng MCP internally
• Direct CLI phổ biến hơn MCP cho automation

Pattern chung: hầu hết professional CLIs đạt đủ goodness ở Level 1-2. MCP là add-on cho IDE integration.

6. Áp dụng vào project của bạn: checklist

Level 1 checklist — trước khi claim "agent-ready":

• Mọi command có --json flag
• Exit codes phân biệt: 0 success, 2 usage error, 3 not found, 4 auth, 5 conflict
• Không có interactive prompts (input(), confirm(), getpass())
• Destructive commands yêu cầu --force
• Data ra stdout, messages ra stderr

Level 2 checklist — trước khi claim "Skills-enabled":

• SKILL.md tồn tại và < 600 tokens
• SKILL.md có command examples với exact flag syntax
• SKILL.md có exit code table
• SKILL.md có ít nhất 2 workflow examples

Level 3 checklist — trước khi deploy MCP server:

• MCP server expose đúng tools (verify với mcp-inspector)
• Token schema estimate < 60,000 tokens (verify với token counter)
• Server error handling không crash process
• Auth không hardcode trong server code

7. Ứng dụng trong AI-centric engineering

Progressive Enhancement cho tools không phải là lý thuyết — đó là risk management.

Khi bạn bắt đầu từ Level 1 (CLI), bạn có thể ship trong ngày. Khi agent workflow cần thêm, bạn leo lên Level 2 (Skills) trong vài giờ. Khi IDE integration quan trọng, Level 3 (MCP) trong vài ngày. Không có rewrite, không có migration risk.

Ngược lại, nếu bắt đầu từ Level 4 (full Agent SDK) ngay từ đầu — bạn over-engineer trước khi biết tool có được dùng không.

Một nguyên tắc từ Kent Beck mà áp dụng hoàn hảo: "Make it work, make it right, make it fast." Trong agent tools: "Make it CLI (work), make it have Skills (right), make it MCP/SDK when needed (scale)."

Bài tiếp (và cuối)

Bài 10: End-to-End — Từ REST API đến Agent-Native Tool — Tổng hợp cả series: build CLI hoàn chỉnh từ API spec theo Progressive Enhancement ladder, expose qua Skills + MCP, integrate vào agent workflow. Template có thể apply ngay vào bất kỳ REST API nào. Hành trình 10 bài và những gì bạn đã học.