Pi Agent: Sự đánh đổi giữa tự do và tiện lợi

1. Bất ngờ đầu tiên

Sự tương phản đó nói về chỗ công việc nằm ở đâu, không nói về chất lượng. Ở một sản phẩm tích hợp, nhiều năng lực hỗ trợ đã có sẵn khi bạn mở nó ra. Với Pi, tôi có thể tự thay đổi hoặc tự xây những mảnh đó, và tôi bắt đầu làm vậy.

Bài này đi theo một lập luận. Pi cho lập trình viên nhiều tự do hơn để định hình hệ thống quanh một model, và sự tự do đó chuyển trách nhiệm sang họ. Sự tiện lợi không biến mất. Nó trở thành thứ bạn phải xây, tích hợp, kiểm thử và bảo trì. Tôi sẽ đi từ kiến trúc và hệ thống công cụ của nó, qua các thí nghiệm của mình, đến chuyện gì xảy ra khi việc thực thi thất bại, ranh giới phân quyền, vấn đề workflow và Code Mode, rồi hỏi liệu một bộ công cụ lớn hơn có sửa được điều gì trong số đó không, và kết bằng việc tôi nghĩ sự đánh đổi này thực chất là gì.

2. Pi là gì

Bốn công cụ dựng sẵn được bật mặc định: read, bash, edit và write. Bốn công cụ dựng sẵn nữa (grep, find, ls và powershell chỉ dành cho Windows) phải bật thêm (CLI reference). Phần 3 trình bày toàn bộ hệ thống công cụ. Trang chủ liệt kê những thứ Pi cố tình bỏ ra: “No sub-agents”, “No plan mode”, “No permission popups”. Với mỗi thứ, trang này chỉ sang extension, package hoặc công cụ khác (pi.dev).

Bản thân vòng lặp khá nhỏ. Pi thêm tin nhắn của bạn vào nhánh đang hoạt động, dựng một request từ system prompt, nhánh đó, các định nghĩa công cụ và cài đặt model, stream câu trả lời, chạy mọi lời gọi công cụ trong đó rồi ghi lại kết quả. Nếu kết quả đó hoặc các tin nhắn đang xếp hàng cần thêm một request nữa, một turn mới bắt đầu. Nếu không, lượt chạy kết thúc (How Pi works).

Tài liệu tách bạch các cơ chế tùy biến, và sự khác biệt này quan trọng cho mọi phần bên dưới (How Pi works):

Cơ chế	Là gì	Mức cưỡng chế
Skill và file ngữ cảnh	Chỉ dẫn model đọc, nạp theo nhu cầu hoặc lúc khởi động	Không có. Model có thể phớt lờ.
Prompt template	Đoạn tin nhắn dùng lại được, mở rộng từ đầu vào của bạn	Không có.
Extension	Module TypeScript nạp vào process Pi. Chúng đăng ký công cụ, lệnh, nhà cung cấp, bộ xử lý sự kiện và giao diện.	Bằng code. Chúng có thể chặn lời gọi công cụ, và chạy với quyền hệ điều hành của process.
Package	Cách phân phối extension, skill, template và theme qua npm hoặc git	Giống nội dung bên trong.

Trang chủ nói MCP nay đã được tích hợp sẵn, cùng với Codemode (phần 10).

Các lớp này trả lời những câu hỏi khác nhau, và chọn nhầm lớp là lỗi dễ mắc. Trước khi viết code, hãy hỏi yêu cầu thực sự là gì:

• Chỉ dẫn hoặc kiến thức dùng lại được (repo này build thế nào, quy ước nào áp dụng): file ngữ cảnh, skill hoặc prompt template. Skill phù hợp khi một workflow “needs more context than a prompt template but does not need a new executable integration point” (Skills).
• Hành vi lúc chạy hoặc việc thực thi công cụ (chặn một lời gọi, thêm công cụ, đổi thứ model nhìn thấy): extension.
• Tích hợp với hệ thống khác: extension, MCP, hoặc điều khiển Pi từ bên ngoài qua RPC hay SDK (phần 9).
• Phân phối và duy trì một bộ các thứ trên: package. Package chỉ là cơ chế phân phối, và chúng “can execute extension code and can include skills that instruct the model to run programs”, nên việc xem xét mã nguồn là của bạn (Packages).

3. Công cụ: model thực sự làm được gì

Xuyên suốt bài tôi đã dùng chữ “công cụ” (tool), và phần còn lại của bài dựa vào nó. Phân quyền, khả năng quan sát, sub-agent và khôi phục lỗi, xét đến cùng đều là câu hỏi về các lời gọi công cụ. Vì vậy cần nói chính xác công cụ trong Pi là gì trước khi đi tiếp.

Một lời gọi công cụ, từng bước

Năm thành phần trong hình có vai trò khác nhau:

• Model đề xuất. Nó thấy các định nghĩa công cụ và quyết định có gọi một cái hay không. Nó không chạy được gì.
• Vòng lặp agent nắm việc thực thi. Nó tra công cụ, kiểm tra đối số, chạy hook, gọi execute() và biến kết quả thành một tin nhắn.
• Định nghĩa công cụ là hợp đồng model đọc: tên, mô tả và schema tham số.
• execute() của công cụ là code bình thường chạy trong process Pi, với quyền hệ điều hành của process đó.
• Kết quả công cụ quay lại nhánh đang hoạt động dưới dạng tin nhắn kết quả công cụ, nên request tiếp theo chứa nó. Đó cũng là lý do output lớn quan trọng: bất cứ thứ gì kết quả chứa đều trở thành ngữ cảnh.

Pi đi kèm những gì

Công cụ	Trách nhiệm	Mặc định	Giới hạn output (từ mã nguồn)
read	Đọc file văn bản và các ảnh được hỗ trợ	bật	2.000 dòng hoặc 50 KB, dùng offset / limit để đọc tiếp
bash	Chạy một lệnh shell trong thư mục làm việc	bật	2.000 dòng cuối hoặc 50 KB; output đầy đủ lưu vào file tạm
edit	Thay thế văn bản chính xác trong file đã có	bật	không áp dụng
write	Tạo mới hoặc ghi đè một file	bật	không áp dụng
grep	Tìm nội dung file; tôn trọng .gitignore	bật thêm	100 kết quả khớp hoặc 50 KB
find	Tìm đường dẫn theo mẫu glob; tôn trọng .gitignore	bật thêm	1.000 kết quả hoặc 50 KB
ls	Liệt kê thư mục, gồm cả file ẩn	bật thêm	500 mục hoặc 50 KB
powershell	Chạy lệnh PowerShell, chỉ trên Windows	bật thêm	giống bash

Hai công cụ nữa đến từ các extension dựng sẵn của Pi, không thuộc bộ công cụ lõi. Cả hai đều tắt mặc định (CLI reference):

Công cụ	Trách nhiệm
codemode	Model viết JavaScript gọi các công cụ khác; chỉ output của script quay lại (phần 10)
tool_search	Tìm các công cụ chưa được khai báo với model và khai báo những cái khớp cho lần gọi tiếp theo

Một chỉnh sửa cho cách nói tắt trước đó của chính tôi: phần 2 nói bốn công cụ được bật mặc định còn grep, find và ls phải bật thêm. Điều đó đúng nhưng chưa đủ. Có tám tên công cụ dựng sẵn, gồm cả một shell chỉ dành cho Windows, và hai công cụ nữa nằm sau extension.

Công cụ lõi, công cụ từ extension, và công cụ của riêng bạn

Câu hỏi “Pi có bao nhiêu công cụ?” không có một đáp án duy nhất, vì công cụ đến với model theo những cách khác nhau:

Loại	Do ai định nghĩa	Đến với model thế nào
Công cụ dựng sẵn	Lõi của Pi (read, bash, edit, write, grep, find, ls, powershell)	Được khai báo khi đang hoạt động; bốn cái đầu hoạt động mặc định
Công cụ của extension dựng sẵn	Các extension đi kèm Pi (codemode, tool_search)	Đăng ký ở trạng thái không hoạt động; được bật theo tên hoặc bởi extension MCP
Công cụ MCP	Một MCP server bạn cấu hình; đặt tên mcp__<server>__<tool>	exposure theo từng server: codemode (mặc định, không khai báo với model), deferred, direct hoặc hidden (MCP)
Công cụ extension tự viết	Extension TypeScript của bạn, qua pi.registerTool()	Mặc định direct, được bật ngay khi đăng ký; có các kiểu exposure khác
Công cụ SDK	Ứng dụng host nhúng Pi, qua tùy chọn customTools	Thuộc tập công cụ đang hoạt động mà tools, noTools và excludeTools điều khiển (SDK)

Một công cụ tự viết là một đoạn code nhỏ. Đây là ví dụ hello.ts của chính Pi, đã rút gọn (nguồn):

const helloTool = defineTool({
  name: "hello",
  label: "Hello",
  description: "A simple greeting tool",
  parameters: Type.Object({ name: Type.String({ description: "Name to greet" }) }),
  async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
    return {
      content: [{ type: "text", text: `Hello, ${params.name}!` }],
      details: { greeted: params.name },
    };
  },
});

export default function (pi: ExtensionAPI) {
  pi.registerTool(helloTool);
}

Công cụ, extension, skill, MCP server, package

Phần 2 phân tách các cơ chế tùy biến theo thứ chúng cưỡng chế. Ở đây là cùng sự phân tách đó, nhưng theo việc mỗi cơ chế làm gì với bề mặt công cụ của model:

Cơ chế	Thêm một thao tác model gọi được?	Chạy code trong process Pi?
Công cụ	Có, chính nó là thao tác đó	Có, execute() của nó
Extension	Có, nếu gọi registerTool(). Nó cũng có thể thêm lệnh, hook, provider và giao diện	Có
Skill	Không. Model làm theo chỉ dẫn bằng các công cụ đã có	Không
Prompt template	Không. Nó mở rộng thành văn bản tin nhắn	Không
MCP server	Có, công cụ của nó xuất hiện dưới dạng mcp__<server>__<tool>	Server là một process riêng hoặc dịch vụ từ xa. Extension MCP của Pi là client
Package	Mang theo bất kỳ thứ nào ở trên	Tùy nội dung bên trong

4. Tự xây những mảnh còn thiếu

Trình tự quan trọng hơn bất kỳ lỗi riêng lẻ nào. Động cơ cho các sub-agent là những session dài và ngữ cảnh lớn. Tôi không tìm thấy thứ mình muốn ở dạng mình muốn, nên tôi thử tự xây. Ngoài công sức bỏ ra, thứ nó để lại cho tôi là những câu hỏi về việc ủy quyền: orchestrator chịu trách nhiệm điều gì, kết quả và lỗi của một sub-agent đi đâu, và ai nhìn thấy chúng. Phần còn lại của bài đi theo những câu hỏi đó. Đó là cách tôi đọc thí nghiệm của chính mình. Nó là một diễn giải về những gì xảy ra khi tôi tự xây các mảnh này, không phải một khẳng định rằng Pi nói chung thiếu năng lực ủy quyền.

Những gì tài liệu thiết lập sẵn là một chuyện riêng, và kiểm tra được. Pi gọi “no sub-agents” là một lựa chọn. Hướng dẫn extension của nó cũng không nhắc đến sub-agent, dù cho phép extension chạy các công cụ khác bằng ctx.executeTool(), và những lời gọi lồng nhau này đi qua cùng các handler tool_call như lời gọi do model phát ra (hướng dẫn extension). Vậy nên orchestrator không phải thứ bạn cấu hình. Nó là thứ bạn thiết kế.

Ngữ cảnh không chỉ là một cửa sổ

Trước hết là cái gì lấp đầy cửa sổ. System prompt gồm các chỉ dẫn nền của Pi cộng với các context file nó tìm thấy. Định nghĩa công cụ được gửi kèm mỗi request, và nhánh đang hoạt động được chuyển thành các tin nhắn user, assistant và tool-result. Skill được nạp dần: chỉ tên, mô tả và đường dẫn của mỗi skill vào system prompt, còn toàn bộ SKILL.md chỉ được đọc khi model quyết định một tác vụ khớp với mô tả. Skill có disable-model-invocation: true chỉ dùng được qua lệnh tường minh /skill:name. Tin nhắn của bạn có thể mang tham chiếu file bằng @, ảnh dán vào và đầu ra của !command (!!command chạy lệnh mà không gửi đầu ra cho model), và extension có thể thêm chỉ dẫn hoặc biến đổi ngữ cảnh trước khi request rời đi (How Pi works, Skills, Usage, extensions guide).

Ngữ cảnh dài là lý do tôi muốn có sub-agent, nên cần nói chính xác các cơ chế của Pi làm gì. Ba thứ dễ bị lẫn vào nhau:

• Compaction quản lý thứ model nhìn thấy lúc này. Nó thay các tin nhắn cũ bằng một bản tóm tắt, nên bản tóm tắt giữ lại gì sẽ quyết định agent biết gì về sau.
• Persistence (lưu bền) giữ toàn bộ bản ghi trên đĩa, gồm cả phần compaction đã giấu khỏi model.
• Branching (rẽ nhánh) điều khiển hướng đi: bạn có thể quay lại một điểm trước đó và thử cách khác mà không mất nhánh đã rời.

5. Khi việc ủy quyền trở nên khó nhìn thấy

Quan sát này nói về một khoảng trống: giữa tín hiệu tiến độ chung chung và khả năng kiểm tra việc thực thi thực sự. Dựng cái thứ nhất thì dễ và dễ bỏ qua cái thứ hai. Tôi không khẳng định extension của mình có hay thiếu cơ chế cụ thể nào. Điểm bên dưới là thứ một hệ thống ủy quyền cần có, nếu bạn muốn tin nó.

Các khối xây dựng của Pi bao phủ một phần. Session được lưu dưới dạng cây JSONL ghi lại tin nhắn, lời gọi công cụ và kết quả, cùng các lần compaction, còn chế độ JSON và RPC stream các sự kiện agent (How Pi works). API extension bổ sung các hook chi tiết hơn. Sự kiện vòng đời gồm agent_start, turn_start, message_update và agent_settled, còn việc thực thi công cụ có tool_execution_start, tool_execution_update (tiến độ trong một lời gọi) và tool_execution_end. Với các lời gọi lồng nhau qua ctx.executeTool(), những sự kiện này mang theo parentToolCallId (hướng dẫn extension). SDK cung cấp session.subscribe() cho sự kiện của một session chạy trong cùng process (SDK). Đây là các khối xây dựng, và tôi chưa kiểm chứng chúng hoạt động thế nào giữa các process Pi con riêng biệt. Tài liệu tôi đọc không mô tả dashboard, metrics hay hệ thống tracing nào ngoài những thứ này. Việc một process con có xuất hiện hữu ích trong bản ghi đó hay không phụ thuộc vào cách bạn khởi chạy nó. Đó là một quyết định thiết kế thuộc về bạn.

Extension API là nơi các khối xây dựng đó trở nên cụ thể. Hình liệt kê các hook theo thứ tự chúng chạy và điều mỗi loại handler được phép làm: có loại chỉ quan sát, có loại biến đổi thứ đi qua, và một số có thể chặn.

Gộp lại, có ba thuộc tính riêng biệt, và một agent có thể có cái đầu tiên mà thiếu các cái còn lại:

• Thực thi: nó có thể thực hiện hành động.
• Khả năng quan sát: bạn biết nó đang làm gì và đang ở đâu.
• Kiểm soát: bạn có thể can thiệp, đổi cách làm hoặc dừng nó.

Ủy quyền mà thiếu khả năng quan sát tạo ra một hệ thống có thể hành động mà không dễ hiểu được. Đó là kết luận về thiết kế, không phải khẳng định rằng mọi hệ thống đa agent đều như vậy.

Kiểm soát cũng có một mặt được ghi trong tài liệu. Một người có thể steer, xếp follow-up hoặc abort (mục 2), và một chương trình có thể làm như vậy qua RPC. Những thứ đó tác động lên một session Pi. Một agent cha sẽ áp dụng chúng cho agent con ra sao, khi nào nên làm, và agent con xử lý chúng thế nào là những quyết định tôi sẽ phải tự thiết kế. Tôi không khẳng định Pi không làm được.

6. Khi việc thực thi dừng lại

Như vậy có hai nhóm, và sự khác biệt giữa chúng chính là phần hữu ích: các gián đoạn tôi phục hồi được bằng cách chẩn đoán rồi chạy tiếp, và các lỗi chặn đứng tác vụ. Tôi không xếp từng lỗi cụ thể (lỗi phản hồi, dùng sai công cụ, cạn kiệt ngữ cảnh) vào nhóm nào, và tôi cũng không nói lỗi nào trong số đó là không thể phục hồi nói chung. Một lỗi có tự tiếp tục được hay không phụ thuộc vào model, nhà cung cấp, cấu hình và các extension, và phần kể của tôi không gán cái nào cho cái nào.

Đây là vấn đề khác với phần 5. Khả năng quan sát hỏi bạn có thấy được agent đang làm gì không. Khả năng phục hồi hỏi chuyện gì xảy ra khi việc nó đang làm bị hỏng. Khả năng thực thi một tác vụ của agent và khả năng phục hồi khi việc thực thi thất bại là hai thuộc tính riêng. Một hệ thống có thể rất giỏi cái đầu mà không nói gì về cái sau.

Tôi không nên nói quá những gì Pi thiếu, vì nó có hành vi phục hồi, và tài liệu mô tả chúng:

Vậy phát biểu chính xác không phải là Pi không bao giờ phục hồi. Một số lỗi có đường xử lý tích hợp sẵn, và một số đường đó có giới hạn: ba lần retry theo mặc định, và một đường phục hồi bằng compaction kết thúc mà không thử lại nếu bản thân compaction thất bại. Tài liệu tôi đọc không liệt kê lỗi nào được tính là transient. Chúng cũng không mô tả cách xử lý tích hợp cho một model cứ dùng sai một công cụ, hoặc cho một lần chạy kết thúc ở trạng thái bạn muốn tiếp tục. Tôi không biết liệu lỗi nào của mình nằm trong hay ngoài các đường tích hợp sẵn. Tôi không khẳng định chúng là khoảng trống của Pi. Có thể đó là những trường hợp mặc định đã cạn hoặc không áp dụng.

Hình vẽ các đường đó và điều xảy ra khi từng đường cạn. Ô nét liền là hành vi có trong tài liệu. Hàng nét đứt đánh dấu một khoảng trống trong những gì tôi đã đọc, không phải một khẳng định về Pi.

Pi cho bạn một phần những thứ này, và cây session của nó, vốn giữ nguyên các mục gốc ngay cả sau compaction, là một bản ghi hữu ích để tiếp tục từ đó (How Pi works). Tôi chưa tìm các package bổ sung retry hay compaction an toàn hơn, nên không thể nói chúng có tồn tại hay hoạt động tốt đến đâu. Ở một sản phẩm tích hợp, nhiều quyết định trong số này có thể đã được đưa sẵn cho bạn. Với Pi, mặc định chỉ là điểm xuất phát, và phần còn lại là của bạn để thiết kế, kiểm thử và bảo trì. Đó là cùng một sự đánh đổi như trước, nhìn từ trường hợp thất bại: tự do tùy biến một agent không đi kèm đảm bảo rằng nó phục hồi một cách trơn tru.

7. Ranh giới phân quyền thực sự

Các extension hạn chế quyền và nỗ lực dùng Docker ở phần 4 đặt ra câu hỏi cái gì thực sự giới hạn một agent. Một prompt, một công cụ bị hạn chế và một container là những thứ khác nhau, nên tách chúng ra sẽ có ích.

Vòng lặp dưới đây mang tính khái niệm, không phải sơ đồ cấu trúc nội bộ của Pi:

context → model → tool request → runtime → execution environment → tool result → updated context

Năm lớp đều có thể được gọi là “permission”:

1. Quyền của process. Những gì user hệ điều hành chạy agent làm được. Mọi thứ trong process đều bị chặn trên bởi đây.
2. Kiểm tra ở tầng ứng dụng. Các quy tắc trong agent xem xét một lời gọi công cụ rồi cho phép, hỏi lại hoặc từ chối.
3. Ranh giới thư mục project. Thư mục làm việc là một hàng rào hay chỉ là điểm xuất phát.
4. Năng lực của công cụ. Một read có cấu trúc có thể bị rào theo đường dẫn. Một shell có thể chạy bất kỳ chương trình nào, và chương trình đó có thể mở bất kỳ file nào.
5. Cách ly. Container, VM và sandbox hệ điều hành giới hạn chính process, kể cả các process con.

Điều đó khớp với tài liệu: mặc định không có hàng rào ở tầng ứng dụng. Nhưng việc không có hộp thoại không chứng minh quyền truy cập không giới hạn trong mọi cấu hình. Một extension có thể thêm kiểm tra. Sự kiện tool_call có thể sửa hoặc chặn một lời gọi, và một handler ném lỗi sẽ chặn nó theo kiểu fail-closed (hướng dẫn extension). Một hộp thoại cũng không chứng minh bảo mật toàn diện. Tài liệu của Claude Code nói quy tắc deny của Read và Edit áp dụng cho các công cụ file tích hợp, cho các lệnh file mà nó nhận ra trong Bash như cat, và cho đích của redirection. Chúng không áp dụng cho một lệnh đọc file mà không nêu tên chúng, như grep -r pattern ., hay cho một script tự mở file. Để có cưỡng chế ở mức hệ điều hành, tài liệu chỉ đến sandbox của nó, và nói chế độ bypassPermissions chỉ nên dùng trong môi trường cách ly như container hoặc VM (permissions). Vậy tài liệu của cả hai đều chỉ đến sự cách ly cho ranh giới thật. Chúng khác nhau ở mặc định giữa bạn và ranh giới đó. Ở Manual mode của Claude Code (giá trị cấu hình default), nó hỏi trước hầu hết hành động chỉnh sửa file, chạy lệnh shell hoặc truy cập mạng (permission modes). Một tập lệnh chỉ đọc tích hợp như cat và ls chạy không cần hỏi, kể cả với đường dẫn ngoài thư mục làm việc, trừ khi permissions.blockReadsOutsideWorkingDirectories được bật. Tài liệu cũng nói từ v2.1.283, auto mode là chế độ khởi đầu cho các session tương tác trong terminal và VS Code, với một classifier xem xét hành động thay bạn. Pi không hỏi gì cả. Tôi so sánh tài liệu, không so sánh hành vi: tôi chưa chạy Claude Code cho bài này.

Hai chi tiết riêng của Pi dễ bị bỏ sót:

• Project trust không phải sandbox. Nó kiểm soát những gì một thư mục cung cấp: settings và MCP server của project, extension, skill, prompt template và theme dưới .pi, file system prompt, và các package được cấu hình theo project. Nó “prevents a folder from silently loading executable extensions before you approve it”, và trang bảo mật nói nó “does not limit what tool calls can access or affect”. Extension chạy “inside the Pi process with the same operating-system permissions”, nên một extension đã được tin cậy có thể đọc prompt, lời gọi công cụ, file và lịch sử session (hướng dẫn extension). File ngữ cảnh (AGENTS.md, CLAUDE.md) được nạp mà không cần trust (Configuration). Chỉ dẫn trong một repository bạn đã clone có thể đến được model dù bạn có tin cậy nó hay không. Việc một model cụ thể có làm theo một chỉ dẫn độc hại hay không là câu hỏi khác mà tôi chưa thử.

• Docker là một công cụ, không phải một đảm bảo. Container thực sự cách ly cái gì phụ thuộc vào việc bạn mount gì, truyền credential nào vào, mạng có mở không, và nó chạy dưới user nào. Một container mount thư mục home của bạn cùng một API key phạm vi rộng chỉ dời vấn đề đi chỗ khác, không giải quyết nó. Đây là bảo mật container nói chung, không phải kết quả từ nỗ lực của tôi (Docker security).

Tóm lại, ba câu hỏi hay bị trộn lẫn. Trust hỏi tài nguyên riêng của một thư mục có được nạp hay không. Permissions hỏi process đang chạy và các công cụ của nó về mặt kỹ thuật làm được gì. Isolation hỏi điều gì vẫn nằm ngoài tầm với ngay cả khi một agent hoặc extension hành xử sai. Tài liệu của Pi cung cấp cái thứ nhất, mô tả cái thứ hai, và để cái thứ ba cho bạn. Tôi chưa kiểm toán bảo mật của Pi ngoài việc đọc các trang này và mã nguồn của một công cụ.

Hướng dẫn container hóa của Pi cung cấp gì

Chỉ nói “tự mang container đến” thì là lời khuyên mỏng, và tài liệu đi xa hơn thế. Hướng dẫn containerization mô tả bốn lựa chọn, và chúng khác nhau ở thứ nằm trong ranh giới:

8. Từ agent đến workflow

Khi tôi xem xét việc dùng Pi trong các project vốn đã dùng phát triển có AI hỗ trợ, một vấn đề khác xuất hiện. Năng lực không phải workflow. Một agent có năng lực không biết project build thế nào, theo quy ước nào, test nào phải pass, hay khi nào công việc được coi là xong.

Phần còn lại của mục này là phân tích chi phí để đưa một agent vào một project. Đó là suy luận chung, không phải báo cáo về điều gì đã đi sai trong một project cụ thể của tôi.

Đây là chỗ các phần trước gặp nhau. Khả năng quan sát, khả năng phục hồi và ranh giới phân quyền về bản chất đều là câu hỏi về workflow: hệ thống làm gì, có ai nhìn thấy được không, và cái gì ràng buộc nó. Một sản phẩm tích hợp đã quyết định nhiều điều trong số đó rồi. Với Pi, bạn tự quyết.

9. Không có WebUI tích hợp không có nghĩa là không có lựa chọn tích hợp

Pi không có giao diện web tích hợp, điều tôi cảm thấy là một khoảng trống. Nhưng thiếu UI và thiếu giao diện lập trình là hai chuyện khác nhau. Tài liệu liệt kê nhiều cách để điều khiển cùng một agent (CLI, How Pi works):

Giao diện	Mục đích sử dụng
Interactive (mặc định)	Giao diện terminal cho con người.
Print (-p)	Một prompt, văn bản cuối ra stdout, rồi thoát.
JSON (--mode json)	Chạy một lần và ghi sự kiện agent dưới dạng JSONL.
RPC (--mode rpc)	Process chạy lâu, được điều khiển bằng lệnh JSONL trên stdin, sự kiện ra stdout.
SDK	Thư viện TypeScript tạo và điều khiển session trong cùng process.

Vậy một front end web không bị chặn. Bạn có thể xây một cái trên RPC hoặc SDK. Thứ các giao diện này không làm là công việc xung quanh chúng: dựng UI, xử lý output dạng stream, giữ trạng thái session, quyết định chuyện gì xảy ra khi có lỗi (phần 6), và quản lý vòng đời của agent. Trang SDK còn nêu một điểm tinh tế bạn sẽ phải xử lý: agent_end đánh dấu kết thúc một lần chạy, còn agent_settled báo hiệu Pi sẽ không tự tiếp tục. Tôi chưa xây front end nào như vậy, nên đây là mô tả bề mặt đã được tài liệu hóa, không phải trải nghiệm của tôi.

Chi tiết là nơi công việc ẩn mình (RPC). Hình cho thấy hình dạng của một prompt qua giao diện RPC, và phần mà một client ngây thơ làm sai.

10. Code Mode: một hướng thiết kế tôi chưa thử

Tôi tìm thấy Code Mode của Pi trong tài liệu. Tôi chưa dùng nó cho tác vụ thật nào, nên phần này mô tả thiết kế đã được tài liệu hóa và không nói gì về kết quả.

Tôi muốn thử nó trên một tác vụ thật trước khi đánh giá. Cho đến lúc đó, nó vẫn chỉ là một giả thuyết.

11. Nhiều công cụ hơn, agent có tốt hơn?

Phản ứng đầu tiên của tôi trước môi trường mỏng của Pi (phần 1) là đếm những gì còn thiếu. Hệ thống công cụ khiến phản ứng đó đáng được xem xét lại, vì rất dễ biến “ít công cụ dựng sẵn” thành “kém năng lực hơn”. Tôi không nghĩ số lượng công cụ quyết định được điều gì, và phần so sánh dưới đây nhằm cho thấy vì sao.

Ba harness đi kèm những gì

	Pi	Claude Code	Codex
Bề mặt công cụ dựng sẵn	8 công cụ lõi (4 bật mặc định), cộng 2 công cụ extension tắt mặc định	Tools reference liệt kê 46 mục. Một số có điều kiện: công cụ task tùy model, Grep và Glob mặc định bị bỏ trên macOS, Linux và WSL, và một mục được ghi là đã gỡ	Không có danh sách hay tổng số được tài liệu hóa. Mã nguồn có handler cho thực thi shell (exec_command, write_stdin), apply_patch, update_plan, view_image, request_user_input, request_permissions, công cụ tài nguyên MCP, tool_search, công cụ multi-agent và web search do host cung cấp. Tôi không kiểm chứng cái nào được bật với một model hay cấu hình cụ thể
Sửa file	edit (thay thế chính xác), write	Edit, Write, NotebookEdit	apply_patch
Tìm kiếm	bash, hoặc grep / find / ls bật thêm	Grep / Glob trên Windows. Ở nơi khác, Claude mặc định tìm bằng find và grep qua Bash	Qua công cụ shell. Tôi không thấy handler tìm kiếm riêng
Lập kế hoạch, sub-agent	Không dựng sẵn; trang chủ ghi “No sub-agents”, “No plan mode”	Agent, EnterPlanMode, AskUserQuestion, công cụ task, công cụ worktree và nhiều hơn	update_plan, request_user_input, công cụ multi-agent. Tài liệu mô tả subagent như một lớp tùy biến
Thêm công cụ	registerTool() trong extension, customTools của SDK, MCP	MCP (“To add custom tools, connect an MCP server”). Một skill “runs through the existing Skill tool rather than adding a new tool entry”. Hook và quy tắc phân quyền ràng buộc công cụ	MCP, với enabled_tools / disabled_tools cho MCP server. Skill là chỉ dẫn; plugin đóng gói và phân phối chúng
Phân quyền và sandbox	Mặc định không có hộp thoại phê duyệt và không có sandbox; tài liệu bảo bạn tự mang container	Quy tắc allow và deny theo tên công cụ, chế độ phân quyền, và cờ theo từng công cụ cho biết có cần hỏi hay không	Sandbox do hệ điều hành cưỡng chế (Seatbelt, bwrap cộng seccomp) cộng chính sách phê duyệt. Với thư mục có version control, mặc định là workspace-write với phê duyệt on-request
Kiểm soát chi phí ngữ cảnh	Allowlist --tools, exposure, tool_search, codemode	ToolSearch mặc định hoãn định nghĩa công cụ MCP; alwaysLoad cho một server không bị hoãn	enabled_tools / disabled_tools; có một công cụ tool_search trong mã nguồn

Lập luận: bộ công cụ lớn hơn không tự động làm agent tốt hơn

Tuyên bố của tôi hẹp hơn “ít hơn thì tốt hơn”. Một bộ công cụ lớn hơn tự nó không làm agent có năng lực, đáng tin cậy hay hữu ích hơn, và một bộ nhỏ hơn tự nó cũng không làm agent an toàn hơn hay dễ sống chung hơn. Sáu góc nhìn dưới đây, mỗi cái được đánh dấu là loại khẳng định nào.

1. Đơn giản so với năng lực. Quan điểm Một ít công cụ tổng quát có thể phủ các thao tác cơ bản: đọc, ghi, sửa và chạy lệnh. Riêng bash đã làm được những gì grep, find và ls làm, đó là lý do ba công cụ ấy phải bật thêm ở Pi, và tài liệu Claude Code nói rằng trên macOS, Linux và WSL nó cũng mặc định bỏ Grep và Glob và tìm kiếm qua Bash. Chồng chéo là chỗ một bộ lớn hơn bắt đầu tốn kém: hai công cụ làm gần giống nhau buộc model phải chọn và buộc bạn phải hiểu hai hành vi. Nhưng một bộ nhỏ cũng có chồng chéo (edit và write đều sửa file, và bash làm được cả hai), nên nhỏ không đồng nghĩa với không chồng chéo.

2. Chọn công cụ và suy luận. Quan điểm Trực giác là mỗi công cụ thêm vào là một lựa chọn nữa model phải cân nhắc, có thể làm việc chọn kém dự đoán được hơn. Tôi chưa đo điều đó, và cả tài liệu Pi lẫn Claude Code tôi đọc đều không đưa ra khẳng định về độ chính xác khi chọn công cụ, nên tôi coi nó là một giả thuyết. Điều tài liệu cho thấy là cả hai sản phẩm đều xây cơ chế để không khai báo mọi thứ ngay từ đầu (hình trên), gợi ý rằng các tác giả coi trọng chi phí của một tập khai báo lớn. Đó là suy luận về ý định, không phải lý do được nêu ra.

3. Khả năng mở rộng so với sự đầy đủ dựng sẵn. Quan điểm Một lõi tối giản đặt ra ít giả định hơn và dễ đọc từ đầu đến cuối hơn. Cái giá tương ứng chính là điều cả bài này nói đến: bất cứ thứ gì lõi bỏ ra, ai đó phải xây, kiểm thử và bảo trì. API extension của Pi rộng rãi, nhưng một công cụ tự viết là code bạn sở hữu, viết trên một API đã từng thay đổi (phần 12 nhắc tới việc đổi tên package). Một harness tích hợp đã làm việc đó một lần, cho tất cả mọi người.

4. Kiểm soát so với tiện lợi. Quan điểm Một bộ mặc định nhỏ là nền rõ ràng để tùy biến: bạn đọc được model được cung cấp gì, đổi nó, và móc vào mọi lời gọi. Một harness được trau chuốt cho bạn thứ chạy được ngay ngày đầu. Cả hai đều là giá trị thật. Bên nào thắng tùy việc bạn có bao giờ dùng đến sự kiểm soát đó không, và tôi sẽ không trung thực nếu nói lúc nào tôi cũng dùng.

5. Chi phí ngữ cảnh và cài đặt. Tài liệu Định nghĩa công cụ, schema và chỉ dẫn đều là ngữ cảnh. Tài liệu Claude Code nói “each upfront tool consumes context that would otherwise be available for your conversation”, rằng mỗi skill trong danh sách “adds to your context on every turn”, và rằng tool search giữ ngữ cảnh MCP ở mức thấp “by deferring tool definitions until Claude needs them”. Pi giới hạn phần khai báo công cụ trong mô tả của codemode ở 3.000 token ước tính theo mặc định. Output cũng quan trọng: công cụ dựng sẵn của Pi cắt ở 2.000 dòng hoặc 50 KB, và Claude Code lưu kết quả MCP quá lớn ra đĩa khi vượt 50.000 ký tự. Quan điểm Vậy chi phí là có thật, nhưng phụ thuộc vào thứ được khai báo. Mười công cụ nhỏ có thể tốn ít hơn một công cụ với schema khổng lồ, và một công cụ bị hoãn gần như không tốn gì cho đến khi cần. Khẳng định “mỗi công cụ thêm vào đều gây hại” không suy ra được.

6. Độ tin cậy và trách nhiệm. Quan điểm Một bộ công cụ nhỏ hơn không làm agent an toàn hay đáng tin cậy. Bốn công cụ mặc định của Pi có bash, thứ làm được gần như mọi việc người dùng làm được, và tài liệu bảo mật của nó nói thẳng rằng nó không hỏi trước mỗi lời gọi. Codex có sandbox và chính sách phê duyệt, Claude Code có quy tắc phân quyền theo công cụ, và cả hai đều không phụ thuộc vào số lượng công cụ. Điều quyết định độ tin cậy là chất lượng cài đặt của từng công cụ, việc kiểm tra đầu vào, báo lỗi, và ranh giới quanh việc thực thi. Một công cụ có mô tả mơ hồ hoặc lỗi âm thầm gây hại hơn một công cụ bị thiếu.

Chủ nghĩa tối giản của Pi giúp ở đâu, và tốn kém ở đâu

Giúp ở đâu	Tốn kém ở đâu
Bề mặt ngắn, dễ đọc: tám cái tên, bốn cái mặc định	Mọi thứ ngoài thao tác file và bash là việc bạn phải tự xây hoặc cài
Bạn chọn model thấy gì (--tools, exposure)	Bạn phải biết lựa chọn đó tồn tại, và phải đưa ra nó
Một điểm hook thấy mọi lời gọi, kể cả lời gọi lồng nhau	Hook là bề mặt chính sách, không phải sandbox; ranh giới là việc bạn tự dựng (phần 7)
Ít giả định được nhúng sẵn, nên harness ít gây bất ngờ	Các workflow phổ biến (kế hoạch, sub-agent, phê duyệt) bắt đầu từ trang trắng
Dễ nhúng qua RPC hoặc SDK	Nhúng khiến bạn là chủ của phần keo dán (phần 9)

12. Tự do, tiện lợi, và ai sở hữu hệ thống

Các thí nghiệm này cộng lại thành gì? Khả năng mở rộng chính là điểm mấu chốt của Pi: hành vi lập trình được, một hook duy nhất nơi mọi lời gọi công cụ đều có thể bị kiểm tra hoặc từ chối, các luồng sự kiện bạn có thể xây lên trên, và một lõi đủ nhỏ để hiểu. Mỗi thứ đó đi kèm một cái giá tương ứng, và cái giá luôn giống nhau. Quyết định đã chuyển sang tôi.

Pi cho bạn gì	Pi đòi hỏi gì ở bạn
Định hình nhiều phần của hệ thống hơn	Quyết định có gì trong đó, và bảo trì nó
Hành vi tùy chỉnh khớp nhu cầu của bạn	Kiểm thử nó, và giữ cho nó chạy được khi Pi thay đổi. Package từng đổi scope npm một lần: @mariozechner/pi-coding-agent có từ 11/2025, @earendil-works/pi-coding-agent từ 05/2026, theo npm registry, nơi giờ đánh dấu tên cũ là deprecated và khuyên dùng tên mới.
Nhìn thấy và thay đổi các quyết định kiến trúc	Đưa ra chúng cho tốt: phân quyền, cách ly, khả năng quan sát, phục hồi sau lỗi
Không có chính sách đóng gói sẵn để phải chống lại	Tự cung cấp chính sách của riêng bạn, hoặc làm việc mà không có

Hệ thống công cụ là ví dụ rõ nhất. Pi cho bạn một bộ nguyên liệu nhỏ và chỗ để thêm của riêng bạn, và phần 11 lập luận rằng đó là một canh bạc chứ không phải một thiếu sót. Sản phẩm tích hợp không phải là đối lập của khả năng mở rộng. Chẳng hạn Claude Code có hook, skill, sub-agent, plugin và MCP, và Pi không phải không có tiện ích. Khác biệt là bao nhiêu thứ được quyết định sẵn cho bạn theo mặc định, và ai bảo trì nó.

13. Khi nào nên dùng Pi?

Làm việc với Pi khiến tôi ý thức hơn về một sự đánh đổi dễ bị bỏ qua: tự do chuyển trách nhiệm. Bạn càng kiểm soát nhiều một hệ thống, bạn càng phải đưa ra nhiều quyết định để biến sự kiểm soát đó thành một trải nghiệm làm việc đáng tin cậy. Chính tài liệu của Pi cũng nói đúng như vậy về phân quyền: nó bảo bạn tự mang container đến, và mô tả bốn cách để làm điều đó.

Vậy câu hỏi không phải là Pi có tốt hơn các coding agent khác hay không. Tôi chưa thử điều đó, và bài này không khẳng định gì về nó. Câu hỏi là sự tự do Pi đem lại có đáng với phần việc thêm mà bạn sẵn sàng nhận hay không. Tôi mở đầu bằng một model mạnh trong một môi trường mỏng. Môi trường mỏng ấy chính là lời đề nghị, và công việc lấp đầy nó là cái giá.

Tự do cho bạn khả năng xây hệ thống mình muốn. Tiện lợi giúp bạn tốn ít thời gian hơn cho việc xây hệ thống ngay từ đầu.

Tài liệu tham khảo

Pi: tài liệu chính thức và mã nguồn

• pi.dev, Sessions, Skills, Packages, Extensions, SDK, How Pi works, Security, Configuration, Settings, Compaction, CLI, Code Mode, Usage, RPC, Containerization, MCP, Quickstart
• earendil-works/pi: extensions.md, src/core/tools (gồm read.ts), agent-loop.ts, types.ts, hello.ts, tool-override.ts, path-utils.ts, utils/paths.ts
• Metadata của npm registry (npm view) cho @earendil-works/pi-coding-agent và @mariozechner/pi-coding-agent (đã deprecated), kiểm tra ngày 20/10/2026

Pi: bài viết của các tác giả

• Mario Zechner, What I learned building an opinionated and minimal coding agent, tháng 11/2025
• Earendil, You Said No MCP!, 29/09/2026

So sánh và tài liệu nền

• Claude Code, Tools reference, MCP (gồm tool search), Skills, Configure permissions và Permission modes
• OpenAI Codex, Customization, MCP, Agent approvals and security, và các tool handler mã nguồn mở trong openai/codex (commit e18a20d)
• Docker, Docker security